如何啟用 ServBay 中 PHP 的 Swoole 模組

ServBay 作為功能強大的本機 Web 開發環境，內建了眾多開發者所需的工具與擴充套件，其中包含高效能的 Swoole PHP 擴展。Swoole 是一套專為 PHP 打造的非同步、並行、高性能網路通訊引擎，可顯著提升 PHP 應用的效能與延展性。本文將詳細說明如何在 ServBay 裡輕鬆啟用 Swoole 擴展，幫助您充分運用其強大功能，打造更高效的 PHP 應用與服務。

關於 Swoole 框架

Swoole 是一個開源專案，為 PHP 提供類似 Node.js 的非同步 I/O、協程、多進程等進階功能。藉由 Swoole，PHP 開發者可跳脫傳統 Web 伺服器（例如 Apache/Nginx + PHP-FPM）同步阻塞的模型，建構高效能、常駐記憶體的服務，如：

• 高性能 API 閘道
• 即時通訊應用（WebSocket）
• 遊戲伺服器
• 物聯網 (IoT) 應用
• 後端服務與任務處理

Swoole 的主要特色

1. 高效能：基於 epoll/kqueue 等系統呼叫實現非同步非阻塞 I/O，結合多執行緒/多進程/協程，達到高吞吐與低延遲。
2. 非同步與協程：具備協程能力，讓非同步程式碼能以同步方式撰寫，大幅提升開發效率。
3. 豐富組件：內建 HTTP、WebSocket、TCP、UDP 伺服器與客戶端、連線池、計時器、流程管理等功能。
4. 易於整合：可與現有 PHP 框架（如 Laravel、Symfony、ThinkPHP 等）結合，或用於打造全新的 Swoole 原生應用。

ServBay 對 Swoole 模組的支援

ServBay 針對不同版本的 PHP 預先內建了 Swoole 擴展，無需單獨下載或自行編譯安裝。ServBay 會自動管理各 PHP 版本對應的 Swoole 相容版本。

目前，ServBay 支援下列 PHP 版本啟用 Swoole 擴展：

• PHP 5.6
• PHP 7.x 系列
• PHP 8.x 系列（包含 PHP 8.5）

ServBay 會根據你所選的 PHP 版本，自動匹配並提供相應的 Swoole 擴展檔案。

前置條件

在啟用 Swoole 模組之前，請確定：

• 您已成功安裝並運行 ServBay。
• 您已於 ServBay 中安裝並選取欲使用 Swoole 的 PHP 版本。

啟用 Swoole 模組的操作步驟

ServBay 提供圖形介面與手動編輯設定檔兩種方式啟用 Swoole 模組。建議採用圖形介面方式，直覺且便利。

透過 ServBay 圖形介面啟用（推薦）

這是最簡單且快速啟用 Swoole 模組的方法：

1. 打開 ServBay 圖形使用者介面。
2. 於左側導覽欄選擇 語言 (Languages)。
3. 點選 PHP。
4. 在右側的 PHP 版本列表中，找到您要啟用 Swoole 的 PHP 版本（如：PHP 8.3)，確認該版本呈選取狀態（圓點為綠色）。
5. 點擊該 PHP 版本右側的 擴展 (Extensions) 按鈕。
6. 在彈出擴展列表中找到 swoole 擴展。
7. 點擊 swoole 擴展左側的開關，切換為開啟狀態（開關顯示綠色）。
8. 點選畫面下方的 儲存 (Save) 或 套用 (Apply) 按鈕。
9. ServBay 會提示需重啟相關 PHP 服務載入新擴展，點擊 重啟 (Restart) 按鈕。

待服務重啟完成後，Swoole 模組即成功啟用。

手動編輯設定檔（進階用法）

若您需進階設定，或偏好手動管理設定，可以編輯 PHP 的 ini 檔案啟用 Swoole。

1. 前往指定 PHP 版本的 conf.d 設定資料夾。conf.d 資料夾用於存放額外的 PHP 擴展設定檔，ServBay 會自動載入此資料夾內的 .ini 檔。例如對於 PHP 8.3，路徑常見如下：

   /Applications/ServBay/etc/php/8.3/conf.d/

   請注意，若安裝 ServBay 時選擇了不同安裝路徑，需配合實際路徑調整。

2. 在該目錄下找到並開啟 swoole.ini 檔案。

3. 預設狀況下，啟用 Swoole 的那一行可能已被註解（以 ; 開頭）。尋找如下內容：

   [Swoole]
   ; Uncomment the following line to enable Swoole
   ;extension = swoole.so

4. 刪除 ; 字元，取消 extension = swoole.so 行註解：

   [Swoole]
   ; Uncomment the following line to enable Swoole
   extension = swoole.so

5. 儲存 swoole.ini 檔案。

6. 回到 ServBay GUI 主介面或服務管理面板，找到對應的 PHP 服務，點選重啟按鈕。

等服務重啟後，Swoole 模組便會依照設定檔成功載入。

驗證 Swoole 模組是否啟用成功

最常見的驗證方法是使用 phpinfo() 函數，檢查 PHP 環境已載入模組狀態。

1. 於 ServBay 托管的網站根目錄下（如：/Applications/ServBay/www/servbay.demo/public/），新增名為 phpinfo.php 的檔案。
2. 編輯 phpinfo.php，寫入以下內容：

   <?php
   phpinfo();
   ?>

3. 請確認您的 ServBay 已設定 servbay.demo 這個站台，並指向包含 phpinfo.php 的目錄。
4. 用瀏覽器造訪該檔案對應的網址，例如 https://servbay.demo/phpinfo.php。
5. 在開啟的 phpinfo 頁面中，下滑或使用瀏覽器搜尋功能（Ctrl+F 或 Cmd+F），查詢關鍵字 "swoole"。

