使用 Composer 管理 PHP 套件

Composer

因為不要重造輪子,所以我們就要借助別人的輪子來打造自己的工具,當借助的輪子越來越多,管理起來就會有點麻煩,不管是版本的更新或是大家都使用某個熱門的輪子而造成重覆,這些都需要一個工具來管理,這就是 Composer 要幫我們解決的事。

安裝

Composer 是 PHP 的套件管理工具,官網是 https://getcomposer.org/

在 Mac/Linux 下載及安裝 Composer 的步驟

  1. 下載 composer-setup.php 安裝程式
    php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
    
    請確認你已經先安裝好 PHP 才能執行上述指令。
  2. 檢查已下載的檔案
    php -r "if (hash_file('SHA384', 'composer-setup.php') === 'e115a8dc7871f15d853148a7fbac7da27d6c0030b848d9b3dc09e2a0388afed865e6a3d6b3c0fad45c48e2b5fc1196ae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
    
    確保檔案沒被竄改。顯示「Installer verified」表示沒問題。
  3. 執行安裝
    php composer-setup.php
    
  4. 刪除安裝檔
    php -r "unlink('composer-setup.php');"
    
    最後結果會產生一個 composer.phar 檔案,這就是 PHP 的套件管理工具。
  5. 全域指令
    這個 composer.phar 工具目前只能在所屬的目錄下才能執行,這樣使用上有點麻煩,可以把它移動到我們自己的指令目錄,當成全域指令。同時改名為 composer 方便輸入:
    mv composer.phar /usr/local/bin/composer
    
    註:前提是 /usr/local/bin 已經加入 $PATH 中。

在 Windows 的安裝

先下載 Composer-Setup.exe 後執行即可安裝。

更新

要知道目前的 composer 版本號,使用選項:
composer -V
目前 Composer 的最新版本是 1.2.4 (2016-12-06),日後如果需要更新,可以使用指令來更新:
composer self-update
這個指令會下載穩定(stable)版本,如果要下載預覽版(pre-release),可以加入選項:
composer self-update --preview

使用 Composer 管理套件

這裡示範如何安裝 monolog/monolog 套件。如果要順便練習,可以先建立一個空目錄,然後在其中做接下來的操作。

使用 require

在命令列切換到專案目錄下,輸入:
composer require monolog/monolog
指令執行完成後,在目錄下會出現 composer.json、composer.lock 兩個檔案及 vendor 目錄,安裝的套件會放在 vendor 目錄中。

因為 monolog/monolog 有用到 psr/log,所以你在 vender 目錄中會看到除 monolog 目錄之外,還同時多了 psr 目錄,這是套件提供者的目錄名稱,在它之內則會有以套件名稱為名的目錄。

psr/log 對 monolog/monolog 來說,就是一個相依套件,當你的套件越裝越多的時候,你也不用去煩惱如何管理,Composer 會幫你處理。

另外,在安裝訊息中,會出現一堆 suggests installing 的訊息,這是建議你去安裝這些它推薦的套件,這只是建議,有需要在下載即可。

註:如果你有使用 git ,記得把 vendor 目錄加入 .gitignore 中,套件不需要被 commit。只要有 composer.lock 或 composer.json 在執行以下介紹的指令就能下載相關的套件了。

使用 update

你也可以先編寫 composer.json,指定需要使用的套件及版本,然後輸入指令:
composer update
Composer 會讀取 composer.json 去下載指定的套件及版本,完成後會自動產生 composer.lock(如果已有則會將其更新)。
有時候你只想更新某一套件到最新版本:
composer update 套件提供者/套件名稱

使用 install

當你的專案中已經有 composer.lock,可以直接執行
composer install
Composer 就會安裝 composer.lock 中指定的套件及版本。

關於 composer.json 檔

composer.json 是一個 json 資料格式的設定檔,提供資訊給 Composer,讓它知道要安裝什麼套件,及該套件的版本。
內容如下:
{
    "require": {
        "monolog/monolog": "^1.21"
    }
}

關於 composer.lock 檔

composer.lock 會明確列出這個專案中用到的套件及它的版本,可以用來確保其他人使用到同一個版本號的套件。
composer.lock 這個檔案不可以手動建立,它會在執行 install 或 update 之後自動產生或更新。

何時用 install ? 何時用 update ?

composer install 指令會先去找 composer.lock,如果有,則依其中所指定的版本安裝,無論該套件是否有新版本;如果沒有,則會讀取 composer.json 來安裝,並且產生 composer.lock。

在沒有 composer.lock 檔的情況下,執行 composer install 的行為等同於 composer update

使用 composer update 指令,會去讀取 composer.json,並且安裝最新版本,同時更新 composer.lock。

這裡所謂的「安裝最新版本」是指 composer.json 檔中該套件所指定的版本上限,如果你指定為固定版本,例如 1.0.0,那無論如何 update 都只會安裝該版本。

