• Composer 版本相對於 VCS 版本
• VCS 標籤與分支
  • 標籤
  • 分支
  • 穩定度
  • 最小穩定度
• 撰寫版本約束
  • 確實版本約束
  • 版本範圍
  • 連字號分隔的版本範圍 (-)
  • 萬用字元版本範圍 (.*)
• 下個重大版本號運算符
  • 波浪號版本範圍 (~)
  • 插入符號版本範圍 (^)
• 穩定度約束
• 摘要
• 測試版本約束

版本和約束#

Composer 版本相對於 VCS 版本#

由於 Composer 非常偏好利用像 git 等的版本控制系統，所以「版本」一詞可能會有點含糊。在版本控制系統中，「版本」是一組包含特定資料的特定檔案。「頭」或標籤可能代表的 Git 術語中，這是「ref」，或特定提交。在您的 VCS 中查看該版本（例如，標籤 v1.1 或提交 e35fa0d）時，您會要求取得一組已知的單一檔案，您永遠都會取得相同的檔案。

在 Composer 中，通常被稱為「版本」（也就是在 require 行中套件名稱之後的字串，例如 ~1.1 或 1.2.*）實際上更具體地稱為「版本約束」。Composer 使用版本約束，以找出它應該於 VCS 中查看哪些 ref（或查看特定函式庫在 composer.json 中具有 version 規格的靜態維護時是否可接受）。

VCS 標籤與分支#

對於下列討論，我們假設下列範例函式庫儲存庫

~/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 的第一及第二個正式版本候選、1.1 的最終發布版本等（請注意，Composer 會自動移除實際標記名稱中的 'v' 前綴，以取得有效的最終版本號碼）。

當 Composer 從 VCS 取得完整的可用版本清單後，它會尋找符合專案中所有版本限制的最高版本（其他套件可能需要比您還要更特定的函式庫版本，因此它選擇的版本可能不總是最高可用版本）；然後，它會下載那個標記的 zip 檔案，並解壓縮到 vendor 目錄中的正確位置。

分支#

如果您希望 Composer 簽出分支，而不是標記，您需要使用特殊的前綴 dev-*（或有時為後綴；請見下文）將它指向該分支。如果您簽出分支，會假設您想在該分支上工作；而 Composer 會實際將存放庫複製到 vendor 目錄中的正確位置。對於標記，它會複製正確的檔案，而不會實際複製存放庫。（您可以使用 --prefer-source 和 --prefer-dist 修改這個行為。請見 安裝選項。）

在上面的範例中，如果您想簽出 my-feature 分支，您會在 require 子句中將 dev-my-feature 指定為版本限制。這樣會讓 Composer 將 my-library 存放庫複製到我的 vendor 目錄，並簽出 my-feature 分支。

當分支名稱看來像是版本，我們必須為 Composer 釐清我們嘗試檢視的是分支，而非標籤。在上面的範例中，我們有兩個版本分支：v1 和 v2。讓 Composer 檢視其中一個分支，您必須指定一個版本約束，如下所示：v1.x-dev。.x 是 Composer 要求的任意字串，以告知我們所談論的是 v1 分支，而不是 v1 標籤（或者，您可以將分支命名為 v1.x，而不是 v1）。對於具有版本樣式名稱的分支（在本例中為 v1），您追加 -dev 作為後綴，而不是使用 dev- 作為前綴。

穩定性#

Composer 辨識以下穩定性（依穩定性順序）：dev、alpha、beta、RC 和 stable。RC 代表候選版本。版本的穩定性由其後綴定義，例如版本 v1.1-BETA 的穩定性為 beta，而 v1.1-RC1 的穩定性為 RC。如果此類後綴不存在，例如版本 v1.1，則 Composer 將該版本視為 穩定。除此之外，Composer 會自動將 -dev 後綴新增至所有數字分支，並在 VCS 儲存庫匯入的所有其他分支之前加上前綴 dev-。在兩種情況下，都指定穩定性 dev。

記住這一點將有助於您閱讀下一個段落。

最低穩定性#

還有一件事將影響從程式庫的 VCS 檢視並新增至您的專案的檔案：Composer 允許您指定穩定性約束，以限制哪些標籤被視為有效。在上面的範例中，請注意在正式版本發佈之前，程式庫為版本 1.1 發佈了一個 beta 版和兩個候選版本。要在執行 composer install 或 composer update 時接收這些版本，我們必須明確告訴 Composer，我們接受候選版本和 beta 版本（如果我們想要的話，還包括 alpha 版本）。這可以使用 composer.json 中的專案範圍 minimum-stability 值或版本約束中的「穩定性旗標」來完成。請在 架構頁面 中閱讀更多內容。

