PHP Composer: 패키지 설치와 클래스 오토로드

Composer는 PHP의 패키지 관리자입니다. 프로젝트 폴더에서 composer require vendor/package를 실행하세요. Composer가 라이브러리를 vendor/에 내려받고 composer.json에 기록하며, 여러분은 그것을 설치한 다른 모든 것과 함께 한 줄로 불러옵니다: 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%']);

파일마다 include할 필요가 없습니다. 오토로더가 Logger, StreamHandler와 그것들이 쓰는 모든 것을 각 클래스가 처음 필요할 때 불러옵니다. 패키지는 Composer가 기본으로 검색하는 공개 저장소 Packagist에서 옵니다.

Composer 설치하기

Composer는 먼저 컴퓨터에 PHP가 있어야 합니다(PHP 설치 참고).

Windows: getcomposer.org에서 Composer-Setup.exe를 내려받아 실행하세요. php.exe를 찾고 composer를 PATH에 추가합니다. 그다음 새 터미널을 여세요.

macOS에서 Homebrew로:

brew install composer

Linux: 배포판의 패키지(Debian과 Ubuntu에서는 sudo apt install composer)도 동작하지만 오래된 릴리스인 경우가 많습니다. 공식 설치 프로그램은 최신 버전을 줍니다.

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의 다운로드 페이지는 실행하기 전에 설치 프로그램의 해시를 확인하는 줄도 보여 줍니다. 최신 해시를 얻으려면 명령을 거기서 복사하세요. 그다음 동작하는지 확인하세요.

composer --version

composer.json과 composer.lock

composer init은 몇 가지를 묻고 composer.json을 쓰며, 또는 첫 패키지에서 composer require가 그것을 만듭니다. 일반적인 예입니다.

{
    "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는 PHP 버전을 포함해 프로젝트를 실행하는 데 필요한 것을 나열합니다.
• require-dev는 개발에만 쓰는 도구(테스트, 정적 분석)를 나열합니다. composer require --dev phpunit/phpunit이 여기에 추가하고, composer install --no-dev는 운영 서버에서 이것을 건너뜁니다.
• autoload는 직접 만든 클래스가 어디에 있는지 Composer에 알려 줍니다(아래 참고).

그 옆에 Composer는 설치한 모든 패키지의 정확한 버전을, 패키지가 의존하는 패키지까지 포함해 composer.lock에 씁니다. 두 파일 모두 커밋하세요. vendor/는 커밋하지 마세요. composer install이 lock 파일로 다시 만들므로 .gitignore에 추가하세요.

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

프로젝트를 클론한 뒤와 매 배포 때 composer install을 실행하세요. 모두가 테스트된 같은 버전을 받습니다. composer update는 업그레이드할 의도가 있을 때만 실행하고, 그다음 테스트하고 새 composer.lock을 커밋하세요. 운영 서버에서 update를 실행하면 아무도 테스트하지 않은 버전이 설치됩니다.

버전 제약: ^와 ~

버전 없이 composer require vendor/package를 쓰면 최신 안정 릴리스를 골라 ^ 제약을 써 주며, 보통 원하는 결과입니다.

PSR-4로 직접 만든 클래스 오토로드하기

PSR-4는 네임스페이스를 폴더에 대응시키는 규약입니다. "App\\": "src/"라면 클래스 App\Text\Slug는 src/Text/Slug.php에 있습니다. autoload 섹션을 추가한 뒤 다음을 실행하세요.

composer dump-autoload

Composer의 오토로더는 spl_autoload_register()로 등록한 함수이며, 코드가 아직 불러오지 않은 클래스를 쓸 때마다 PHP가 호출합니다. 이 블록은 클래스 파일 두 개를 쓰고 자체적인 작은 PSR-4 오토로더를 등록하므로 대응 관계가 동작하는 것을 볼 수 있습니다. 세 번째 클래스 파일을 추가하고 써 보세요.

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

오토로더는 클래스마다 한 번 실행됩니다. 두 번째 Slug::from() 호출은 클래스가 이미 불러와졌으므로 autoload: 줄을 출력하지 않습니다. 실제 프로젝트에서는 이 함수를 직접 쓰지 않습니다. vendor/autoload.php가 vendor/의 패키지도 처리하는 Composer의 버전을 등록합니다. 네임스페이스는 네임스페이스 페이지에서 다룹니다.

흔한 에러

• Class "Monolog\Logger" not found. 스크립트가 require 'vendor/autoload.php'를 하지 않았거나 경로가 틀렸습니다. 경로가 현재 디렉터리에 의존하지 않도록 __DIR__ . '/vendor/autoload.php'를 쓰세요.
• autoload에 추가한 뒤에도 직접 만든 클래스를 찾지 못함. composer dump-autoload를 실행하고, 파일 경로가 대소문자까지 네임스페이스와 정확히 일치하는지 확인하세요. App\Text\Slug는 src/Text/Slug.php여야 하며, Linux 서버는 src/text/slug.php를 다른 파일로 취급합니다.
• Your requirements could not be resolved to an installable set of packages. 두 패키지가 무언가의 서로 호환되지 않는 버전을 필요로 하며, PHP 자체인 경우가 많습니다. 메시지가 충돌을 나열하고, composer why-not vendor/package 2.0이 무엇이 그 버전을 막는지 설명합니다.
• composer를 인식할 수 없음. 설치 전에 연 터미널이거나 폴더가 PATH에 없습니다. 새 터미널을 열거나 php composer.phar를 직접 호출하세요.