如何使用 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"
    }
}

當中的 ^2.0 表示相容於 2.0.0 及以上但不含 3.0.0 的版本。

2. 安裝依賴套件

進入含有 composer.json 的專案根目錄，於終端輸入以下指令安裝依賴：

composer install

執行後：

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/"
        }
    }
}

這代表凡是以 App\ 開頭的類別，Composer 會自動在 src/ 內依命名空間與類名尋找對應檔案（如 App\MyClass 會對應到 src/MyClass.php）。

2. 重新產生自動載入檔案

每當您變動 autoload 配置時，需要執行此指令重新整理自動載入映射：

composer dump-autoload

此命令會重建 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();

?>

上述 require __DIR__ . '/vendor/autoload.php'; 一行，讓您能於整個專案中自由調用各套件類別，不必手動維護大量 require 或 include，極大簡化專案結構。

更新依賴套件

隨著專案發展與套件升級，您可能需更新現有函式庫版本。

終端進入專案根目錄，執行：

composer update

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 網站根目錄建立新資料夾，並切換進該目錄：
sh
```
cd /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/"
         }
     }
}

同步配置 PSR-4 自動載入，即便此簡單範例未用到，亦為好習慣。

安裝依賴：在該專案目錄下執行：
sh
```
composer install
```
1
Composer 會下載 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>";
?>

此檔案先引入自動載入，然後利用 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，怎麼處理？

請確認 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 專案管理建構與維運的強大利器。

如何使用 ServBay 自帶的 Composer 進行 PHP 專案管理 ​

Composer 簡介 ​

主要特色 ​

ServBay 內建 Composer ​

利用 Composer 管理專案依賴 ​

1. 建立 composer.json 檔案 ​

2. 安裝依賴套件 ​

利用 Composer 的自動載入 ​

1. 設定 autoload 欄位 ​

2. 重新產生自動載入檔案 ​

3. 在原始碼中載入自動載入檔案 ​

更新依賴套件 ​

在 ServBay 環境中使用 Composer 的注意事項 ​

範例專案：使用 GuzzleHttp 套件 ​

常見問題 (FAQ) ​

總結 ​

如何使用 ServBay 自帶的 Composer 進行 PHP 專案管理

Composer 簡介

主要特色

ServBay 內建 Composer

利用 Composer 管理專案依賴

1. 建立 `composer.json` 檔案

2. 安裝依賴套件

利用 Composer 的自動載入

1. 設定 `autoload` 欄位

2. 重新產生自動載入檔案

3. 在原始碼中載入自動載入檔案

更新依賴套件

在 ServBay 環境中使用 Composer 的注意事項

範例專案：使用 GuzzleHttp 套件

常見問題 (FAQ)

總結