Composer 基本使用

基本用法

引言

介紹基本用法，我們将安裝 monolog/monolog 日志庫作為範例。如果你還沒有安裝 Composer，請參閱

Composer 安裝

章節。

注意：為簡便起見，我們假定你已經 本地 安裝了 Composer。

composer.json：項目設定

若要在項目中使用 Composer 你需要一個 composer.json 檔案。該檔案描述了你的項目依賴關系和其他中繼資料。

require 鍵

首先（通常也是唯一）應該做的事情就是在你的 composer.json 檔案中定義好 require 鍵。你應該簡要告訴 Composer 你的項目所依賴的包有哪些。

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

如上所示， require 擷取了一個包名稱 （例如 monolog/monolog）映射到版本限制 （例如 1.0.*）的 json 對象。

Composer 使用該資訊去「版本庫」中搜尋，你在 Composer.json 中注冊的 repositories 鍵所指定的版本倉庫中的相關合适的檔案，或是在 Packagist 中預設的包庫。在上述示例中，因為沒有其他在 composer.json 檔案中注冊的版本庫資訊，是以它認為 monolog/monolog 包預設是在 Packagist 中。（更多 Packagist 資訊請參閱如下，或在此閱讀更多相關資訊。

包名稱

包名由供應商名稱和項目名稱組成。通常情況下，這些名稱是相同的，供應商名稱的存在則很好的解決了命名沖突。 例如，它允許兩個不同的人建立同樣名為 Json 的庫。 可以命名為 igorw/json 和 seldaek/json。

在這裡您可以閱讀更多有關釋出包和包命名的内容。

注意，您還可以指定 “平台包” 作為依賴項，這允許您自定義某些版本的伺服器軟體。請參閱下面的平台軟體包

包版本限制

在上面的示例中，我們引入的 monolog 版本指定為 1.0.*。這表示任何從 1.0 開始的開發分支，它将會比對 大于或等于 1.0 且小于 1.1 的版本。

請閱讀關于版本的更深入資訊，如何互相關聯或如何版本控制。

Composer 如何下載下傳正确的檔案？當您在 composer.json 中指定一個依賴項時， Composer 首先擷取您所請求的包的名稱，并在已使用庫密鑰注冊的任何存儲庫中搜尋它。如果您沒有注冊任何額外的存儲庫，或者它在您指定的存儲庫中找不到具有該名稱的包，則傳回到 Packagist （下面是詳細說明）。

當 Composer 在打包器中找到正确的包時，或者在已指定的包的儲存庫，它使用包的 VCS （即分支和标簽）的版本化特性來嘗試找到您指定的版本限制的最佳比對。請務必閱讀有關版本和包聲明的文章。

注意：如果您試圖擷取一個包，但 Composer 抛出關于包穩定性的錯誤，則您指定的版本可能無法滿足預設的最小穩定性要求。預設情況下，隻有在搜尋 VCS 中的有效包版本時才會考慮穩定的版本。

如果你也想獲得 DEV、Alpha、Beta 或 RC 版本。請閱讀更多關于穩定标志和 minimum-stability key on the schema page。

安裝依賴關系

使用 install指令為你的項目安裝已經定義好的依賴關系

php composer.phar install

運作該指令，composer 會根據情況通過以下兩種方式中的一種進行安裝

非 composer.lock 安裝

如果你之前從未運作過指令就不會出現 composer.lock 檔案，Composer 隻會解析你在 composer.json 檔案中列出的依賴關系并且下載下傳最近版本到你項目 vendor 目錄中 ( vendor 是項目中存放所有第三方代碼的正常目錄)。在我們上面的例子中，你最終會在

vendor/monolog/monolog/

目錄中看到所有 Monolog 的源檔案。如果 Monolog 有任何依賴，也将會出現在 vendor/ 中.

提示：如果你的項目中使用了 git, 或許你希望将 vendor 添加到 .gitignore 中。因為将所有第三方包添加到版本庫裡面看起來很傻。

當 Composer 完成安裝後，它将把所有下載下傳的包和确切的版本資訊寫入到 composer.lock 檔案，以此來鎖定項目中第三方包的版本。你應該将 composer.lock 放在項目倉庫中，以便該項目所有成員都能鎖定在依賴關系相同的版本

使用 composer.lock 檔案安裝

這裡來到了第二種安裝方式。如果你在運作 composer install 指令之前已經存在了 composer.lock 和 composer.json 檔案， 這意味着你之前使用了 install 指令， 或者項目中的其他成員使用了 install 指令并将 composer.lock 檔案送出至了項目中 (這是非常好的)。

