Composer trong PHP: cài package và autoload class

Composer là trình quản lý package cho PHP. Chạy composer require vendor/package trong thư mục dự án: Composer tải thư viện vào vendor/, ghi nó vào composer.json, và bạn nạp thư viện đó, cùng mọi thứ khác đã cài, chỉ bằng một dòng 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%']);

Không cần include cho từng tệp: autoloader nạp Logger, StreamHandler và mọi thứ chúng dùng vào lần đầu mỗi class được cần đến. Package được lấy từ Packagist, kho package công khai mà Composer tìm kiếm mặc định.

Cài đặt Composer

Composer cần có PHP trên máy trước (xem cài đặt PHP).

Windows: tải và chạy Composer-Setup.exe từ getcomposer.org. Trình cài đặt tự tìm php.exe và thêm composer vào PATH. Sau đó mở một terminal mới.

macOS với Homebrew:

brew install composer

Linux: package của bản phân phối (sudo apt install composer trên Debian và Ubuntu) dùng được nhưng thường là bản cũ. Trình cài đặt chính thức cho bạn bản mới nhất:

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

Trang tải về trên getcomposer.org còn có một dòng lệnh kiểm tra mã hash của trình cài đặt trước khi chạy; hãy sao chép các lệnh từ đó để có mã hash hiện tại. Sau đó kiểm tra xem Composer đã chạy được chưa:

composer --version

composer.json và composer.lock

composer init hỏi vài câu rồi ghi ra composer.json, hoặc composer require tự tạo tệp này khi bạn cài package đầu tiên. Một tệp điển hình:

{
    "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 liệt kê những gì dự án cần để chạy, kể cả phiên bản PHP.
• require-dev liệt kê các công cụ chỉ dùng khi phát triển (kiểm thử, phân tích tĩnh). composer require --dev phpunit/phpunit thêm vào mục này, còn composer install --no-dev bỏ qua nó trên máy chủ production.
• autoload cho Composer biết class của bạn nằm ở đâu (xem bên dưới).

Bên cạnh đó, Composer ghi ra composer.lock với phiên bản chính xác của mọi package đã cài, kể cả những package mà các package của bạn phụ thuộc vào. Hãy commit cả hai tệp. Đừng commit vendor/: thêm nó vào .gitignore, vì composer install dựng lại thư mục này từ tệp lock.

composer install và 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

Chạy composer install sau khi clone một dự án và mỗi lần triển khai: ai cũng có đúng các phiên bản đã được kiểm thử. Chỉ chạy composer update khi bạn định nâng cấp, sau đó kiểm thử và commit composer.lock mới. Chạy update trên máy chủ production sẽ cài những phiên bản chưa ai kiểm thử.

Ràng buộc phiên bản: ^ và ~

composer require vendor/package không kèm phiên bản sẽ chọn bản ổn định mới nhất và ghi ràng buộc ^ cho nó, thường là đúng thứ bạn cần.

Autoload class của bạn với PSR-4

PSR-4 là quy ước ánh xạ một namespace tới một thư mục: với "App\\": "src/", class App\Text\Slug nằm trong src/Text/Slug.php. Sau khi thêm mục autoload, chạy:

composer dump-autoload

Autoloader của Composer là một hàm được đăng ký bằng spl_autoload_register(), PHP gọi nó mỗi khi code dùng một class chưa được nạp. Khối code này ghi ra hai tệp class và đăng ký một autoloader PSR-4 nhỏ của riêng nó, để bạn thấy phép ánh xạ hoạt động. Hãy thêm một tệp class thứ ba và dùng thử.

<?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 chạy một lần cho mỗi class: lời gọi Slug::from() thứ hai không in ra dòng autoload: nào, vì class đã được nạp. Trong dự án thật, bạn không bao giờ tự viết hàm này; vendor/autoload.php đăng ký phiên bản của Composer, phiên bản đó còn xử lý cả các package trong vendor/. Namespace được trình bày ở trang namespace.

Các lỗi thường gặp

• Class "Monolog\Logger" not found. Script chưa require 'vendor/autoload.php', hoặc đường dẫn sai. Dùng __DIR__ . '/vendor/autoload.php' để đường dẫn không phụ thuộc vào thư mục hiện tại.
• Không tìm thấy class của bạn sau khi đã thêm vào autoload. Chạy composer dump-autoload, và kiểm tra đường dẫn tệp có khớp chính xác với namespace không, kể cả chữ hoa và chữ thường: App\Text\Slug phải là src/Text/Slug.php, và máy chủ Linux coi src/text/slug.php là một tệp khác.
• Your requirements could not be resolved to an installable set of packages. Hai package cần những phiên bản không tương thích của cùng một thứ, thường là chính PHP. Thông báo lỗi liệt kê xung đột; composer why-not vendor/package 2.0 giải thích điều gì đang chặn một phiên bản.
• Không nhận ra lệnh composer. Terminal được mở trước khi cài, hoặc thư mục chưa có trong PATH. Mở một terminal mới, hoặc gọi trực tiếp php composer.phar.