• 介紹
• composer.json：專案設定
  • require 鍵
  • 套件名稱
  • 套件版本限制
• 安裝相依套件
  • 將 composer.lock 檔案提交至版本控制
  • 從 composer.lock 安裝
• 將相依套件更新至其最新版本
• Packagist
• 平台套件
• 自動載入

基本用法#

簡介#

在我們的基本用法簡介中，我們將安裝monolog/monolog，一個記錄函式庫。如果您尚未安裝 Composer，請參閱簡介章節。

注意：為了簡單起見，本簡介假設您已執行 Composer 的本機安裝。

composer.json：專案設定#

要在專案中開始使用 Composer，您只需要一個composer.json檔案即可。此檔案描述您的專案的相依性，也可以包含其他元資料。它通常應該放在您的專案/VCS 儲存庫的最上層目錄中。您可以在技術上任意位置執行 Composer，但如果您要將套件發布到 Packagist.org，它必須能夠在您的 VCS 儲存庫的最上層找到該檔案。

require 鍵#

您在composer.json中指定的第 1 件事是require鍵。您告訴 Composer 您的專案依賴哪些套件。

{
    "require": {
        "monolog/monolog": "2.0.*"
    }
}

如您所見，require接受一個物件，該物件將套件名稱 (例如 monolog/monolog) 對應到版本限制 (例如 1.0.*)。

Composer 使用此資訊在套件「儲存庫」中搜尋正確的檔案集，您可以使用repositories鍵或使用Packagist.org（預設套件儲存庫）進行註冊。在上述範例中，由於在 composer.json 檔案中沒有註冊其他儲存庫，因此假設 monolog/monolog 套件已在 Packagist.org 上註冊。（請閱讀更多關於 Packagist和關於儲存庫的資訊）。

套件名稱#

套件名稱由供應商名稱和專案名稱組成。通常會相同，供應商名稱只存在來避免命名衝突。例如，它允許兩個人建立名為 json 的函式庫。一個可以用 igorw/json 命名，而另一個可以用 seldaek/json 命名。

深入瞭解 發布套件和套件命名。（請注意，您也可以指定「平台套件」作為相依性，讓您可以要求伺服器軟體的特定版本。請見下方的 平台套件。）

套件版本限制#

在我們的範例中，我們要求 Monolog 套件的版本限制為 2.0.*。這表示 2.0 開發分支中的任何版本，或任何大於或等於 2.0 且小於 2.1 的版本 (>=2.0 <2.1)。

請閱讀 版本 以深入瞭解版本、版本之間的關聯性，以及版本限制。

Composer 如何下載正確的檔案？ 當您在 composer.json 中指定相依性時，Composer 會先取得您請求的套件名稱，並在您使用 repositories 金鑰註冊的任何存放庫中搜尋。如果您尚未註冊任何額外的存放庫，或者它在您指定的存放庫中找不到具有該名稱的套件，它就會退回到 Packagist.org（更多 詳情如下）。

當 Composer 在 Packagist.org 或您指定的存放庫中找到正確的套件時，它就會使用套件 VCS（例如分支和標記）的版本化功能，嘗試找到與您指定的版本限制最相符的版本。務必在 版本文章 中閱讀版本和套件解析。

注意： 如果您嘗試要求套件，但 Composer 針對套件穩定性擲回錯誤，則您指定的版本可能不符合您的預設最小穩定性需求。預設情況下，在 VCS 中搜尋有效的套件版本時，僅考慮安全性版本。

如果您嘗試要求套件的開發、alpha、beta 或 RC 版本，您可能會遇到此問題。請在 架構頁面 上深入瞭解穩定性標記和 minimum-stability 金鑰。

安裝相依性#

若要為您的專案初步安裝已定義的相依性，您應該執行 update 命令。

php composer.phar update

這將讓 Composer 執行以下兩件事：

• 此命令會解決composer.json 檔案中所列出的所有相依性，並將所有套件和其確切版本寫入到composer.lock 檔案中，並將專案鎖定至那些特定版本。你應該提交composer.lock 檔案到專案儲存庫，讓所有人員在專案上所操作的相依性版本相同（詳見下文）。這是update 命令的主要角色。
• 接著，它會隱式執行install 命令。此動作會將相依性檔案下載到專案中的vendor 目錄中。（vendor 目錄是專案中所有第三方程式碼的慣用存放位置）。在上述範例中，你最終會將 Monolog 原始碼檔案放在vendor/monolog/monolog/ 中。由於 Monolog 相依於psr/log，因此也可以在vendor/ 內找到該套件的檔案。

提示：如果你為專案使用 Git，你可能會希望在.gitignore 中新增vendor。你一定不希望將所有第三方程式碼新增到已版本化的儲存庫中。

將composer.lock 檔案提交至版本控制#

將此檔案提交至版本控制非常重要，這是因為這會導致任何設定專案的人員使用你所使用的相依性之確切相同版本。你的 CI 伺服器、執行階段機器、團隊中的其他開發人員，一切事物和人員都執行於相同的相依性中，這會減輕僅影響配置部分中的部分偵錯之可能性。即使你單獨開發，在六個月後重新安裝專案時，你也可以有信心所安裝的相依性仍然可以正常運作，即使相依性已於此後發布許多新版本。（請參閱下文有關使用update 命令的說明。）

