Composer: 利用のヒント

インストール

Composer は実行できる .phar ファイルで、次のようにダウンロードしてインストールします。

Windows

公式のインストーラ Composer-Setup.exeを使います。

Linux、macOS

必要なのは 4 つのコマンドだけで、このページからコピーできます。

さらに、システムの PATH に含まれるフォルダにコピーすれば、Composer をどこからでも使えるようになります。

$ mv ./composer.phar ~/bin/composer # または /usr/local/bin/composer

プロジェクトでの利用

プロジェクトで Composer を使い始めるのに必要なのは composer.json ファイルだけです。このファイルはプロジェクトの依存関係を記述し、ほかのメタデータを含むこともあります。最も単純な composer.json は次のようなものです。

{
	"require": {
		"nette/database": "^3.0"
	}
}

ここでは、私たちのアプリケーション（またはライブラリ）が nette/database パッケージを必要とし（パッケージ名はベンダー名とプロジェクト名から成ります）、^3.0 というバージョン制約に合う版（つまり最新のバージョン 3）を求めている、と述べています。

composer.json ファイルをプロジェクトのルートに置いたら、次を実行します。

composer update

Composer は Nette Database を vendor/ ディレクトリにダウンロードします。あわせて composer.lock ファイルも作られ、どのライブラリのどのバージョンを正確にインストールしたかの情報が入ります。

Composer は vendor/autoload.php ファイルを生成します。このファイルを読み込むだけで、余計な作業なしにライブラリのクラスを使い始められます。

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

$db = new Nette\Database\Connection('sqlite::memory:');

パッケージを最新版に更新する

composer.json で定めた制約に従って、使っているライブラリを最新版に更新するには composer update コマンドを使います。たとえば依存関係が "nette/database": "^3.0" なら、最新の 3.x.x 版がインストールされ、バージョン 4 はインストールされません。

composer.json ファイルの制約自体を、たとえば "nette/database": "^4.1" に更新して最新版をインストールできるようにするには、composer require nette/database コマンドを使います。

使っているすべての Nette のパッケージを更新するには、コマンドラインにそれらをすべて並べる必要があります。たとえば次のようにです。

composer require nette/application nette/forms latte/latte tracy/tracy ...

これは実用的ではありません。そこで、代わりにやってくれる簡単なスクリプト Composer Frontline を使ってください。

php composer-frontline.php

新しいプロジェクトの作成

新しい Nette のプロジェクトは、ひとつのコマンドで作れます。

composer create-project nette/web-project name-of-the-project

name-of-the-project をプロジェクトのディレクトリ名に置き換えて実行してください。Composer が GitHub から nette/web-project リポジトリ（すでに composer.json ファイルを含んでいます）をダウンロードし、続いて Nette Framework 自体をインストールします。あとは temp/ と log/ ディレクトリの権限を設定するだけで、プロジェクトが動き出すはずです。

プロジェクトを置くホスティングの PHP のバージョンが分かっているなら、必ずそれを設定してください。

PHP のバージョン

Composer は常に、今使っている PHP のバージョン（正確には Composer を実行したコマンドラインの PHP のバージョン）に合うパッケージの版をインストールします。これはウェブホスティングが使うバージョンと同じとは限りません。ですから、ホスティングの PHP のバージョンの情報を composer.json ファイルに足すことが決定的に重要です。そうすれば、ホスティングに合う版のパッケージだけがインストールされます。

たとえばプロジェクトが PHP 8.2.3 で動くと指定するには、次のコマンドを使います。

composer config platform.php 8.2.3

バージョンは composer.json ファイルに次のように書かれます。

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

ただし PHP のバージョン番号は、このファイルの別の場所、require セクションにも書かれます。最初の番号がパッケージをインストールする際のバージョンを決めるのに対し、2 つめはアプリケーション自体がどのバージョン向けに書かれているかを示します。たとえば PhpStorm はこれを使って PHP language level を設定します。（もちろんこの 2 つが食い違うのは意味をなさないので、二重に書くことになっているのは設計上の見落としです。）このバージョンは次のコマンドで設定します。

composer require php 8.2.3 --no-update

あるいは composer.json ファイルに直接書きます。

{
	"require": {
		"php": "8.2.3"
	}
}

PHP のバージョンを無視する

パッケージはふつう、対応する最も低い PHP のバージョンと、テスト済みの最も高いバージョンの両方を指定しています。テストなどのためにそれより新しい PHP のバージョンを使うつもりなら、Composer はそのパッケージのインストールを拒みます。その答えが --ignore-platform-req=php+ オプションで、これを使うと Composer は要求される PHP バージョンの上限を無視します。

