如何使用 ServBay 自帶的 Composer 進行 PHP 專案管理
ServBay 作為一款強大的本地 Web 開發環境,已為開發者預先安裝 Composer,大幅簡化了 PHP 專案的依賴管理。Composer 是現代 PHP 開發不可或缺的依賴管理工具,可協助開發者輕鬆整合管理第三方套件,自動處理複雜的依賴關係,並提供便捷的自動載入功能。有了 ServBay,您無需額外安裝或設定 Composer,即可直接加速 PHP 的開發流程。
Composer 簡介
Composer 是一種管理 PHP 專案依賴的工具。它允許開發者宣告專案所需的外部函式庫(通常稱為套件),並自動安裝與更新這些依賴項。Composer 不僅能管理 PHP 函式庫,也支援其他類型的套件,如框架、元件、外掛等。
主要特色
- 依賴管理:Composer 可自動處理專案的相依關係,確保所有函式庫的版本相容,並解決潛在衝突。
- 自動載入:Composer 提供了自動載入功能,會產生統一的自動載入檔案,讓開發者無需手動
include
或require
,即可使用由 Composer 安裝的類別文件。 - 版本控管:開發者可在
composer.json
檔案中指定依賴函式庫的版本規則,Composer 會根據這些約束下載合適版本;同時透過composer.lock
檔案鎖定當前已安裝的具體版本,確保團隊成員與不同環境下均使用相同的依賴版本。 - 套件管理:Composer 主要利用 Packagist 中央倉庫來查找與下載套件,開發者可以輕鬆找到並引用幾乎所有主流的 PHP 開源函式庫。
- 社群資源豐富:Composer 擁有龐大且活躍的開發者社群與完善的文件資源。
ServBay 內建 Composer
ServBay 整合了多個 PHP 版本,且在安裝時自動為您準備好 Composer。這代表您無需額外下載或設定 Composer。ServBay 會確保 Composer 在您的系統中可用,且通常與當前啟用的 PHP 版本綁定,讓您直接在專案終端操作 composer
或 composer-2.2
命令。
提示
Composer 分為最新版 Composer 2.8.x
及兼容舊版 PHP 的 Composer 2.2.x LTS
,分別對應 PHP 7.2+
與 PHP 5.3 - PHP 7.1
。
ServBay 預設安裝為 Composer 2.8.x
,適用於 PHP 7.2+
。
若需於 PHP 5.3 - PHP 7.1
之間使用,請至「軟體包」中安裝 Composer 2.2.x LTS
,安裝後請使用指令 composer-2.2
。兩個版本彼此獨立,互不衝突。
利用 Composer 管理專案依賴
Composer 透過專案根目錄下的 composer.json
來管理依賴套件。以下為建立與使用 composer.json
的基本步驟:
1. 建立 composer.json
檔案
在您的 PHP 專案根目錄下建立一個名為 composer.json
的檔案。例如,若您在 /Applications/ServBay/www/my_php_project
目錄下工作,請在此目錄中建立該檔。
composer.json
是一個 JSON 結構,require
鍵用來列出專案所需的依賴。鍵名為套件名稱(通常為 vendor/package
格式),值為期望的版本約束。
例如,要安裝 Monolog(常用 PHP 日誌函式庫),且版本需為 2.0 或以上:
json
{
"require": {
"monolog/monolog": "^2.0"
}
}
1
2
3
4
5
2
3
4
5
當中的 ^2.0
表示相容於 2.0.0 及以上但不含 3.0.0 的版本。
2. 安裝依賴套件
進入含有 composer.json
的專案根目錄,於終端輸入以下指令安裝依賴:
sh
composer install
1
執行後:
- Composer 會讀取
composer.json
。 - 計算所有依賴(包括您指定和它們自身依賴)。
- 下載依賴至專案目錄下的
vendor
目錄。 - 產生
composer.lock
,精準記錄現有所有套件的版本——此檔極為重要,建議提交至版本控制(如 Git),以統一協作者及環境的依賴版本。 - 產生自動載入檔
vendor/autoload.php
。
安裝成功後,專案中會新增 vendor
目錄與 composer.lock
檔案。
利用 Composer 的自動載入
Composer 最大優勢之一即自動載入機制。它遵循各種自動載入規範(如 PSR-0、PSR-4)來映射類別名稱與檔案路徑,並產生統一的自動載入檔。
如何設定與使用:
1. 設定 autoload
欄位
於 composer.json
補充或修改 autoload
欄位。舉例,以 PSR-4 標準將 App\
命名空間映射至專案根下的 src/
:
json
{
"require": {
"monolog/monolog": "^2.0"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
這代表凡是以 App\
開頭的類別,Composer 會自動在 src/
內依命名空間與類名尋找對應檔案(如 App\MyClass
會對應到 src/MyClass.php
)。
2. 重新產生自動載入檔案
每當您變動 autoload
配置時,需要執行此指令重新整理自動載入映射:
sh
composer dump-autoload
1
此命令會重建 vendor/autoload.php
。若僅安裝或更新依賴且未更動自動載入,執行 composer install
或 composer update
也會自動處理。
3. 在原始碼中載入自動載入檔案
於 PHP 腳本開頭引入 Composer 產生的自動載入檔:
php
<?php
// 引入 Composer 自動載入檔案
require __DIR__ . '/vendor/autoload.php';
// 現在可以直接使用 Composer 安裝的類別或 autoload 設定的類別
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use App\MyClass; // 若已設定 App\ 命名空間自動載入
// 使用 Monolog 函式庫
$log = new Logger('name');
$log->pushHandler(new StreamHandler('your.log', Logger::WARNING));
$log->warning('這是一個警告!');
// 使用您自己的類別 (若已設定 autoload)
// $myObject = new MyClass();
// $myObject->doSomething();
?>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
上述 require __DIR__ . '/vendor/autoload.php';
一行,讓您能於整個專案中自由調用各套件類別,不必手動維護大量 require
或 include
,極大簡化專案結構。
更新依賴套件
隨著專案發展與套件升級,您可能需更新現有函式庫版本。
終端進入專案根目錄,執行:
sh
composer update
1
composer update
會檢查composer.json
所列所有依賴及其子依賴是否有新版本,且符合規則。- 若有新版,Composer 會自動下載並安裝。
- 過程結束後,Composer 也會刷新
composer.lock
,記錄全新版本狀態。
重要提醒:
composer install
與composer update
差異:composer install
用於首次建置或現有專案安裝依賴——它會忠實依據composer.lock
版本,確保一致性;composer update
則用於升級符合composer.json
規則的最新套件,並同步更新composer.lock
。團隊協作時,除非確需升級,通常只在更新套件時執行composer update
,並務必提交更新後的composer.json
和composer.lock
。
在 ServBay 環境中使用 Composer 的注意事項
ServBay 專為本地開發打造,選用 Composer 時請注意:
- 終端環境:請確認於 ServBay 環境內終端執行 Composer 指令。ServBay 會自動將已選 PHP 版本添加至 PATH,所以您可直接在新終端視窗用
php
與composer
。若遇到command not found
,試著重開終端或檢查 ServBay 是否運行中。 - PHP 版本切換:ServBay 容易讓您切換 PHP 版本。
composer
會搭配當前 ServBay 面板啟用的 PHP 版本。若需某專案用特定 PHP 版本(如只支援舊版),請預先在 ServBay 面板切換版本後再執行 Composer。 - 專案目錄位置:建議將專案放在 ServBay 預設網站根
/Applications/ServBay/www
子目錄,並在控制面板設定對應網站,便於瀏覽器存取。於專案根目錄執行 Composer 命令即可。
範例專案:使用 GuzzleHttp 套件
以下為一個簡易範例,示範如何在 ServBay 環境下安裝並使用 GuzzleHttp(熱門 PHP HTTP 客戶端)。
建立專案資料夾並進入: 於 ServBay 網站根目錄建立新資料夾,並切換進該目錄:
shcd /Applications/ServBay/www mkdir guzzle_demo.servbay.demo cd guzzle_demo.servbay.demo
1
2
3此處目錄名遵循 ServBay 品牌規範範例網域格式。
建立
composer.json
檔案: 在guzzle_demo.servbay.demo
裡建立composer.json
,內容如下:json{ "require": { "guzzlehttp/guzzle": "^7.0" }, "autoload": { "psr-4": { "App\\": "src/" } } }
1
2
3
4
5
6
7
8
9
10同步配置 PSR-4 自動載入,即便此簡單範例未用到,亦為好習慣。
安裝依賴: 在該專案目錄下執行:
shcomposer install
1Composer 會下載 GuzzleHttp 及其依賴,並新建
vendor
資料夾與composer.lock
。建立 PHP 檔並調用依賴套件: 新建
index.php
檔案於專案根目錄:php<?php // 引入 Composer 自動載入檔案 require __DIR__ . '/vendor/autoload.php'; use GuzzleHttp\Client; use GuzzleHttp\Exception\RequestException; echo "<h1>GuzzleHttp Demo</h1>"; echo "<pre>"; try { // 建立 Guzzle 客戶端實例 $client = new Client(); // 發送 GET 請求 $response = $client->request('GET', 'https://httpbin.org/get', [ 'query' => ['param1' => 'value1', 'param2' => 'value2'] ]); // 取得回應內容 $body = $response->getBody()->getContents(); echo "Response Body:\n"; echo $body; // 取得回應狀態碼 $statusCode = $response->getStatusCode(); echo "\n\nStatus Code: " . $statusCode; } catch (RequestException $e) { // 處理請求異常 echo "Request Exception:\n"; echo $e->getMessage(); if ($e->hasResponse()) { echo "\nResponse Status: " . $e->getResponse()->getStatusCode(); echo "\nResponse Body: " . $e->getResponse()->getBody()->getContents(); } } catch (\Exception $e) { // 其他錯誤處理 echo "An error occurred:\n"; echo $e->getMessage(); } echo "</pre>"; ?>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44此檔案先引入自動載入,然後利用 GuzzleHttp 客戶端發送 API 請求並輸出結果。
網站配置於 ServBay: 開啟 ServBay 面板,進入「網站」分頁(原「主機」)。點選新增,設置網站指向
/Applications/ServBay/www/guzzle_demo.servbay.demo
目錄,網域設為guzzle_demo.servbay.demo
。儲存並重啟 Web 伺服器(如 Caddy 或 Nginx)。瀏覽器存取測試: 於瀏覽器進入
http://guzzle_demo.servbay.demo/
。您應會看到 PHP 執行結果,顯示由https://httpbin.org/get
抓取的資料。
常見問題 (FAQ)
Q: 我用 PHP 5.6 無法正常運作 Composer,怎麼辦?
A: ServBay 內建主流 2.8.x 與兼容舊 PHP 的 2.2.x LTS 兩種 Composer。支援 PHP 5.6 請安裝 Composer 2.2 LTS
,並以指令 composer-2.2
來使用。
Q: 在終端執行 composer
命令時顯示 command not found
,怎麼處理?
A:
- 請確認 ServBay 應用已啟動。
- 嘗試關閉並重新開啟您的終端視窗。ServBay 啟動時會設定所需環境變數,須於新視窗再度加載。
- 確認 ServBay 控制面板已啟動至少一個 PHP 版本。
- 若仍有問題,可嘗試用 ServBay 特定 PHP 版本之完整路徑執行 Composer,例如
/Applications/ServBay/php/8.2/bin/php /usr/local/bin/composer install
(路徑以實際安裝為準,但 ServBay 設計原則上讓您能直接使composer
指令)。
Q: 怎樣指定 Composer 使用 ServBay 的特定 PHP 版本?
A: Composer 指令會以 ServBay 面板目前選定並啟動的 PHP 版本執行。若欲切換,僅需於 ServBay 面板 PHP 分頁選擇目標版本後,於新終端視窗執行 composer
。
Q: composer.lock
有何用途?需提交至 Git 嗎?
A: composer.lock
詳實記錄您上次運行 composer install
或 composer update
時所有套件的版本。強烈建議將 composer.lock
一併提交到版本控制(如 Git)。這可保證團隊全員及各部署環境依賴版本一致,避免「只在我電腦能跑」的問題,確保穩定而一致的佈署。團隊成員複製或重新安裝時,Composer 會優先依據 composer.lock
進行安裝,而非僅以 composer.json
中版本約束。
總結
ServBay 透過預載及整合 Composer,為 PHP 開發者帶來高效便捷的本地開發體驗。您可無痛切換 PHP 版本、輕鬆管理專案依賴、自動載入類別,專注於原始碼撰寫,提升效率與專案品質。將 ServBay 結合 Composer,絕對是現代 PHP 專案管理建構與維運的強大利器。