PHPのComposer：パッケージのインストールとオートロード

ComposerはPHPのパッケージマネージャーです。プロジェクトのフォルダーでcomposer require vendor/packageを実行すると、Composerがライブラリをvendor/にダウンロードしてcomposer.jsonに記録し、インストールしたほかのすべてと一緒に、1行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がロックファイルから作り直すので、.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は、コードがまだ読み込まれていないクラスを使うたびにそれを呼びます。このブロックは2つのクラスファイルを書き出し、独自の小さなPSR-4オートローダーを登録するので、対応づけが動くのを確認できます。3つ目のクラスファイルを加えて使ってみてください。

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

オートローダーはクラスごとに1回しか動きません。2回目のSlug::from()の呼び出しでは、クラスがすでに読み込まれているのでautoload:の行は出力されません。本物のプロジェクトでは、この関数を自分で書くことはありません。vendor/autoload.phpがComposerの版を登録し、それはvendor/の中のパッケージも扱います。名前空間については名前空間のページで扱っています。

よくあるエラー

• 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。 2つのパッケージが、何か（しばしばPHP自体）の互換性のないバージョンを必要としています。メッセージに衝突が並び、composer why-not vendor/package 2.0はどのバージョンが何に妨げられているかを説明します。
• composerが認識されない。 インストールする前にターミナルを開いたか、フォルダーがPATHに入っていません。新しいターミナルを開くか、php composer.pharを直接呼びましょう。