假如你有修改過 composer.json 當你執行 composer install 時,Composer 會提醒你 composer.lock 及 composer.json 不同步,要求你執行 composer update

一般來說,只有當你確定要更新套件版本,或是第一次下載套件時,才用 update;如果你是從別人那裡拿到專案(例如github),而專案目錄中已經有 composer.lock,最安全的做法是使用 install,這樣可以確保安裝的套件版本和原專案的開發者使用的是同一個版本號。使用 update 的風險在於,你可能會安裝到最新的版本,而這有可能造成程式執行時因為不相容而發生錯誤。

套件版本號

版本號的組成:主版本號 . 副版本號 . 修正版本號
通常主版本號的跳號表示可能有部份功能會無法向下相容;副版本號則是會增加一些新功能,但仍可向下相容;修正版本號則是一些錯誤的修正,而且向下相容。
想知道更多可以參考 語意化版本 2.0.0

套件版本的指定只有三種目的:
  • 固定版本,例如:1.0.0
  • 指定下限,例如:>=1.0.0
  • 指定上下限,例如:>=1.0.0,<2.0.0
表示方式雖然有很多種,但目的都一樣。通常指定上限的原因,是怕更新了主或副版本號後發生不相容所做的保護性限制。

明確指定

明確表示要使用的版本號,例如:
  • 1.0.0

範圍指定

比較運算子
使用比較運算子 >,>=,<,<=,!= 的組合來表示上下限,可以使用 || 表示 OR;使用空白逗號表示 AND。
例如:
  • >=1.0
  • >=1.0 <2.0
  • >=1.0,<1.1 || >=1.2
連字號(-)
  • 1.0 - 2.0 相當於 >=1.0.0 <2.1
萬用字元(*)
  • 1.0.* 相當於 >=1.0 <1.1
    表示不管修正版號如何增加都無所謂,只要主副版號相同即可。
波浪符號(~)
如果只有指定副版本號,則在副版本號之上,但主版本號不動;
如果指定修正版本號,則在修正版本號之上,但副版本號不動。
  • ~1.2 相當於 >=1.2 <2.0.0
  • ~1.2.3 相當於 >=1.2.3 <1.3.0
跳脫符號(^)
最接近語意化版本的格式,例如:
  • ^1.2.3 相當於 >=1.2.3 <2.0.0
  • ^0.3 相當於 >=0.3.0 <0.4.0

Composer 常用指令整理

初始化

以對話方式幫你產生 composer.json,如果你要發佈自己的套件,會方便很多。
composer init

檢查 composer.json

如果有手動更新 composer.json 檔,可以用這個指令檢查。
composer validate

依 composer.lock 安裝套件

composer install
composer install --dev
composer install --no-dev
--dev 選項是預設值所以可以不輸入,也就是會安裝屬於 dev 部份的套件。如果不需要,可以使用 --no-dev 來指示不要安裝。

依 composer.json 更新套件

composer update
composer update --dev
composer update --no-dev
composer update 套件提供者/套件名稱

請求安裝

composer require 套件提供者/套件名稱
composer require 套件提供者/套件名稱:版本號
composer require 套件提供者/套件名稱=版本號

移除已安裝的套件

composer remove 套件提供者/套件名稱

顯示套件資訊

composer show 套件提供者/套件名稱
composer show //顯示已安裝的套件清單
composer info //和 show 相同功能

全域安裝套件

將套件安裝成全域而非單一專案。
composer global require 套件提供者/套件名稱:版本號

列出 Composer 的所有指令

composer list

顯示某個指令的說明

composer help 指令

更新 Composer

composer self-update
composer selfupdate
composer self-update --preview

套件庫

尋找套件

要查看有什麼套件可以使用,可以到 Packagist 套件庫中尋找。

建立套件

如果想建立自己的套件,必須先將套件的程式碼 push 到 GitHub 上,然後在 Packagist 註冊帳號後,將套件所在的 GitHub 的資料連結到 Packagist 中,這樣就可以讓別人安裝使用了,詳細的內容可以參考 How to submit packages
如果要建立私人用的套件,可以參考 Hosting your own 的說明。

參考資料

本文網址:http://blog.tonycube.com/2016/12/composer-php.html
Tony Blog 撰寫,轉載時請註明出處及文章連結,謝謝 😀

我要留言

留言小提醒:
1.回覆時間通常在晚上,如果太忙可能要等幾天。
2.請先瀏覽一下其他人的留言,也許有人問過同樣的問題。
3.程式碼請先將它編碼後再貼上。(線上編碼:http://bit.ly/1DL6yog)
4.文字請加上標點符號及斷行,難以閱讀者恕難回覆。
5.感謝您的留言,您的問題也可能幫助到其他有相同問題的人。