若網頁上出現 Swoole 相關資訊（包含版本號、設定選項等），即表示 Swoole 模組已成功載入並啟用。

圖示：於 phpinfo 頁面搜尋 Swoole 資訊

Swoole 使用範例

啟用 Swoole 模組後，您就可以開始撰寫 Swoole 應用程式。以下是一個建立簡易 HTTP 伺服器的示範。

範例程式碼：打造簡單 Swoole HTTP 伺服器

1. 建立專案資料夾
   在您的開發目錄（譬如 /Applications/ServBay/www/ 下新建一個資料夾），建一個新專案目錄，如 my-swoole-app。於該目錄下新增 public 資料夾做為入口檔案存放處。

   cd /Applications/ServBay/www/
   mkdir my-swoole-app
   cd my-swoole-app
   mkdir public

2. 建立伺服器入口檔 public/index.php

   <?php
   
   require __DIR__ . '/../vendor/autoload.php'; // 若您有使用 Composer 安裝其他相依套件
   
   use Swoole\Http\Server;
   use Swoole\Http\Request;
   use Swoole\Http\Response;
   
   // 建立 HTTP 伺服器實例，監聽所有本地 IP (0.0.0.0) 的 9501 埠口
   $server = new Server("0.0.0.0", 9501);
   
   // 設定伺服器參數（可略）
   // $server->set([
   //     'worker_num' => 4, // 工作進程數量
   //     'daemonize' => false, // 是否以守護行程方式執行
   // ]);
   
   // 監聽請求事件
   $server->on("request", function (Request $request, Response $response) {
       // 設定回應標頭
       $response->header("Content-Type", "text/plain");
   
       // 設定回應內容
       $response->end("Hello ServBay with Swoole!");
   });
   
   // 監聽伺服器啟動事件（可略）
   $server->on("start", function (Server $server) {
       echo "Swoole http server is started at http://0.0.0.0:9501\n";
   });
   
   // 啟動伺服器
   $server->start();
   
   echo "Swoole server stopped.\n"; // 這行程式碼只會在伺服器停止後執行

   說明：範例中的 require __DIR__ . '/../vendor/autoload.php'; 僅當您用 Composer 安裝了其他 Swoole 相關庫（如 swoole/ide-helper 或 Swoole 框架）時才需要，否則可刪除。若純用 Swoole 原生功能，通常不必加 autoload.php。

3. 從指令列啟動伺服器
   開啟 ServBay 的終端機（Terminal）功能，或系統內建終端機，進入您的專案目錄（/Applications/ServBay/www/my-swoole-app/）。請確認終端機使用的是 ServBay 管理的 PHP 版本（可執行 which php 查路徑，或用 ServBay 的終端功能）。

   執行下列指令啟動 Swoole 伺服器：

   php public/index.php

   若一切順利，終端機會顯示 "Swoole http server is started at http://0.0.0.0:9501"。

   圖示：終端機執行 Swoole 伺服器成功畫面

4. 測試連線
   伺服器啟動後，打開瀏覽器輸入 http://localhost:9501，應可看到頁面顯示 "Hello ServBay with Swoole!"。

   若要終止 Swoole 伺服器，請在終端機按下 Ctrl + C。

注意事項

• 運行方式：上述範例為於終端直接啟動 Swoole 伺服器，適合開發常駐記憶體型服務。傳統 Web 應用（如 Laravel/Symfony/WordPress 等）多數是以 PHP-FPM 模式執行，再由 Caddy 或 Nginx 代理。若你希望在 Swoole 環境跑這些框架（如 Hyperf、Swoole-Laravel 等），通常需搭配框架的專用啟動指令，運作方式與 Swoole 原生範例類似，皆為獨立進程。
• 埠口占用：Swoole 伺服器會監聽指定埠口（此例為 9501），請確保該埠口未被其他程式佔用。
• 錯誤日誌：Swoole 的錯誤與輸出訊息通常直接顯示於啟動終端機；也可依設定輸出至指定日誌檔。

常見問題集 (FAQ)

Q: 已在 ServBay GUI 啟用 Swoole，為什麼 phpinfo() 頁面找不到 Swoole 資訊？

A: 請檢查以下事項：

1. 請確認正在查看的是正確 PHP 版本的 phpinfo() 頁面。ServBay 可同時執行多個 PHP 版本，請核對您拜訪的網站或終端機使用的 PHP 是否為已啟用 Swoole 的版本。
2. 請確保已於 ServBay GUI 儲存設定並順利重啟相對應 PHP 服務。
3. 如有手動編輯 swoole.ini，請再次檢查檔案路徑、檔名及 extension = swoole.so 那行是否正確且未註解。

Q: 執行 Swoole 範例時出現 Class 'Swoole\Http\Server' not found？

A: 這代表當前 PHP 環境並未正確載入 Swoole 擴展。請依前述步驟重查 Swoole 是否啟用，並確定你在終端上用的是 ServBay 管理、且已啟動 Swoole 的 PHP 版本。可在終端機執行 php -m | grep swoole 快速檢查命令行下 PHP 是否已載入 Swoole 模組。

結語

利用 ServBay，啟用 PHP 的 Swoole 擴張變得極為輕鬆。不論是用直觀的圖形介面，或手動編輯設定檔，開發者均可為選定的 PHP 版本迅速載入 Swoole，開展高效能、非同步 Web 應用開發之路。透過 Swoole 強大的能力，您可以靈活打造反應更快、併發量更高的 PHP 服務，發揮 PHP 在現代 Web 開發的最大潛能。ServBay 也提供完善的環境管理支援，讓您專注於程式實作，而無需煩擾環境設定細節。