Composer バージョン制約

Version 1.9.1

— y2sunlight 2020-03-16

Composer に戻る

関連記事

• Composerのインストール
• ComposerをPHPバージョンで使い分ける
• Composerのローカルインストール
• Composer 基本的な使い方
• Composer コマンド一覧
• Composer バージョン制約

本章は以下のページの翻訳に補足事項を加筆をしたものです。

Versions and constraints　— https://getcomposer.org/doc/articles/versions.md

ComposerはgitなどのVCS(バージョン管理システム)の利用に重点を置いているため、「バージョン」という用語は少し曖昧な場合があります。バージョン管理システムの意味では、「バージョン」は特定のデータを含む特定のファイルセットのことです。gitの用語では、これは ref または特定のコミットであり、ブランチHEADまたはタグで表されます。あなたがVCSでそのバージョン（タグv1.1やコミットe35fa0dなど）をチェックアウトする時、単一で既知のファイルセットが要求され、常に同じファイルが返ってきます。

Composerでは、しばしば気軽にバージョンと呼ばれるもの、つまり、requireキー でパッケージ名に続く文字列（例：~1.1 または 1.2.*）は、実際に、より具体的に言えば、それはバージョン制約のことです。Composerは、バージョン制約を使用して、VCSのどの ref をチェックアウトするかを判断します（また、composer.json のバージョン仕様で静的にメンテナンスされたライブラリの場合は、特定のライブラリが受け入れられることを確認します）。

以下の説明では、次のサンプルライブラリのリポジトリを想定します。

~/my-library$ git branch
v1
v2
my-feature
another-feature

~/my-library$ git tag
v1.0
v1.0.1
v1.0.2
v1.1-BETA
v1.1-RC1
v1.1-RC2
v1.1
v1.1.1
v2.0-BETA
v2.0-RC1
v2.0
v2.0.1
v2.0.2

通常、Composerはタグを処理します。バージョン制約を記述するとき、特定のタグ（例：1.1）を参照する場合と、有効なタグ範囲（例：>= 1.1 <2.0 または ~4.0）を参照する場合があります。これらの制約を解決するために、ComposerはまずVCSに利用可能な全てのタグを一覧表示するように要求し、次にこれらのタグに基づいて利用可能なバージョンの内部リストを作成します。上記の例では、composerの内部リストには、バージョン1.0、1.0.1、1.0.2、1.1-BETA、1.1のRC1版とRC2版、1.1の最終リリース版などが含まれています。（Composer有効な最終バージョン番号を取得するために、実際のタグ名の vプレフィックスを自動的に削除します。

ComposerがVCSで使用可能なバージョンの完全なリストを取得すると、Composerはプロジェクト内の全てのバージョン制約に一致する最上位バージョンを検索します（他のパッケージでは、より特定のバージョンのライブラリが必要になる可能性があるため、選択するバージョンは常に最高のバージョンであるとは限りません）、そして、そのタグのzipアーカイブをダウンロードして、vendor ディレクトリの正しい場所に解凍します。

Composerにタグの代わりにブランチをチェックアウトさせる場合は、特別な dev-* プレフィックス（または サフィックス。以下を参照）を使用してブランチを指示する必要があります。ブランチをチェックアウトしている場合、ブランチで作業することを想定しているため、Composerは実際にリポジトリをvender ディレクトリの正しい場所に複製します。タグの場合は、実際にリポジトリを複製せずに適切なファイルをコピーします。（この動作は　–prefer-source および –prefer-dist で変更できます。install コマンドのオプションを参照してください。）

上記の例で、my-feature ブランチをチェックアウトする場合は、requireキーのバージョン制約として dev-my-feature を指定します。これにより、Composerは my-library リポジトリを vender ディレクトリに複製し、my-feature ブランチをチェックアウトします。

ブランチ名がバージョンのように見える場合、タグではなくブランチをチェックアウトしようとしていることをComposerに明確にする必要があります。上記の例では、v1 と v2 の2つのバージョンブランチがあります。Composerにこれらのブランチの1つをチェックアウトさせるには、v1.x-dev のようなバージョン制約を指定する必要があります。.x は、Composerが v1タグではなく v1ブランチについて話していることを伝えるために必要な任意の文字列です（または、v1 の代わりにブランチにv1.x という名前を付けることができます）。バージョンのような名前（この場合はv1）を持つブランチの場合、プレフィックスとして dev- を使用するのではなく、サフィックスとして -dev を追加します。

ライブラリのVCSからチェックアウトされ、プロジェクトに追加されるファイルに影響するもう1つのことがあります。それは、Composerでは「安定性の制約」を指定して有効と見なされるタグを制限できるという事です。 上記の例では、ライブラリが最終的な公式リリースの前にβ版と、バージョン1.1の2つのリリース候補版(RC1とRC2)をリリースしたことに注意してください。Composerの install または update の実行時にこれらのバージョンを受け取るには、リリース候補とβリリース（および必要に応じてαリリース）で問題ないことをComposerに明示的に通知する必要があります。これは、composer.json でプロジェクト全体の「最小安定値」を使用するか、バージョン制約で「安定フラグ」を使用して実行できます。 詳細については、スキーマページをご覧ください。

Composerがバージョンをどのように認識するかがわかったので、プロジェクトの依存関係にバージョン制約を指定する方法について話しましょう。