誤った報告

パッケージを更新したりバージョン番号を変えたりすると、ときどき衝突が起こります。あるパッケージの要求が別のパッケージと衝突する、といった具合です。ただし Composer は、実際には存在しない衝突を報告することがあります。そうした場合は composer.lock ファイルを削除してやり直すとうまくいくことがあります。

それでもエラーメッセージが残るなら、それは本物です。何をどう直すべきか、メッセージを読んで理解する必要があります。

Packagist.org – グローバルなリポジトリ

Packagistは、Composer が既定でパッケージを探す主要なリポジトリです。ここで自分のパッケージを公開することもできます。

中央のリポジトリを使いたくない場合

社内のアプリケーションやライブラリで公開できないものがあるなら、それ用に自分たちのリポジトリを作れます。

リポジトリについて詳しくは公式ドキュメントをご覧ください。

オートローディング

Composer の重要な機能は、インストールしたすべてのクラスにオートローディングを提供することです。vendor/autoload.php ファイルを読み込めば有効になります。

さらに Composer を使って、vendor/ ディレクトリの外のクラスを読み込むこともできます。ひとつめの方法は、指定したディレクトリとそのサブディレクトリを Composer に走査させ、見つけたすべてのクラスをオートローダーに登録させることです。そのためには composer.json の autoload > classmap を設定します。

{
	"autoload": {
		"classmap": [
			"src/",      # src/ ディレクトリとそのサブディレクトリを含めます
		]
	}
}

その場合、変更のたびに composer dumpautoload コマンドを実行してオートローディングの表を作り直す必要があります。これはきわめて面倒です。この仕事は RobotLoaderに任せるほうがずっと良く、同じことを自動的に、しかもはるかに速くバックグラウンドで行ってくれます。

ふたつめの方法は PSR-4に従うことです。簡単にいえば、名前空間とクラス名がディレクトリ構造とファイル名に対応するしくみで、たとえば App\Core\RouterFactory は /path/to/App/Core/RouterFactory.php ファイルに置かれます。設定の例です。

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # App\ 名前空間は app/ ディレクトリにあります
		}
	}
}

この振る舞いの設定方法について詳しくは Composer のドキュメントをご覧ください。

新しいバージョンを試す

パッケージの新しい開発版を試したいですか。やり方を説明します。まず composer.json ファイルに次の 2 つのオプションを足します。これで開発版をインストールできるようになりますが、安定版の組み合わせで要求を満たせない場合にだけ Composer は開発版に頼ります。

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

あわせて composer.lock ファイルの削除もおすすめします。Composer が理由もはっきりしないままインストールを拒むことがあり、これで解決することがあるからです。

パッケージが nette/utils で、新しいバージョンが 4.0 だとしましょう。次のコマンドでインストールします。

composer require nette/utils:4.0.x-dev

あるいは特定のバージョン、たとえば 4.0.0-RC2 をインストールすることもできます。

composer require nette/utils:4.0.0-RC2

ただし別のパッケージがそのライブラリに依存していて、古いバージョン（たとえば ^3.1）に固定されている場合、理想的な解はその依存元のパッケージを新しいバージョンで動くよう更新することです。とはいえ、制限を回避して、開発版を古いバージョン（たとえば 3.1.6）のふりをさせたまま Composer にインストールさせたいだけなら、as キーワードを使えます。

composer require nette/utils "4.0.x-dev as 3.1.6"

コマンドの呼び出し

自分で定義したコマンドやスクリプトを、Composer 本来のコマンドであるかのように Composer 経由で呼び出せます。vendor/bin ディレクトリにあるスクリプトなら、そのパスを指定する必要もありません。

例として、Nette Testerでテストを実行するスクリプトを composer.json に定義してみましょう。

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

あとは composer tester でテストを実行します。プロジェクトのルートディレクトリでなく、そのサブディレクトリにいてもこのコマンドを呼べます。

感謝を伝える

オープンソースの作者を喜ばせる小技を紹介します。プロジェクトが使っているライブラリに、GitHub で簡単にスターを付けられます。symfony/thanks ライブラリをインストールするだけです。

composer global require symfony/thanks

そして次を実行します。

composer thanks

試してみてください。

設定

Composer はバージョン管理ツール Gitと密に結びついています。Git をインストールしていない場合は、それを使わないよう Composer に伝える必要があります。

composer -g config preferred-install dist