PHP Composer: Paket Kurma ve Sınıfları Otomatik Yükleme

Composer PHP'nin paket yöneticisidir. Proje klasörünüzde composer require vendor/package çalıştırın: Composer kütüphaneyi vendor/ içine indirir, composer.json içine kaydeder ve siz onu, kurduğunuz diğer her şeyle birlikte tek satırla yüklersiniz: require __DIR__ . '/vendor/autoload.php';.

composer require monolog/monolog

<?php
require __DIR__ . '/vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Level;

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Level::Warning));
$log->warning('Disk almost full', ['free' => '2%']);

Her dosya için include yok: otomatik yükleyici Logger, StreamHandler ve kullandıkları her şeyi, her sınıfa ilk ihtiyaç duyulduğunda yükler. Paketler Composer'ın varsayılan olarak aradığı herkese açık kayıt olan Packagist üzerinden gelir.

Composer kurulumu

Composer önce makinenizde PHP gerektirir (bkz. PHP kurulumu).

Windows: getcomposer.org adresinden Composer-Setup.exe dosyasını indirip çalıştırın. php.exe dosyanızı bulur ve composer komutunu PATH'e ekler. Ardından yeni bir terminal açın.

Homebrew ile macOS:

brew install composer

Linux: dağıtımınızın paketi (Debian ve Ubuntu'da sudo apt install composer) çalışır ama çoğu zaman eski bir sürümdür. Resmi yükleyici güncel olanı verir:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

getcomposer.org üzerindeki indirme sayfası ayrıca yükleyiciyi çalıştırmadan önce onun hash'ini kontrol eden bir satır gösterir; güncel hash'i almak için komutları oradan kopyalayın. Sonra çalıştığını kontrol edin:

composer --version

composer.json ve composer.lock

composer init birkaç soru sorar ve composer.json dosyasını yazar ya da composer require onu ilk pakette oluşturur. Tipik bir örnek:

{
    "name": "acme/shop",
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.0",
        "vlucas/phpdotenv": "^5.6"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

• require projenin çalışması için gerekenleri, PHP sürümü dahil, listeler.
• require-dev yalnızca geliştirme için araçları (testler, statik analiz) listeler. composer require --dev phpunit/phpunit buna ekler ve composer install --no-dev üretim sunucularında onu atlar.
• autoload Composer'a kendi sınıflarınızın nerede yaşadığını söyler (aşağıda).

Yanına Composer, paketlerinizin bağlı olduğu paketler dahil kurduğu her paketin tam sürümünü içeren composer.lock dosyasını yazar. İki dosyayı da commit edin. vendor/ klasörünü commit etmeyin: onu .gitignore dosyasına ekleyin, çünkü composer install onu kilit dosyasından yeniden oluşturur.

composer install ile composer update

composer install          # install exactly what composer.lock says
composer update           # pick the newest allowed versions, rewrite composer.lock
composer update monolog/monolog   # update one package only
composer remove monolog/monolog   # uninstall and remove from composer.json
composer outdated         # list packages with newer versions available

Bir projeyi klonladıktan sonra ve her dağıtımda composer install çalıştırın: herkes test edilmiş aynı sürümleri alır. composer update komutunu yalnızca yükseltmeyi amaçladığınızda çalıştırın, sonra test edin ve yeni composer.lock dosyasını commit edin. Bir üretim sunucusunda update çalıştırmak kimsenin test etmediği sürümleri kurar.

Sürüm kısıtları: ^ ve ~

Sürüm belirtmeden composer require vendor/package en yeni kararlı sürümü seçer ve onun için bir ^ kısıtı yazar; genellikle istediğiniz budur.

Kendi sınıflarınızı PSR-4 ile otomatik yükleme

PSR-4 bir isim alanını bir klasöre eşleyen kuraldır: "App\\": "src/" ile App\Text\Slug sınıfı src/Text/Slug.php dosyasında yaşar. autoload bölümünü ekledikten sonra şunu çalıştırın:

composer dump-autoload

Composer'ın otomatik yükleyicisi spl_autoload_register() ile kaydedilmiş bir fonksiyondur; PHP kod henüz yüklenmemiş bir sınıfı her kullandığında onu çağırır. Bu blok iki sınıf dosyası yazar ve kendine ait küçük bir PSR-4 otomatik yükleyici kaydeder, böylece eşlemenin çalıştığını izleyebilirsiniz. Üçüncü bir sınıf dosyası ekleyin ve onu kullanın.

<?php
// Two class files, laid out the PSR-4 way
is_dir('src/Text') || mkdir('src/Text', 0777, true);

file_put_contents('src/Greeter.php', <<<'PHP'
<?php
namespace App;

class Greeter
{
    public function hello(string $name): string
    {
        return "Hello, $name";
    }
}
PHP);

file_put_contents('src/Text/Slug.php', <<<'PHP'
<?php
namespace App\Text;

class Slug
{
    public static function from(string $title): string
    {
        return trim(preg_replace('/[^a-z0-9]+/', '-', strtolower($title)), '-');
    }
}
PHP);

// What vendor/autoload.php does for "App\\": "src/"
spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class => ", substr($file, strlen(__DIR__) + 1), "\n";
    if (is_file($file)) {
        require $file;
    }
});

echo (new App\Greeter())->hello('Ada'), "\n";
echo App\Text\Slug::from('Composer & PSR-4, Explained'), "\n";
echo App\Text\Slug::from('Loaded once, used twice'), "\n";

Otomatik yükleyici sınıf başına bir kez çalışır: ikinci Slug::from() çağrısı hiçbir autoload: satırı yazdırmaz, çünkü sınıf zaten yüklüdür. Gerçek bir projede bu fonksiyonu asla kendiniz yazmazsınız; vendor/autoload.php vendor/ içindeki paketleri de ele alan Composer sürümünü kaydeder. İsim alanları isim alanları sayfasında anlatılıyor.

Sık görülen hatalar

• Class "Monolog\Logger" not found. Betik require 'vendor/autoload.php' yapmadı ya da yol yanlış. Yol geçerli dizine bağlı olmasın diye __DIR__ . '/vendor/autoload.php' kullanın.
• Kendi sınıfınız autoload bölümüne ekledikten sonra bulunamıyor. composer dump-autoload çalıştırın ve dosya yolunun büyük küçük harf dahil isim alanıyla tam olarak eşleştiğini kontrol edin: App\Text\Slug src/Text/Slug.php olmalıdır ve Linux sunucuları src/text/slug.php dosyasını farklı bir dosya sayar.
• Your requirements could not be resolved to an installable set of packages. İki paket bir şeyin, çoğu zaman PHP'nin kendisinin, uyumsuz sürümlerine ihtiyaç duyuyor. Mesaj çakışmayı listeler; composer why-not vendor/package 2.0 bir sürümü neyin engellediğini açıklar.
• composer tanınmıyor. Terminal kurulumdan önce açılmış ya da klasör PATH içinde değil. Yeni bir terminal açın ya da doğrudan php composer.phar çağırın.