無論使用哪種方式，存在 composer.lock 檔案時使用 install 指令安裝依賴時 composer.lock 都會解析并安裝你在 composer.json 中所列出來的依賴，但是 Composer 會嚴格使用 composer.lock 檔案列出來的版本來確定項目中的所有成員所安裝的版本都是一緻的。是以，你可以獲得 composer.json 檔案列出的所有檔案，但是與此同時他們可能并不是最新的可用版本 (一些在 composer.lock 檔案中列出的依賴可能會在這個檔案建立之後釋放了新的版本)。這個是設計上的，這樣的設計可以確定你的項目不會因為一些依賴的改變而崩潰。

送出你的 composer.lock 檔案至版本控制工具

将此檔案送出至 VC 是非常重要的。因為它可以確定項目中的任何人使用的都是與你是完全一緻的依賴。 你的 CI 伺服器，生産伺服器，團隊的其他開發人員，所有人都使用的是相同的依賴項，這減輕了僅部署某些部分而引起錯誤的可能性。即使你獨立開發，在你重新安裝項目的 6 個月内，你的依賴項釋出了許多新的版本，你依然可以确信你的依賴項是可用的。(請參閱下邊有關使用 update 的指令。)

更新依賴到最新版本

如上所述，composer.lock 檔案将阻止你自動擷取最新依賴版本。如果要更新依賴到最新版本，使用 update 指令。這将擷取最新比對的版本（根據你的 composer.json 檔案）并将新版本更新到 composer.lock 檔案。（這相當于删除 composer.lock 檔案并再次運作 install）。

php composer.phar update

注意：當執行 install 指令時，由于 composer.json 的更改可能影響到依賴解析而未更新 composer.lock ，Composer 将顯示警告。

如果隻是想安裝或更新一個依賴，可以将它們列出來：

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

注意：對于庫來說，沒必要送出 composer.lock 檔案，請參考：庫 - 鎖檔案。

Packagist

Packagist 是 Composer 的主要資源庫。一個 Composer 庫基本上是一個包的源：一個你可以得到包的地方。

Packagist 的目标是成為一個任何人都可以使用的中央倉庫。這意味着你可以 require 那裡的任何包，無需指定 Composer 查找包的位置。

當你通路 Packagist 網站 (packagist.org)，你可以浏覽和搜尋包。

建議使用 Composer 的開源項目在 Packagist 上釋出包。雖然并不一定需要釋出在 Packagist 上來被 Composer 使用，但是它能被其它的開發者更快的發現和采用。

平台包

Composer 将那些已經安裝在系統上，但并不是由 Composer 安裝的包視為虛拟的平台包。這包括 PHP 本身、PHP 擴充和一些系統庫。

php 代表使用的 PHP 版本要求，允許你應用限制，例如 ^7.1 。如果需要 64 位版本的 PHP， 你可以使用 php-64bit 進行限制。

hhvm 代表 HHVM 運作環境的版本，并且允許你應用限制 ，例如，^2.3。

ext- 允許你依賴 PHP 擴充（包括核心擴充）。通常 PHP 拓展的版本可以是不一緻的，将它們的版本限制為 * 是一個不錯的主意。一個 PHP 擴充包的例子是：ext-gd。

lib- 允許對 PHP 庫的版本進行限制。以下可用例子： curl， iconv， icu，libxml，openssl， pcre， uuid， xsl。

你可以使用指令 show --platform 去擷取你本地可用的平台包。

自動加載

為了描述包的自動加載資訊， Composer 會生成一個 vendor/autoload.php 檔案，你可以簡單的 include 這個檔案，并在無需其它額外工作的情況下就可以使用這些包所提供的類：

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

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

你甚至可以在 composer.json 中添加一個 autoload 指令，來添加自己的自動加載聲明

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

Composer 會為 Acme 命名空間注冊一個 PSR-4 的自動加載.

你定義一個命名空間指向目錄的映射。 在 vendor 目錄同級的 src 目錄将成為你項目的根目錄。一個案例，檔案名 src/Foo.php 需包含 AcmeFoo 類。

添加 autoload 指令之後，你必需重新運作 dump-autoload 來重新生成 vendor/autoload.php 檔案。

包含此檔案後也可以接收到一個 autoloader 執行個體，由是以您可以将 include 調用的傳回值存儲在變量中并添加更多名稱空間，這在測試套件中将會很有用，例如：

$loader = require DIR . '/vendor/autoload.php';

$loader->addPsr4('Acme\Test\', __DIR__);

作為 PSR-4 自動加載規範的補充，Composer 也支援 PSR-0、類表、檔案清單的自動加載方式。具體請查詢 autoload 引用。

你也可以查閱 optimizing the autoloader 了解關于自動加載器的優化.

注意：Composer 提供自己的加載器，但如果你不想使用那個而想自己配置加載器的話，你可以試試 include vendor/composer/autoload_*.php 這些檔案所傳回的關聯數組來實作。