Composer: 利用のヒント
****************

<div class=perex>

Composer は PHP の依存関係を管理するための道具です。プロジェクトが依存するライブラリを宣言すると、そのインストールと更新を代わりに行ってくれます。ここでは次のことを学びます。

- Composer のインストール方法
- 新しいプロジェクトや既存のプロジェクトでの使い方

</div>


インストール
======

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


Windows
-------

公式のインストーラ [Composer-Setup.exe|https://getcomposer.org/Composer-Setup.exe]を使います。


Linux、macOS
-----------

必要なのは 4 つのコマンドだけで、[このページ |https://getcomposer.org/download/]からコピーできます。

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

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


プロジェクトでの利用
==========

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

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

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

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

```shell
composer update
```

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

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

```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 のパッケージを更新するには、コマンドラインにそれらをすべて並べる必要があります。たとえば次のようにです。

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

これは実用的ではありません。そこで、代わりにやってくれる簡単なスクリプト "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff を使ってください。

```shell
php composer-frontline.php
```


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

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

```shell
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/` ディレクトリの[権限を設定する |nette:troubleshooting#ディレクトリの権限の設定]だけで、プロジェクトが動き出すはずです。

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


PHP のバージョン
==========

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

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

```shell
composer config platform.php 8.2.3
```

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

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

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

```shell
composer require php 8.2.3 --no-update
```

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

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


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

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


誤った報告
=====

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

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


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

[Packagist |https://packagist.org]は、Composer が既定でパッケージを探す主要なリポジトリです。ここで自分のパッケージを公開することもできます。


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

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

リポジトリについて詳しくは[公式ドキュメント |https://getcomposer.org/doc/05-repositories.md#repositories]をご覧ください。


オートローディング
=========

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

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

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

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

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

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

この振る舞いの設定方法について詳しくは [Composer のドキュメント |https://getcomposer.org/doc/04-schema.md#psr-4]をご覧ください。


新しいバージョンを試す
===========

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

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

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

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

```shell
composer require nette/utils:4.0.x-dev
```

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

```shell
composer require nette/utils:4.0.0-RC2
```

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

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


コマンドの呼び出し
=========

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

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

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

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


感謝を伝える
======

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

```shell
composer global require symfony/thanks
```

そして次を実行します。

```shell
composer thanks
```

試してみてください。


設定
===

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

```shell
composer -g config preferred-install dist
```