Composer: Kullanım İpuçları
***************************

<div class=perex>

Composer, PHP'de bağımlılıkları yönetmek için bir araçtır. Projemizin bağlı olduğu kütüphaneleri listelememize olanak tanır ve bunları bizim için kurar ve günceller. Şunları göstereceğiz:

- Composer nasıl kurulur
- yeni veya mevcut bir projede kullanımı

</div>


Kurulum
=======

Composer, aşağıdaki şekilde indirip kuracağınız çalıştırılabilir bir `.phar` dosyasıdır:


Windows
-------

Resmi [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe] yükleyicisini kullanın.


Linux, macOS
------------

[Bu sayfadan |https://getcomposer.org/download/] kopyalayacağınız sadece 4 komut yeterlidir.

Ayrıca, sistem `PATH`'inde bulunan bir klasöre yerleştirerek, Composer genel olarak erişilebilir hale gelir:

```shell
$ mv ./composer.phar ~/bin/composer # veya /usr/local/bin/composer
```


Projede Kullanım
================

Projemizde Composer kullanmaya başlamak için yalnızca `composer.json` dosyasına ihtiyacımız var. Bu dosya projemizin bağımlılıklarını tanımlar ve ayrıca ek meta veriler içerebilir. Temel bir `composer.json` dosyası şöyle görünebilir:

```js
{
	"require": {
		"nette/database": "^3.0"
	}
}
```

Burada uygulamamızın (veya kütüphanemizin) `nette/database` paketini (paket adı kuruluş adı ve proje adından oluşur) gerektirdiğini ve `^3.0` koşuluna uyan sürümü (yani en son 3 sürümünü) istediğini söylüyoruz.

Yani projenin kökünde `composer.json` dosyamız var ve kurulumu başlatıyoruz:

```shell
composer update
```

Composer, Nette Database'i `vendor/` klasörüne indirecektir. Ayrıca, tam olarak hangi kütüphane sürümlerini kurduğu hakkında bilgi içeren `composer.lock` dosyasını oluşturacaktır.

Composer, `vendor/autoload.php` dosyasını oluşturur, bunu basitçe dahil edebilir ve başka herhangi bir iş yapmadan kütüphaneleri kullanmaya başlayabiliriz:

```php
require __DIR__ . '/vendor/autoload.php';

$db = new Nette\Database\Connection('sqlite::memory:');
```


Paketleri En Son Sürümlere Güncelleme
=====================================

Kullanılan kütüphaneleri `composer.json`'da tanımlanan koşullara göre en son sürümlere güncellemek `composer update` komutunun sorumluluğundadır. Örneğin, `"nette/database": "^3.0"` bağımlılığı için en son 3.x.x sürümünü kurar, ancak 4 sürümünü kurmaz.

En son sürümü kurabilmek için `composer.json` dosyasındaki koşulları örneğin `"nette/database": "^4.1"` olarak güncellemek için `composer require nette/database` komutunu kullanın.

Kullanılan tüm Nette paketlerini güncellemek için hepsini komut satırında listelemek gerekirdi, örn.:

```shell
composer require nette/application nette/forms latte/latte tracy/tracy ...
```

Bu pratik değildir. Bu yüzden bunu sizin için yapacak basit "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff betiğini kullanın:

```shell
php composer-frontline.php
```


Yeni Proje Oluşturma
====================

Nette üzerinde yeni bir proje tek bir komutla oluşturulur:

```shell
composer create-project nette/web-project proje-adi
```

`proje-adi` olarak projeniz için dizin adını girin ve onaylayın. Composer, zaten `composer.json` dosyasını içeren `nette/web-project` deposunu GitHub'dan indirecek ve hemen ardından Nette Framework'ü indirecektir. Artık yalnızca `temp/` ve `log/` klasörlerine yazma [izinlerini ayarlamak |nette:troubleshooting#nastaveni-prav-adresaru] yeterli olmalı ve proje canlanmalıdır.

Projenin hangi PHP sürümünde barındırılacağını biliyorsanız, [onu ayarlamayı |#Verze PHP] unutmayın.


PHP Sürümü
==========

Composer her zaman kullandığınız PHP sürümüyle uyumlu paket sürümlerini kurar (daha doğrusu Composer'ı çalıştırırken komut satırında kullanılan PHP sürümüyle). Ancak bu muhtemelen barındırma hizmetinizin kullandığı sürümle aynı değildir. Bu nedenle, barındırmadaki PHP sürümü hakkındaki bilgiyi `composer.json` dosyasına eklemek çok önemlidir. Ardından yalnızca barındırma ile uyumlu paket sürümleri kurulacaktır.

Projenin örneğin PHP 8.2.3 üzerinde çalışacağını şu komutla ayarlarız:

```shell
composer config platform.php 8.2.3
```

Sürüm `composer.json` dosyasına şu şekilde yazılır:

```js
{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}
```

Ancak, PHP sürüm numarası dosyanın başka bir yerinde, `require` bölümünde de belirtilir. İlk sayı, paketlerin hangi sürüm için kurulacağını belirlerken, ikinci sayı uygulamanın kendisinin hangi sürüm için yazıldığını söyler. Ve örneğin PhpStorm, *PHP dil seviyesini* buna göre ayarlar. (Elbette bu sürümlerin farklı olmasının bir anlamı yoktur, bu yüzden çift kayıt düşüncesizliktir.) Bu sürümü şu komutla ayarlarsınız:

```shell
composer require php 8.2.3 --no-update
```

Veya doğrudan `composer.json` dosyasında:

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


PHP Sürümünü Yoksayma
=====================

Paketler genellikle hem uyumlu oldukları en düşük PHP sürümünü hem de test edildikleri en yüksek sürümü belirtirler. Henüz daha yeni bir PHP sürümü kullanmayı planlıyorsanız, örneğin test amacıyla, Composer böyle bir paketi kurmayı reddedecektir. Çözüm, Composer'ın gerekli PHP sürümünün üst sınırlarını yoksaymasına neden olan `--ignore-platform-req=php+` seçeneğidir.


Yanıltıcı Bildirimler
=====================

Paketleri yükseltirken veya sürüm numaralarını değiştirirken çakışmalar meydana gelebilir. Bir paket, başka bir paketle çelişen gereksinimlere sahip olabilir vb. Ancak Composer bazen yanıltıcı bildirimler yazdırır. Gerçekte var olmayan bir çakışma bildirir. Bu durumda, `composer.lock` dosyasını silmek ve tekrar denemek yardımcı olur.

Hata mesajı devam ederse, ciddiye alınmalı ve neyin nasıl ayarlanacağını anlamak için okunmalıdır.


Packagist.org - Merkezi Depo
============================

[Packagist |https://packagist.org], Composer'ın aksi belirtilmedikçe paketleri aramaya çalıştığı ana depodur. Burada kendi paketlerimizi de yayınlayabiliriz.


Merkezi Depoyu Kullanmak İstemezsek Ne Olur?
--------------------------------------------

Şirket içi uygulamalarımız varsa ve bunları kamuya açık olarak barındıramıyorsak, onlar için bir şirket deposu oluştururuz.

Depolar hakkında daha fazla bilgi [resmi belgelerde |https://getcomposer.org/doc/05-repositories.md#repositories].


Otomatik Yükleme (Autoloading)
==============================

Composer'ın temel bir özelliği, kurduğu tüm sınıflar için otomatik yükleme sağlamasıdır; bunu `vendor/autoload.php` dosyasını dahil ederek başlatırsınız.

Ancak, Composer'ı `vendor` klasörü dışındaki diğer sınıfları yüklemek için de kullanmak mümkündür. İlk seçenek, Composer'ın tanımlanmış klasörleri ve alt klasörleri taramasını, tüm sınıfları bulmasını ve bunları otomatik yükleyiciye dahil etmesini sağlamaktır. Bunu `composer.json`'da `autoload > classmap` ayarlayarak başarırsınız:

```js
{
	"autoload": {
		"classmap": [
			"src/",      # src/ klasörünü ve alt klasörlerini dahil eder
		]
	}
}
```

Ardından, her değişiklikte `composer dumpautoload` komutunu çalıştırmak ve otomatik yükleme tablolarını yeniden oluşturmak gerekir. Bu son derece zahmetlidir ve bu görevi aynı işlemi arka planda otomatik olarak ve çok daha hızlı gerçekleştiren [RobotLoader|robot-loader:]'a devretmek çok daha iyidir.

İkinci seçenek [PSR-4|https://www.php-fig.org/psr/psr-4/]'e uymaktır. Basitçe ifade etmek gerekirse, bu, isim alanlarının ve sınıf adlarının dizin yapısına ve dosya adlarına karşılık geldiği bir sistemdir, yani örn. `App\Core\RouterFactory`, `/path/to/App/Core/RouterFactory.php` dosyasında olacaktır. Yapılandırma örneği:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # App\ isim alanı app/ dizinindedir
		}
	}
}
```

Davranışın tam olarak nasıl yapılandırılacağını [Composer belgelerinde|https://getcomposer.org/doc/04-schema.md#psr-4] öğrenebilirsiniz.


Yeni Sürümleri Test Etme
========================

Bir paketin yeni bir geliştirme sürümünü test etmek istiyorsunuz. Nasıl yapılır? Öncelikle `composer.json` dosyasına, paketlerin geliştirme sürümlerinin kurulmasına izin veren, ancak yalnızca gereksinimleri karşılayan kararlı sürüm kombinasyonu yoksa buna başvuran şu çift seçeneği ekleyin:

```js
{
	"minimum-stability": "dev",
	"prefer-stable": true,
}
```

Ayrıca `composer.lock` dosyasını silmenizi öneririz, bazen Composer anlaşılmaz bir şekilde kurulumu reddeder ve bu sorunu çözer.

Diyelim ki paket `nette/utils` ve yeni sürümün numarası 4.0. Şu komutla kurarsınız:

```shell
composer require nette/utils:4.0.x-dev
```

Veya belirli bir sürümü kurabilirsiniz, örneğin 4.0.0-RC2:

```shell
composer require nette/utils:4.0.0-RC2
```

Ancak kütüphaneye daha eski bir sürüme kilitlenmiş başka bir paket bağlıysa (örn. `^3.1`), o zaman paketi yeni sürümle çalışacak şekilde güncellemek idealdir. Ancak yalnızca kısıtlamayı aşmak ve Composer'ı geliştirme sürümünü kurmaya ve daha eski bir sürüm (örn. 3.1.6) gibi davranmaya zorlamak istiyorsanız, `as` anahtar kelimesini kullanabilirsiniz:

```shell
composer require nette/utils "4.0.x-dev as 3.1.6"
```


Komutları Çağırma
=================

Composer aracılığıyla, sanki yerel Composer komutlarıymış gibi kendi önceden hazırlanmış komutlarınızı ve betiklerinizi çağırabilirsiniz. `vendor/bin` klasöründe bulunan betikler için bu klasörü belirtmeye gerek yoktur.

Örnek olarak, `composer.json` dosyasında [Nette Tester|tester:] kullanarak testleri çalıştıran bir betik tanımlayalım:

```js
{
	"scripts": {
		"tester": "tester tests -s"
	}
}
```

Testleri daha sonra `composer tester` kullanarak çalıştırırız. Komutu, projenin kök klasöründe olmasak bile, bazı alt dizinlerde olsak bile çağırabiliriz.


Teşekkür Gönderin
=================

Size açık kaynak yazarlarını memnun edecek bir numara göstereceğiz. Projenizin kullandığı kütüphanelere GitHub'da basit bir şekilde yıldız verebilirsiniz. Sadece `symfony/thanks` kütüphanesini kurmanız yeterlidir:

```shell
composer global require symfony/thanks
```

Ve sonra çalıştırın:

```shell
composer thanks
```

Deneyin!


Yapılandırma
============

Composer, [Git |https://git-scm.com] sürüm kontrol aracıyla yakından bağlantılıdır. Eğer kurulu değilse, Composer'a onu kullanmamasını söylemeniz gerekir:

```shell
composer -g config preferred-install dist
```

{{sitename: Best Practices}}