パッケージの正確なバージョンを指定できます。これにより、Composerはこのバージョンのみをインストールするようになります。 他の依存関係が異なるバージョンを必要とする場合、ソルバーは最終的に失敗し、インストールまたは更新手順を中止します。

例: 1.0.2

比較演算子を使用すると、有効なバージョンの範囲を指定できます。有効な演算子は >、>=、<、⇐、!=です。

複数の範囲を定義できます。スペースまたはカンマ( , )で区切られた範囲は、論理ANDとして扱われます。二重パイプ( || ）は論理ORとして扱われます。ANDはORよりも優先順位が高くなります。

Note:
予期せずに下位互換性を損なうバージョンをインストールする可能性があるため、無制限の範囲を使用する場合は注意してください。この場合。安全のために、キャレット演算子( ^ )の使用を検討してください。

例:

1. >=1.0
2. >=1.0 <2.0
3. >=1.0 <1.1 || >=1.2

包括的なバージョンのセットです。右側のバージョンの一部には、ワイルドカードが含まれています。たとえば、1.0-2.0 は 2.0 が 2.0.* になるため、>=1.0.0 <2.1 と同等です。 一方、1.0.0-2.1.0 は >=1.0.0 ⇐2.1.0 と同等です。

例: 1.0 - 2.0

*ワイルドカードを使用してパターンを指定できます。 1.0.* は、>=1.0 <1.1 と同等です。

例: 1.0.*

~演算子は、例で最もよく説明されています。~1.2 は >=1.2 <2.0.0 と同等で、~1.2.3 は >=1.2.3 <1.3.0と同等です。このように、セマンティックバージョニングを尊重するプロジェクトに最も役立ちます。

セマンティックバージョニング

semantic versioning(セマンティックバージョニング) はバージョン管理の命名規則を使って互換性の定義を標準化しようとする試みです。バージョン番号を３つのセクションで区切り(Major.Minor.Patch)、以下の意味付けをしています。（即ち、メジャーバージョンアップでは後方互換性が保証されません）

Major: 後方互換性を保証しないバージョンアップ
Minor: 後方互換性を保証した機能追加などのバージョンアップ
Patch: 後方互換性を保証したバグの修正によるバージョンアップ

一般的な使用法は、依存する最小のマイナーバージョンを ~1.2 のようにマークすることです（これは、2.0までは含まれますが、2.0は含まれません）。理論的には2.0まで後方互換性の中断はないはずなので、それはうまく機能します。別の見方をすれば、~の使用は最小バージョンを指定しますが、指定された最後の桁が上がることになります。

例: ~1.2

Note:
2.0-beta.1 は厳密に 2.0 より前ですが、~1.2 のようなバージョン制約ではインストールされません。上記のように、 ~1.2 は .2 のみが変更できることを意味しますが、1. の部分は固定されています。

Note:
~演算子には、メジャーリリース番号の動作に例外があります。これは、例えば、~1 は ~1.0 と同じであり、下位互換性を維持しようとしてメジャー番号を増やすことができないことを意味します。

^演算子は、セマンティックバージョニングに近いものであり非常によく似た動作をしますが、常に非破壊的な更新を許可します。例えば、^1.2.3 は、>=1.2.3 <2.0.0 と同等です。これは、2.0 が下位互換性を破るまでリリースがないためです。1.0 より前のバージョンでは、安全性を考慮して機能し、^0.3 を >=0.3.0 <0.4.0 として扱います。

この演算子(^)は、ライブラリコードを記述するときに相互運用性を最大限に高めるための推奨演算子です。

例: ^1.2.3

安定性を明示的に定義しない制約を使用している場合、Composerは内部的に -dev または -stable をデフォルトで使用します。これは使用する演算子によって異なります。そして、これは透過的に発生します。

安定版リリースのみを明示的に検討したい場合は、接尾辞 -stable を追加して下さい。

例:

ただし、制約レベルで強制せずにさまざまな安定性を許可するには、@<stability>（@dev など）のような安定性フラグを使用して、特定のパッケージがデフォルトの最小安定性の設定とは異なる安定性でインストールできることをComposerに知らせることができます。使用可能なすべての安定性フラグは、スキーマページの最小安定性セクションにリストされています。

"require": {
 
    "vendor/package": "1.3.2", // exactly 1.3.2
}

"require": {
 
    // >, <, >=, <= | specify upper / lower bounds
    "vendor/package": ">=1.3.2", // anything above or equal to 1.3.2
    "vendor/package": "<1.3.2", // anything below 1.3.2
}

"require": {
 
    // * | wildcard
    "vendor/package": "1.3.*", // >=1.3.0 <1.4.0
}

"require": {
 
    // ~ | allows last digit specified to go up
    "vendor/package": "~1.3.2", // >=1.3.2 <1.4.0
    "vendor/package": "~1.3", // >=1.3.0 <2.0.0
}

"require": {
 
    // ^ | doesn't allow breaking changes (major version fixed - following semver)
    "vendor/package": "^1.3.2", // >=1.3.2 <2.0.0
    "vendor/package": "^0.3.2", // >=0.3.2 <0.4.0 // except if major version is 0
}

semver.mwl.beを使用してバージョンの制約をテストできます。パッケージ名を入力すると、Composerがcomposer.json ファイルに追加するデフォルトのバージョン制約が自動入力されます。バージョン制約を調整すると、ツールは一致するすべてのリリースを強調表示します。