基本的な使い方

導入

基礎的な使い方の導入として、ここではログライブラリであるmonolog/monologをインストールします。まだComposerをインストールしていなければ、はじめに章を参照してください。

補足： 簡潔のために、この導入ではComposerのローカルインストールを実施した前提で進めます。

プロジェクトでComposerを使い始めるにあたって必要なのはcomposer.jsonファイルだけです。このファイルにはプロジェクトの依存関係が記述され、他のメタデータも含まれることがあります。大抵プロジェクトやVCSリポジトリの最上位ディレクトリにあります。技術的にはComposerをどこで実行することもできますが、パッケージをPackagist.orgに公開したいならば、VCSリポジトリの一番上の階層にファイルがなければなりません。

`require`キー

最初にcomposer.jsonで指定するものは、requireキーです。 Composerにプロジェクトが依存しているパッケージがどれであるかを伝えるものです。

{
    "require": {
        "monolog/monolog": "2.0.*"
    }
}

見ての通り、requireはパッケージ名（例：monolog/monolog）と パッケージバージョン（例：1.0.*）を対応付けるオブジェクトを取ります。

Composerはこの情報を使って、repositoriesキーからパッケージ「リポジトリ」や、既定のパッケージレジストリであるPackagist.orgにある正しいファイル一式を探します。上の例ではこれといったリポジトリはcomposer.jsonファイルに登録されていないので、monolog/monologパッケージはPackagist.orgに登録されているものと推定されます（詳細はPackagistについてとリポジトリについてを参照）。

パッケージ名

パッケージ名はベンダー名とプロジェクト名から成ります。これらはしばしば同一になります。すなわち、ベンダー名は命名が衝突するのを避けるためだけにあります。例えば異なる2人の人物がjsonという名前のライブラリをigorw/jsonとseldaek/jsonとそれぞれ命名して作成できます。

詳細はパッケージの公開とパッケージの命名を読んでください（なお「プラットフォームパッケージ」を依存関係として指定することも可能で、サーバーのソフトウェアの特定のバージョンを要求できます。プラットフォームパッケージで後述します）。

パッケージバージョン制約

先の例ではバージョン制約2.0.*のMonologパッケージを要求しています。これが意味するものは2.0の開発ブランチの任意のバージョン、言い換えると2.0以上で2.1より小さい（>=2.0 <2.1）任意のバージョンのことを指します。

バージョンとバージョン間の関連、バージョン制約についてのより詳しい情報はバージョンを読んでください。

どうやってComposerは正しいファイルをダウンロードしているのか。 composer.jsonに依存関係を指定したとき、Composerはまず、repositoriesキーを使って登録された全てのリポジトリを対象に要求されたパッケージの名前を検索します。もし1つも追加でリポジトリを登録していなかったり、指定したリポジトリにその名前のパッケージがなかったときは、Packagist.org（後述）に落ち着きます。

ComposerがPackagist.orgないし指定したリポジトリで正しいパッケージがあったときは、パッケージのVCSのバージョン機能（つまりブランチとタグ）を使って、指定したバージョン制約に最も合致するものを見付け出そうとします。必ずバージョンについての記事でバージョンとパッケージについて読んでください。

補足： もしパッケージを要求したもののComposerがパッケージの安定性の理由で例外を投げた場合は、指定したバージョンが既定の最小の安定要件に見合わない可能性があります。 VCSで妥当なパッケージバージョンを探す際、既定では安定リリースのみが考慮されます。

パッケージの開発版、アルファ版、ベータ版、リリース候補のバージョンを要求しようとしたときに、この例外に遭遇するかもしれません。安定性フラグとminimum-stabilityキーについての詳細はスキーマのページをお読みください。

依存物をインストール

定義された依存関係をプロジェクトに初めてインストールするときは、updateコマンドを走らせると良いです。

php composer.phar update

こうするとComposerは2つのことをします。

composer.jsonファイルに挙げられている全ての依存関係を解決して、全てのアッケージとその厳密なバージョンをcomposer.lockファイルに書き込みます。このファイルによりプロジェクトが特定のバージョンに固定されます。 composer.lockファイルはプロジェクトのリポジトリにコミットすべきです。そうすればプロジェクトに参画する全員にとって、同じバージョンの依存関係に固定されたものになります（詳細は後述）。これがupdateコマンドの主な役割です。
それから暗黙裡にinstallコマンドが走ります。これにより依存関係のファイルがプロジェクトのvendorディレクトリにダウンロードされます（vendorディレクトリはプロジェクトの全てのサードパーティコード用の定番の場所です）。上の例では最終的にMonologのソースファイルがvendor/monolog/monologにあることになります。 Monologにはpsr/logへの依存関係があるため、そのパッケージのファイルもまたvendor/の中にあります。

コツ： gitをプロジェクトで使っているのなら、多分.gitignoreにvendorを追加したいでしょう。実際のところ、バージョン管理されたリポジトリにサードパーティ製のコード全てを追加したくはないので。

`composer.lock`ファイルをバージョン管理にコミットすること

このファイルをバージョン管理にコミットすることは大事です。なぜならこうすることでプロジェクトの準備をする誰もが、自分が使っているものと全く同じバージョンの依存関係を使えるようになるからです。 CIサーバ、実運用マシン、チーム内の他の開発者、万物万人が同じ依存関係で実行するのです。これにより特定のデプロイでのみ影響する潜在的なバグが低減されます。たとえ一人で開発していて、6箇月経ってからプロジェクトを再インストールしたとしても、そして依存関係が多くの新しいバージョンをリリースされていたとしても、インストールされた依存関係がちゃんと動くことは疑いありません（updateコマンドの使用については以下の補足を参照してください）。

