Composer

• Composer
• 認証が必要なリポジトリを使う場合
• create-project
• トラブルシューティング

前提: Composer 2.x を対象とします。

Composer

Composer は PHP のパッケージ（依存ライブラリ）管理ツールです。

Composer インストール

公式ドキュメントの手順に従ってインストールします。 インストーラーはハッシュ検証つきのスクリプトが案内されており、ハッシュ値は更新されるため、最新の値は公式ページで確認してください。

• Download Composer

手順の概要は次のとおりです(<公式ページ記載のハッシュ> は置き換えてください)。

$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php -r "if (hash_file('sha384', 'composer-setup.php') === '<公式ページ記載のハッシュ>') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
$ php composer-setup.php
$ php -r "unlink('composer-setup.php');"

composer.phar がカレントディレクトリに作成されます。

# 動作確認
$ php composer.phar --version

パスの通っているディレクトリ(例 /usr/local/bin)へ composer という名前で移動すると、どのディレクトリからでも composer コマンドで実行できます。

$ sudo mv composer.phar /usr/local/bin/composer
$ composer --version

インストール時にディレクトリとファイル名を指定することもできます。

$ php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Composer 自体をアップデート

$ composer self-update

Composer 初期化

$ composer init

対話的に composer.json を作成できます。

composer.json の例:

{
    "require": {
        "monolog/monolog": "^3.0"
    }
}

monolog/monolog 3.x は PHP 8.1 以上が必要です。利用する PHP のバージョンに合わせて制約を調整してください。

composer install

install コマンドでパッケージをインストールします。

$ composer install

composer install は次の処理を行います。

1. composer.lock が存在する場合は、その内容どおりのバージョンを vendor ディレクトリにインストールします
2. composer.lock が存在しない場合は、composer.json をもとに依存関係を解決してインストールし、composer.lock を作成します

vendor/autoload.php が作成され、オートロードが利用できます。

composer update

パッケージをアップデートします。

# すべてのパッケージをアップデート
$ composer update
# 特定のパッケージだけアップデート
$ composer update foo/bar

composer update は composer.json に指定した範囲内で最新のバージョンをインストールし、composer.lock を更新します。

特定のパッケージだけを指定した場合、指定していないパッケージは composer.lock に記載されたバージョンのまま維持されます。 既定では、指定したパッケージの依存パッケージは更新されません。依存パッケージも更新するときは次のオプションを使います。

オプション	動作
-w / --with-dependencies	指定パッケージの依存パッケージも更新(ルートの require に書かれたものは除く)
-W / --with-all-dependencies	指定パッケージの依存パッケージをすべて更新

update で composer.json に記載された範囲より上のバージョンをインストール

1. composer.json の該当パッケージのバージョン指定を上げます
2. $ composer update foo/bar を実行します

composer require foo/bar:^2.0 のように、require でバージョン制約を書き換えて更新する方法もあります。

install と update の違い

composer.lock が存在するときの挙動が異なります。

• install
  • composer.lock に記載されたバージョンをインストールします
  • composer.lock が存在しないときは composer.json をもとにインストールし、composer.lock を作成します
• update
  • composer.lock のバージョンに縛られず、composer.json に記載の範囲で最新のバージョンを解決します
  • 結果を composer.lock に書き込みます

チーム開発や本番デプロイでは、composer.lock をコミットし、composer install を使うのが基本です。

パッケージ追加

# 通常パッケージを追加
$ composer require vendor/package

composer require はパッケージのインストールを行い、composer.json(の require)への追記と composer.lock の更新も行います。

# 開発でのみ必要なパッケージを追加
$ composer require --dev vendor/package

composer require --dev は開発環境でのみ必要なパッケージを追加し、composer.json の require-dev へ追記します。

install / update は、既定で require-dev のパッケージもインストール / アップデートします(--dev オプションは非推奨で、指定しても動作は変わりません)。 require-dev パッケージをインストールしないとき(本番環境など)は --no-dev オプションを指定します。

$ composer install --no-dev

個別パッケージを追加(その他パッケージは変更しない)

新規追加パッケージ以外の composer.lock の内容を変更しないようにパッケージを追加します。

$ composer require foo/bar

composer require は、追加するパッケージとその依存パッケージのみを解決対象とし、既存のパッケージは可能な限り composer.lock のバージョンを維持します。

composer.json にパッケージを直接書き足した場合は、次の手順にします。