注意：對於函式庫，無需提交鎖定檔案，另請參閱：函式庫 - 鎖定檔案。

從 composer.lock 安裝#

如果專案資料夾中已存在composer.lock 檔案，表示你已先前執行過update 命令，或是專案中的其他人員已執行過update 命令，並將composer.lock 檔案提交至專案（這是好事）。

不論如何，在存在composer.lock 檔案時執行install 會解決並安裝你在composer.json 中所列出的所有相依性，但 Composer 會使用composer.lock 中所列出的確切版本，以確保套件版本對每個在你的專案上工作的人員來說是一致的。因此，你將擁有composer.json 檔案所要求的所有相依性，但它們可能不是最新的可用版本（自檔案建立以來，composer.lock 檔案中列出的部分相依性可能已發布更新版本）。這是根據設計而定，可確保你的專案不會因相依性的意外變更而中斷。

所以從您的 VCS 存放庫取得新變更後建議執行 Composer install 以確保供應商目錄與 composer.lock 檔案同步。

php composer.phar install

Composer 預設啟用可重複建置。這表示相同指令執行多次會產生 vendor/ 目錄包含相同檔案 (除了時間戳記之外)，包括自動載入檔案。這對於要求嚴格驗證流程的環境以及希望以安全可預測方式打包 PHP 應用程式的 Linux 分配特別有幫助。

將相依項更新為最新版本#

如上述所述，composer.lock 檔案可防止您自動取得最新版本的相依項。若要更新至最新版本，請使用 update 指令。這將取得最新相符版本 (根據您的 composer.json 檔案) 和使用新版本更新鎖定檔案。

php composer.phar update

注意：如果 composer.lock 自從變動 composer.json 會影響相依項解析以來尚未更新，Composer 將在執行 install 指令時顯示警告。

如果您只想要安裝、升級或移除一個相依項，您可以特別將它列為參數

php composer.phar update monolog/monolog [...]

Packagist#

Packagist.org 是主要的 Composer 存放庫。Composer 存放庫基本上是一個套件來源：您可以從中取得套件的地方。Packagist 的目標是成為所有人都使用的中心存放庫。這表示您可以自動 require 其中任何套件，而無需進一步指定 Composer 應從何處尋找套件。

如果您前往 Packagist.org 網站，您可以瀏覽和搜尋套件。

建議任何使用 Composer 的開源專案在其套件上發佈 Packagist。函式庫不一定要在 Packagist 上才能讓 Composer 使用，但這樣其他開發人員可以更快地發現和採用它。

平台套件#

Composer 有平台套件，這些套件是已安裝在系統上但 Composer 實際上無法安裝的事物的虛擬套件。這包括 PHP 本身、PHP 擴充功能和一些系統函式庫。

• php 代表使用者的 PHP 版本，允許您套用約束，例如 ^7.1。若要需要 64 位元版本的 php，您可以需要 php-64bit 套件。

• hhvm 代表 HHVM 執行時期的版本，允許您套用約束，例如 ^2.3。

• ext-<name> 允許您需要 PHP 擴充功能 (包括核心擴充功能)。版本控管在這裡可能很不一致，因此常不失為將約束設定為 * 的好主意。擴充功能套件名稱的一個範例是 ext-gd。

• lib-<name> 允許限定 PHP 使用的函式庫版本。下列版本可用：curl、iconv、icu、libxml、openssl、pcre、uuid、xsl。

您可以使用 show --platform 取得本機可用平台套件的清單。

自動載入#

針對指定自動載入資訊的函式庫，Composer 會產生 vendor/autoload.php 檔案。您可以包含此檔案，並開始使用那些函式庫提供的類別，無需任何額外的工作

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

$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('Foo');

您甚至可以將自己的程式碼加入自動載入程式，方法是將 autoload 欄位加入 composer.json。

{
    "autoload": {
        "psr-4": {"Acme\\": "src/"}
    }
}

Composer 會註冊一個 PSR-4 自動載入程式，用於 Acme 命名空間。

您定義從命名空間至目錄的對應。src 目錄將會位於您的專案根目錄，與 vendor 目錄處於同一層級。範例檔案名稱為 src/Foo.php，內容為 Acme\Foo 類別。

加入 autoload 欄位後，您必須重新執行此指令

php composer.phar dump-autoload

此指令會重新產生 vendor/autoload.php 檔案。請參閱 dump-autoload 章節，以取得更多資訊。

包含該檔案也會傳回自動載入程式執行個體，因此您可以將包含呼叫的傳回值儲存在變數中，並加入更多命名空間。例如，此作法可應用於自動載入測試套件中的類別。

$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Acme\\Test\\', __DIR__);

除了 PSR-4 自動載入之外，Composer 也支援 PSR-0、類別地圖及檔案自動載入。有關更多資訊，請參閱 autoload 說明。

另請參閱 最佳化自動載入程式的文件。

請注意： Composer 提供自己的自動載入程式。如果您不想要使用它，您可以包含 vendor/composer/autoload_*.php 檔案，它會傳回關聯式陣列，讓您能夠設定自己的自動載入程式。

← 簡介 | 函式庫 →

發現錯字了嗎？此文件中有些地方有問題嗎？分枝並編輯吧！