Composer w PHP: instalacja pakietów i autoload klas

Composer to menedżer pakietów dla PHP. Uruchom composer require vendor/package w folderze projektu: Composer pobiera bibliotekę do vendor/, zapisuje ją w composer.json, a ty wczytujesz ją, razem ze wszystkim, co zainstalowałeś, jedną linią, 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%']);

Żadnego include dla każdego pliku: autoloader wczytuje Logger, StreamHandler i wszystko, czego używają, przy pierwszym zapotrzebowaniu na każdą klasę. Pakiety pochodzą z Packagist, publicznego rejestru, który Composer domyślnie przeszukuje.

Instalacja Composera

Composer najpierw wymaga PHP na twojej maszynie (zobacz instalacja PHP).

Windows: pobierz i uruchom Composer-Setup.exe z getcomposer.org. Znajduje twój php.exe i dodaje composer do PATH. Potem otwórz nowy terminal.

macOS z Homebrew:

brew install composer

Linux: pakiet twojej dystrybucji (sudo apt install composer w Debianie i Ubuntu) działa, ale często jest to starsze wydanie. Oficjalny instalator daje bieżące:

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

Strona pobierania na getcomposer.org pokazuje też linię, która sprawdza hash instalatora przed jego uruchomieniem; skopiuj polecenia stamtąd, żeby mieć aktualny hash. Potem sprawdź, czy działa:

composer --version

composer.json i composer.lock

composer init zadaje kilka pytań i zapisuje composer.json, albo tworzy go composer require przy pierwszym pakiecie. Typowy plik:

{
    "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 wymienia to, czego projekt potrzebuje do działania, łącznie z wersją PHP.
• require-dev wymienia narzędzia tylko do pracy deweloperskiej (testy, analiza statyczna). composer require --dev phpunit/phpunit dodaje do tej sekcji, a composer install --no-dev pomija ją na serwerach produkcyjnych.
• autoload mówi Composerowi, gdzie leżą twoje własne klasy (niżej).

Obok Composer zapisuje composer.lock z dokładną wersją każdego zainstalowanego pakietu, łącznie z pakietami, od których zależą twoje pakiety. Commituj oba pliki. Nie commituj vendor/: dodaj go do .gitignore, bo composer install odbudowuje go z pliku lock.

composer install vs 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

Uruchamiaj composer install po sklonowaniu projektu i przy każdym wdrożeniu: wszyscy dostają te same, przetestowane wersje. composer update uruchamiaj tylko wtedy, gdy zamierzasz aktualizować, a potem przetestuj i zacommituj nowy composer.lock. Uruchomienie update na serwerze produkcyjnym instaluje wersje, których nikt nie przetestował.

Ograniczenia wersji: ^ i ~

composer require vendor/package bez wersji wybiera najnowsze stabilne wydanie i zapisuje dla niego ograniczenie ^, co zwykle jest tym, czego chcesz.

Autoload własnych klas przez PSR-4

PSR-4 to konwencja przypisująca przestrzeń nazw do folderu: z "App\\": "src/" klasa App\Text\Slug leży w src/Text/Slug.php. Po dodaniu sekcji autoload uruchom:

composer dump-autoload

Autoloader Composera to funkcja zarejestrowana przez spl_autoload_register(), którą PHP wywołuje zawsze, gdy kod używa klasy, która nie jest jeszcze wczytana. Ten blok zapisuje dwa pliki klas i rejestruje własny mały autoloader PSR-4, żebyś mógł zobaczyć działanie mapowania. Dodaj trzeci plik klasy i go użyj.

<?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";

Autoloader uruchamia się raz na klasę: drugie wywołanie Slug::from() nie wypisuje linii autoload:, bo klasa jest już wczytana. W prawdziwym projekcie nigdy nie piszesz tej funkcji sam; vendor/autoload.php rejestruje wersję Composera, która obsługuje też pakiety w vendor/. Przestrzenie nazw opisuje strona o przestrzeniach nazw.

Częste błędy

• Class "Monolog\Logger" not found. Skrypt nie wykonał require 'vendor/autoload.php' albo ścieżka jest błędna. Używaj __DIR__ . '/vendor/autoload.php', żeby ścieżka nie zależała od bieżącego katalogu.
• Twoja własna klasa nie jest znajdowana po dodaniu do autoload. Uruchom composer dump-autoload i sprawdź, czy ścieżka pliku dokładnie odpowiada przestrzeni nazw, łącznie z wielkością liter: App\Text\Slug musi być w src/Text/Slug.php, a serwery z Linuksem traktują src/text/slug.php jako inny plik.
• Your requirements could not be resolved to an installable set of packages. Dwa pakiety potrzebują niezgodnych wersji czegoś, często samego PHP. Komunikat wymienia konflikt; composer why-not vendor/package 2.0 wyjaśnia, co blokuje daną wersję.
• composer nie jest rozpoznawany. Terminal został otwarty przed instalacją albo folder nie jest w PATH. Otwórz nowy terminal albo wywołaj bezpośrednio php composer.phar.