1. composer.json にパッケージを追加します(例: foo/bar パッケージを追加)
2. $ composer update foo/bar を実行します(バージョンは指定せず、composer.json の制約に従わせます)
3. composer.json, composer.lock をコミットします

バージョン制約を composer update のコマンドラインで直接指定する形(composer update foo/bar:^1.1)は避けてください。composer.json の制約と食い違い、意図しない状態になりやすいためです。 一時的に制約を追加したいときは、Composer 2 の --with オプションを使います。

$ composer update --with foo/bar:^1.1

パッケージインストール場所

デフォルトは composer.json と同階層に vendor ディレクトリを作成します。 上述の composer.json の例では次のようになります。

.
|-- composer.json
|-- composer.lock
`-- vendor
    |-- autoload.php
    `-- monolog
        `-- monolog

インストール済みパッケージ一覧を確認

$ composer show

composer.json で require したパッケージ(直接の依存)のみ表示するには --direct(-D)を指定します。

$ composer show --direct

Composer 1 系で使われていた composer show -i は、Composer 2 では非推奨です。

バージョンの指定

主なバージョン制約の書き方です。

記法	意味
1.2.3	1.2.3 のみ
1.0.*	>=1.0.0 <1.1.0
~1.2	>=1.2 <2.0
~1.2.3	>=1.2.3 <1.3.0
^1.2.3	>=1.2.3 <2.0.0

詳細は公式ドキュメントを参照してください。

• Versions and constraints

Scripts

Composer には、インストールや更新などのイベントに合わせて、あるいは独自のコマンドとして任意のスクリプトを実行する仕組みがあります。

• Scripts

スクリプトを実行せずにインストールするときは --no-scripts を指定します。

$ composer install --no-scripts

認証が必要なリポジトリを使う場合

プライベートリポジトリや、GitHub のようにレート制限のあるサービスを利用する場合は、認証情報を設定します。 Composer の設定は composer config コマンドを使います。

• Authentication for privately hosted packages and repositories

Basic 認証

Basic 認証を設定する方法は次のとおりです。

$ composer config -g http-basic.example.com foo bar

上記コマンドを実行すると、Composer のホームディレクトリ配下に auth.json ファイルが作成されます。

{
    "http-basic": {
        "example.com": {
            "username": "foo",
            "password": "bar"
        }
    }
}

auth.json の場所は環境によって異なります(例: ~/.composer/auth.json, ~/.config/composer/auth.json)。 次のコマンドで Composer のホームディレクトリを確認できます。

$ composer config --global home

注意: auth.json にはパスワードやトークンが平文で保存されます。 プロジェクト直下の auth.json にトークンを書く場合は、リポジトリへコミットしないでください(.gitignore に追加します)。 個人の認証情報は、-g オプションでグローバル設定として保存するのが安全です。

Personal Access Token

GitHub からパッケージを取得する際、短時間に大量のリクエストを送ると GitHub API のレート制限に達することがあります。 その場合、Composer が GitHub のトークンの入力を求めます。 Personal Access Token を事前に設定しておくと、認証済みのリクエストとなり制限が緩和されます。

Personal Access Token は次のページから生成できます。

• Personal Access Tokens

$ composer config -g github-oauth.github.com <token>

Composer に限らず、大量のリクエストを送るアプリケーション(例: Homebrew など)でも、同様に Personal Access Token の設定が必要になることがあります。

• Managing your personal access tokens (GitHub Docs)

create-project

create-project もバージョン指定が可能です。

$ composer create-project vendor/skeleton:1.1.5 my-project

トラブルシューティング

Symfony Flex のプラグインインストール失敗

次のエラーが発生する場合があります。

symfony flex 1.2.7 Plugin installation failed (Invalid version string "5.x")

古い symfony/flex と Composer 本体のバージョンの不整合が原因のことがあります。まず次を試してください。

$ composer self-update
$ composer update symfony/flex

解消しない場合は、次の手順で composer.lock を作り直します。

注意: composer.lock を削除して composer install すると、composer.json の範囲内で全パッケージが最新バージョンに更新されます。 意図しないバージョンアップが起こるため、動作確認を行ってください。

1. ローカル環境の vendor ディレクトリを削除します
2. ローカル環境の composer.lock を削除します
3. ローカル環境で $ composer install を実行します
4. 動作確認後、新しい composer.lock をコミットして Push します