補足： ライブラリの場合、固定ファイルのコミットは不必要です。ライブラリ - 固定ファイルも参照してください。

`composer.lock`からインストールする

既にcomposer.lockファイルがプロジェクトフォルダにあるなら、それは前に自分でupdateコマンドを走らせたか、プロジェクトの誰かがupdateコマンドを走らせてcomposer.lockファイルをプロジェクトにコミットしたからかのどちらかです（いいことです）。

何れにせよ、composer.lockファイルが存在しているときにinstallを走らせるとcomposer.jsonに挙がっている全ての依存関係を解決してインストールします。ただしその際はプロジェクトの作業をしている人全員にとってパッケージのバージョンが必ず一貫したものになるように、Composerはcomposer.lockに挙げられた厳密なバージョンを使用します。結果としてcomposer.jsonファイルで要求された全ての依存関係が取得されるのですが、必ずしも利用できるごく最新のバージョンとはなっていないかもしれません（ファイルが作成された後に、composer.lockファイルで挙げられた依存関係のより新しいバージョンがリリースされる可能性があります）。これは設計上意図されたものであり、依存関係での予期しない変更による不具合がプロジェクトで絶対に発生しないようになっています。

そのためVCSリポジトリから新しい変更を取得した後は、Composerのinstallを走らせて、vendorディレクトリがcomposer.lockファイルと同期していることを確かめることをお勧めします。

php composer.phar install

Composerは既定で再生成可能な構築を有効にします。つまり同じコマンドを複数回走らせると、自動読み込み器のファイルを含め、（タイムスタンプ以外）同値なファイルを含むvendor/ディレクトリを生成するのです。厳密な検証過程を要求する環境や、PHPアプリケーションを安全で予測可能なやり方でパッケージ化することを目指すLinuxディストリビューションにおいては、特に有益です。

Packagist

Packagistは主眼のComposerリポジトリです。 Composerリポジトリは基本的にはパッケージの源です。つまりパッケージを取ってくることができる場所のことです。 Packagistは全ての人が利用できる中央リポジトリであることを目指しています。要はここで利用できるいかなるパッケージも自動的にrequireできるということです。 Composerがパッケージを探す場所を追加で指定しなくて良いのです。

packagistのWebサイトでは、パッケージを閲覧したり検索したりできます。

Composerを使っているオープンソースプロジェクトはパッケージをPackagist上で公開するべきです。 Composerを使う上で、ライブラリをPackagistに載せる必要はありません。しかし公開することで、他の開発者がより素早くパッケージを発見して取り入れられるようになります。

プラットフォームパッケージ

Composerにはプラットフォームパッケージがあります。システムにインストールされる仮想的なパッケージで、実際にはComposerではインストールされないものを指します。 PHP自身やPHP拡張、システムライブライリが含まれます。

phpは利用者のPHPバージョンを表しており、^7.1のような制約を適用できます。 PHPの64bitバージョンを要求するには、php-64bitパッケージを指定できます。
hhvmはHHVMランタイムのバージョンを表しており、^2.3のように制約を適用できます。
ext-<name>とすることでPHPの拡張を要件にできます（中核拡張を含みます）。バージョニングはかなり一貫性がないことがあるので、大体の場合は制約に*を設定するのと良いです。拡張パッケージ名の例はext-gdです。
lib-<name>はPHPで使われるライブラリのバージョンを制約します。次のものが利用できます：curl, iconv, icu, libxml, openssl, pcre, uuid, xsl。

show --platformを使うと、ローカルで利用できるプラットフォームパッケージの一覧が得られます。

自動読み込み

自動読み込み情報を指定するライブラリ用に、Composerはvendor/autoload.phpファイルを生成します。単にこのファイルを含めれば、他に手間を掛けずにそれらのライブラリが提供するクラスを使い始められます。

require __DIR__ . '/vendor/autoload.php';

$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('Foo');

composer.jsonにautoloadフィールドを追加すれば、自分のコードについても自動読み込み器に追加できます。

{
    "autoload": {
        "psr-4": {"Acme\\": "src/"}
    }
}

ここではComposerがPSR-4自動読み込み器をAcme名前空間に登録しています。

名前空間からディレクトリへの対応付けが定義されます。 srcディレクトリはプロジェクトの根幹にあり、同じ階層にvendorもあるとしましょう。ファイル名の例としてはAcme\Fooクラスを含むsrc/Foo.phpがあります。

autoloadフィールドを追加した後は、このコマンドを再び走らせなくてはなりません。

php composer.phar dump-autoload

このコマンドはvendor/autoload.phpファイルを再生成します。詳細はdump-autoload節を参照してください。

自動読み込みファイルを含めるとautoloaderインスタンスを返します。そのためインクルード呼び出しの返り値を変数に保持し、更に名前空間を追加できます。テストスイート内での自動読み込みクラスに便利です。例えば以下です。

$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Acme\\Test\\', __DIR__);

PSR-4自動読み込みに加えて、ComposerはPSR-0、クラスマップ、ファイル自動読み込みにも対応しています。詳細はautoloadリファレンスを参照してください。

autoloaderの最適化についてのドキュメントも参照してください。

注意： Composerは自前の自動読み込み器を提供しています。もしそれを使いたくない場合は、単にvendor/composer/autoload_*.phpファイルを含められます。自前の自動読み込み器を設定できる連想配列を返します。

← 導入 | ライブラリ →

Composer