プロジェクトの基本プロパティ
プロジェクトの基本プロパティとしては、以下のような項目があります。
name
ベンダー名称とプロジェクト名称を"/"で分けて記述します。
ベンダー名称とは会社名であったり、作成者の名称であったりと、パッケージ名と同様な役目となり、同じプロジェクト名が重複しないようにするためのものです。作成時では必須ではありませんがプロジェクト名称などはプログラムを記述する際の名前空間（namespace）と一致させることもあると思います。公開時には必須となる情報なので、最初から考慮しておく必要があります。
name : "coltware/sample"
description
プロジェクトの説明を記述する項目です。図2（Packagistサイトでの表示例）で示したように説明が表示され、通常は1行で説明を記述します。
version
プロジェクトのバージョンを指定します。バージョンは通常「X.Y.Z」のような形式で記述します。それぞれのバージョン番号の付け方は特にありませんが、依存を指定するときには、以下のように記述されることが通常です。
"require" :{
"vendor/project" : "1.0.*"
}
従って、X.Yの部分が変わらない場合には同じAPIがサポートされていることを期待されます。そのような利用者側の意識を想定して作成することが大切です。また、バージョン番号の後に、「-dev」「-patch」「-beta」「-alpha」「-RC」の指定をつけることも可能です。これらを利用し、以下のようなバージョン番号をつけることができます。
- 1.0.0
- 1.1.0-dev
- 1.1.0-alpha1
- 1.1.0-beta2
- 1.1.0-RC3
type
typeは、プロジェクトのタイプを示します。デフォルトは「library」で、その場合には明示的に指定する必要はありません。composerでは、以下の4つのタイプをサポートしていますが、デフォルトでもあるようにライブラリの作成で指定が必要になるケースはあまりありません。
| 設定値 | 概要 |
|---|---|
| library | デフォルトの指定。composerでインストールしたときにvendorフォルダ（変更可能）にコピー |
| project | libraryとほぼ同様だが、ComposerをサポートしているIDEなどにプロジェクトであることを伝えたい場合に利用 |
| metapackage | 空のパッケージで、そのパッケージ自体にはソースなどを含めない場合に利用する。複数のプロジェクトの依存のみを記述する場合になどに利用可能（例えば、複数のライブラリを集めてプロジェクトの依存セットとしての用途） |
| composer-plugin | 個別のインストーラなどを用意する場合に指定 |
license
ライセンスを示す記述です。マルチライセンスでは、配列として指定します。Packagistのようなパッケージ管理サイトへ公開する場合には必須です。
{
"license" : ["Aapache-2.0","MIT"]
}
その他
その他にも、以下のような項目があります。
- keywords : キーワードを指定します。
- homepage : プロジェクトのWebサイトを指定します。
- authors : パッケージの作成者情報を指定します。
- support: パッケージの関連情報のサイトを指定します。
{
"keyword" : ["framework"],
"homepage" : "http://dummy.coltware.com",
"authors": [
{
"name" : "coltware",
"homepage": "http://www.coltware.com/"
},
"support": {
"source" : "https://github.com/xxxxxxxxx"
}
]
}
依存ライブラリ情報
依存ライブラリを記述する項目が「require」で、リスト5のように記述することができます。
{
"require" : {
"vendor/sample1" : "1.0.*",
"vendor/sample2" : ">=2.0"
}
}
jsonでのオブジェクトとして、キーと値でプロジェクト名とそのバージョンの指定をします。依存として指定する場合のバージョン制約の指定方法には、以下のような方法があります。
特定のバージョンを指定する
"1.0.2" のように指定します。このように指定することで特定のバージョンに固定することができます。通常、固定のバージョンに依存することはないと思いますので、あまり使わない指定方法です。
ワイルドカードを使用して指定する
"1.0.*"のように指定する方法です。この指定により、1.0.0以上1.1.0未満のバージョンを対象にします。1.0系のバグフィックスの場合には問題ないが、1.1系にはしないというケースになります。従って、最も使われる指定方法になると思います。また、後述するレンジ指定でも同じ指定ができます。また、ワイルドカードを利用する場合には、リスト6のような記述をする場合もあります。これは、「1.0.1-dev」のようなバージョンを依存として指定する場合です。開発バージョンしかないようなライブラリでは、このように指定します。
{
"require" : {
"vendor/sample1" : "1.0.*@dev"
}
}
レンジを使用して指定する
レンジを指定する場合には、「>（より大）」「>=（以上）」「<（未満）」「<=（以上）」「!=（一致しない）」のような演算子が指定できます。「AND」条件は「,（カンマ）」でつなげて、「OR」条件は「|（パイプ）」でつなげます。また、AND条件の方が優先されます。この指定を利用することで、より柔軟なバージョンの指定が可能で、あるバージョンのみを除外したい場合などに利用できます。
| 指定例 | 概要 |
|---|---|
| >=1.0 | 1.0以上 |
| >=1.0,<1.1 | 1.0以上、1.1未満。つまり、1.0.* と同じ意味 |
| >=1.0,<1.1 | >= 1.2 | 1.0以上、1.1未満。または、1.2以上 |
セマンティックバージョニングに沿って指定する
セマンティックバージョニングとは、X.Y.Zとしてのバージョンの指定方法を決めたルールで以下のようになっています。
- X:下位互換が保証されない変更を伴うバージョンアップ（メジャーバージョンとなる）
- Y:下位互換を保証する形での機能追加などによるバージョンアップ（マイナーバージョンとなる）
- Z:機能の追加、変更、削除などを伴わないバグフィックスなどのバージョンアップ（例：パッチ番号）
より詳細な説明は日本語訳のサイトがありますので、そちらを参照するとより分かります。
このようなバージョンニングをしているパッケージであれば、「1.2以上、2.0未満」や「1.1.1以上、1.2未満」のような指定方法です。この場合には、「~（チルダ）」演算子が利用でき、リスト7のように指定ができます。
{
"require" : {
"vendor/sample1" : "~1.2", // 1.2以上、2.0未満
"vendor/sample2" : "~1.1.1" // 1.1.1以上、1.2未満
}
}