撰寫版本約束#

現在您已經瞭解 Composer 如何看待版本，讓我們來談談如何為專案相依性指定版本約束。

精確版本約束#

您可以指定軟體包的確切版本。這將告訴 Composer 安裝此版本，而且只安裝此版本。如果其他相依性需要不同的版本，求解器最終將失敗並中止任何安裝或更新程序。

範例：1.0.2

版本範圍#

透過使用比較運算子，您可以指定有效的版本範圍。有效的運算子為 >、>=、<、<=、!=。

你可以定義多個範圍。以空格 ( ) 或逗號 (,) 分隔的範圍將被視為 **邏輯 AND**。雙垂直線 (||) 將被視為 **邏輯 OR**。AND 優先權高於 OR。

**注意：**使用無界範圍時務必小心，因為你可能會意外安裝破壞向下相容性的版本。不妨考慮使用 脫字號 運算子以確保安全。

**注意：**在舊版 Composer 中，單垂直線 (|) 是推薦的 **邏輯 OR** 替代選項。因此，為了向下相容，單垂直線 (|) 仍將被視為 **邏輯 OR**。

範例

• >=1.0
• >=1.0 <2.0
• >=1.0 <1.1 || >=1.2

連字符版本範圍 (-)#

包含式的版本組。右邊包含部分版本會用萬用字元補齊。例如，1.0 - 2.0 等於 >=1.0.0 <2.1，因為 2.0 會變成 2.0.*。另一方面，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。如你所見，它對遵循 語意版本控管 的專案最為有用。常見用法是標示你依賴的最小次要版本，例如 ~1.2（允許任何低於 2.0 的版本）。因為理論上在 2.0 之前不應該有破壞向下相容性的情況，所以運作良好。另一種觀點是，使用 ~ 指定最小版本，但允許指定的最後一個數字進位。

範例：~1.2

**注意：**儘管 2.0-beta.1 嚴格來說小於 2.0，但類似 ~1.2 的版本約束不會安裝這項版本。如上所述，~1.2 只意味著 .2 可以變更，但 1. 部分是固定的。

**注意：**~ 運算子主要版本號碼的行為有例外。這表示例如 ~1 與 ~1.0 相同，因為它不會允許主版本號碼增加，以試圖保持向下相容性。

脫字號版本範圍 (^)#

^ 運算子的行為非常類似，但它更貼近語義版本控管，而且總是會允許非破壞性更新。例如，^1.2.3 相當於 >=1.2.3 <2.0.0，因為 2.0 之前的版本都不應破壞後向相容性。對於 1.0 以前的版本，它也會顧及安全性，並將 ^0.3 視為 >=0.3.0 <0.4.0，將 ^0.0.3 視為 >=0.0.3 <0.0.4。

編寫函式庫程式碼時，這是建議使用且能獲得最大相容性的運算子。

範例：^1.2.3

注意：如果你在 Windows 上使用 PowerShell，必須在 CLI 中將插入號作為引數時加上跳脫字元，例如使用 composer require 指令。你必須使用四個連續的插入號運算子，例如 ^^^^1.2.3，以確保插入號運算子能正確傳遞到 Composer。

穩定性約束#

如果你使用未明確定義穩定性的約束，Composer 內部將預設為 -dev 或 -stable，視所使用的運算子而定。這動作會在不明顯的情況中發生。

如果你希望在比較中只明確考慮穩定版本，請加上字尾 -stable。

範例

約束	內部
1.2.3	=1.2.3.0-stable
>1.2	>1.2.0.0-stable
>=1.2	>=1.2.0.0-dev
>=1.2-stable	>=1.2.0.0-stable
<1.3	<1.3.0.0-dev
<=1.3	<=1.3.0.0-stable
1 - 2	>=1.0.0.0-dev <3.0.0.0-dev
~1.3	>=1.3.0.0-dev <2.0.0.0-dev
1.4.*	>=1.4.0.0-dev <1.5.0.0-dev

不過，若要允許各類穩定性而不用在約束層級執行，你可以使用 穩定性旗標，例如 @<stability> (例如 @dev) 讓 Composer 知道特定套件可以安裝在不同穩定性中，而不用遵循你的預設最小穩定性設定。所有可用的穩定性旗標都列在 Schema 頁面 的最小穩定性區段。

摘要#

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

    // >, <, >=, <= | 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

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

    // ~ | 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

    // ^ | 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.madewithlove.com 測試版本約束。填寫套件名稱，它會自動填入 Composer 會新增到你的 composer.json 檔案中的預設版本約束。你可以調整版本約束，該工具會突顯出所有相符的版本。

找到錯字嗎？此文件有什麼不對的地方嗎？分岔並編輯 文件！