在 ServBay 中啟用高效能 Phalcon PHP 框架模組

ServBay 是一個專為開發者打造的強大本機 Web 開發環境，整合多項主流技術堆疊。對於 PHP 開發者而言，ServBay 已預先內建高效能的 Phalcon 框架模組，並且提供極為簡易的啟用流程。Phalcon 以其快速且高效率著稱，其模組化架構協助開發者打造高效 Web 應用。

Phalcon 框架簡介

Phalcon 是一套開源、功能完整的 PHP 框架，以卓越性能與極低資源消耗聞名。不同於多數以純 PHP 開發的框架，Phalcon 採用 C 語言撰寫，並作為 PHP 延伸模組加載執行。這種獨特的架構讓 Phalcon 在效能上具備明顯優勢，同時也提供強大且完整的功能組合。

主要特色

高效能：Phalcon 以 C 延伸模組直接運行於底層，相較於純 PHP 框架，具備更快執行速度，並大幅減少記憶體與 CPU 佔用。
低資源消耗：Phalcon 最佳化設計能在高併發請求時仍保持卓越效能，降低系統負載。
功能豐富：內建完整 MVC 架構支援；強大的 ORM（物件關聯對應）、模板引擎、靈活的路由系統、快取、佇列服務等，滿足各項複雜 Web 開發需求。
易於上手：雖然框架核心以 C 編寫，但開發人員仍然可用熟悉的 PHP 語法開發應用，且擁有清晰 API 與豐富文件，學習與上手門檻低。
模組化設計：各組件高度解耦與模組化，開發者能依專案需求自由挑選、替換特定元件。

ServBay 預載的 Phalcon 模組版本

ServBay 提供多款主流 PHP 版本，並為這些版本預載對應的 Phalcon 模組。ServBay 持續更新 PHP 版本與相關套件，確保技術跟進最新潮流。Phalcon 模組版本與 PHP 版本保持相容，具體資訊可於 ServBay 軟體包管理介面查看。以下為常用 PHP 版本及所對應的 Phalcon 版本列表（請注意 ServBay 可能支持更多或較新版本）：

PHP 5.6, 7.0, 7.1：Phalcon 3.4.5
PHP 7.2, 7.3, 7.4：Phalcon 4.1.2
PHP 8.0, 8.1, 8.2, 8.3：Phalcon 5.7.0
PHP 8.4, 8.5-dev：Phalcon 5.8.0

如何啟用 Phalcon 模組

在 ServBay 中啟用 Phalcon 模組的步驟非常直觀。為了維持極致輕量環境，Phalcon 模組預設可能為停用狀態。透過 ServBay 圖形介面即可快速啟用。

推薦方式：透過 ServBay 圖形介面啟用

這是最推薦且最簡便的啟用方法：

開啟 ServBay 應用程式。
至左側選單選擇 語言 (Languages)。
在套件列表中找到欲啟用 Phalcon 的 PHP 版本，例：PHP 8.3 或 PHP 8.4。
點擊該 PHP 版本右側的 擴展模組 (Extensions) 按鈕。
在彈出的擴展列表尋找 Phalcon 模組。
點擊 Phalcon 模組左側的開關鈕，切換為開啟。
按下視窗底部的 儲存 (Save) 按鈕。
ServBay 會提示您需要重新啟動對應 PHP 服務以生效，點擊確認重啟。

重啟後，Phalcon 模組便已成功掛載於指定 PHP 版本。

進階：手動編輯設定檔啟用（高階用戶適用）

需要自動化配置或進行高階除錯時，亦可手動編輯 PHP 設定檔開啟 Phalcon 模組。

步驟一：找到設定檔

先定位欲啟用 PHP 版本的 conf.d 目錄，這裡為 PHP 擴展模組設定檔所存放之處。例如，若要為 PHP 8.3 啟用 Phalcon 模組，該設定檔一般位於：

bash

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

以文字編輯器打開此檔案。

步驟二：編輯 Phalcon 設定檔

找到下列內容，將 extension = phalcon.so 行前的分號 ; 移除，即可啟用該擴展：

ini

[Phalcon]
; Uncomment the following line to enable Phalcon
extension = phalcon.so

修改後結果應為：

ini

[Phalcon]
extension = phalcon.so

步驟三：啟用 PSR 模組（僅適用於 PHP 7.2 - PHP 7.4）

注意：如已透過 ServBay 圖形介面啟用 Phalcon，可略過此步驟。

於 PHP 7.2 ~ 7.4 版本，Phalcon 需依賴 PSR（PHP Standards Recommendations）擴展模組。ServBay 已預載 PSR，只需確認已經啟用。於 phalcon.ini 或對應的 PSR 設定檔（通常為 psr.ini）內，確保以下行無註解：

ini

; Uncomment both Psr & Phalcon to enable Phalcon
[Psr]
extension = psr.so

[Phalcon]
extension = phalcon.so

步驟四：重啟 PHP 服務

不論使用圖形介面或手動編輯設定，任何 PHP 擴展設定變更後，都必須重啟對應 PHP 服務始能生效。

於 ServBay 主介面或 軟體包 (Packages) 頁面，找到剛剛編輯設定的 PHP 版本，點擊旁邊的重啟按鈕（通常為循環箭頭圖示），即可重啟該服務。

驗證 Phalcon 模組是否已載入

最常見的驗證方式是查閱 PHP 運行時資訊（phpinfo()）。

於任一 ServBay 設定的網站根目錄，建立一個名為 phpinfo.php 的新檔，例如您的網站 servbay.demo 根目錄為 /Applications/ServBay/www/servbay.demo，則直接於該目錄新建 phpinfo.php。
在 phpinfo.php 檔案內容鍵入：
php
```
<?php
phpinfo();
?>
```
1
2
3
以瀏覽器造訪該網站對應的網址，如 https://servbay.demo/phpinfo.php。
於網頁輸出資料尋找 "Phalcon" 相關區塊，若可見相關配置信息、版本號，即表示模組已載入。

圖：於 phpinfo 輸出中尋找 Phalcon 資訊

使用範例

Phalcon 模組啟用後，即可直接於 ServBay 開發 Phalcon 應用。以下為創建一個基本 Phalcon 應用並於 ServBay 執行之範例說明。

假設您預計將專案檔案放於 /Applications/ServBay/www/phalcon-demo 目錄。

步驟一：建立專案資料夾結構

依 Phalcon 建議結構，建立如下目錄：

/Applications/ServBay/www/phalcon-demo/
├── app/
│   ├── controllers/
│   │   └── IndexController.php
│   └── views/
│       └── index/
│           └── index.phtml
└── public/
    └── index.php

步驟二：設定 ServBay 網站

於 ServBay 建立一組新 網站 (Website) 設定，將網域設為 phalcon-demo.servbay.demo，網站根目錄指向專案 public 資料夾（/Applications/ServBay/www/phalcon-demo/public），並確保選用已啟用 Phalcon 模組的 PHP 版本。

步驟三：撰寫範例程式碼

前端控制器：public/index.php
為應用進入端點。

php

<?php

use Phalcon\Autoload\Loader;
use Phalcon\Di\FactoryDefault;
use Phalcon\Mvc\View;
use Phalcon\Mvc\Url;
use Phalcon\Mvc\Application;

// 定義專案根目錄及應用程式目錄常數
define('BASE_PATH', dirname(__DIR__)); // 指向 /Applications/ServBay/www/phalcon-demo
define('APP_PATH', BASE_PATH . '/app'); // 指向 /Applications/ServBay/www/phalcon-demo/app

// 註冊自動加載器，用於載入控制器及模型
$loader = new Loader();
$loader->setDirectories(
    [
        APP_PATH . '/controllers/',
        APP_PATH . '/models/', // 若有模型，註冊模型目錄
    ]
);
$loader->register();

// 建立 DI 容器
$container = new FactoryDefault();

// 於 DI 容器註冊視圖服務
$container->set(
    'view',
    function () {
        $view = new View();
        $view->setViewsDir(APP_PATH . '/views/'); // 設定視圖檔目錄
        return $view;
    }
);

// 於 DI 容器註冊 URL 服務
$container->set(
    'url',
    function () {
        $url = new Url();
        $url->setBaseUri('/'); // 設定基底 URL
        return $url;
    }
);

// 實例化 Phalcon 應用
$application = new Application($container);

try {
    // 處理請求並輸出回應
    $response = $application->handle(
        $_SERVER["REQUEST_URI"]
    );

    $response->send();

} catch (\Exception $e) {
    // 捕捉例外並輸出錯誤訊息
    echo 'Exception: ', $e->getMessage();
}

?>

控制器：app/controllers/IndexController.php
首頁請求的控制邏輯。

php

<?php

use Phalcon\Mvc\Controller;
use Phalcon\Support\Version; // 引入 Version 類以獲取 Phalcon 版本

class IndexController extends Controller
{
    // 預設 Action
    public function indexAction()
    {
        // 取得當前 Phalcon 版本號
        $phalconVersion = new Version();
        $versionString = $phalconVersion->get();

        // 傳遞版本號至視圖
        $this->view->phalconVersion = $versionString;

        // 渲染 app/views/index/index.phtml 視圖
    }
}

視圖：app/views/index/index.phtml
呈現歡迎訊息及 Phalcon 版本號的視圖檔。

html

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Hello ServBay with Phalcon</title>
        <style>
            body { font-family: sans-serif; margin: 40px; text-align: center; }
            h1 { color: #333; }
            p { color: #666; }
        </style>
    </head>
    <body>
        <h1>Hello ServBay!</h1>
        <p>您已成功在 ServBay 中運行 Phalcon 應用。</p>
        <p>目前 Phalcon 版本：**<?= $phalconVersion ?>**</p>
    </body>
</html>

步驟四：訪問應用

請確保 ServBay 的 Nginx/Caddy 及選用的 PHP 版本皆已啟動。以瀏覽器造訪設定的網域，如 https://phalcon-demo.servbay.demo。您應可見畫面顯示「Hello ServBay!」及當前 Phalcon 版本號。

圖：成功執行之 Phalcon 範例應用

注意事項

請確定所選 PHP 版本與專案所需 Phalcon 版本相容。
編輯設定檔後務必重啟對應 PHP 服務。
若遇到問題，優先查閱 PHP 錯誤日誌與 Web 伺服器（Nginx/Caddy）錯誤日誌，可於 /Applications/ServBay/var/log/ 目錄找到。

常見問題集 (FAQ)

Q1: 已依指示啟用 Phalcon，卻在 phpinfo() 看不見 Phalcon？

A1: 請檢視下列事項：

確認修改的是正確 PHP 版本設定檔（若以手動方式修改）。
確認 extension = phalcon.so 沒有被分號 ; 註解。
確認重新啟動了對應 PHP 服務。
確認網站設定使用的是啟用 Phalcon 的該 PHP 版本。
查閱 ServBay PHP 錯誤日誌，看是否有載入擴展失敗提示。

Q2: 我的 Phalcon 應用運行出現 Class 'Phalcon\...' not found 錯誤？

A2: 通常代表 Phalcon 模組尚未正確載入於目前 PHP 環境。請依照本文重新執行啟用與驗證步驟，確認所用 PHP 版本已載入 Phalcon，且可於 phpinfo() 見到資訊。若模組確定載入無誤，請檢查您的應用程式碼是否有命名空間或自動加載設定上的錯誤。

Q3: 使用 Phalcon 會需要其他依賴嗎？

A3: 對於 PHP 7.2 至 7.4，Phalcon 需依賴 PSR 擴展。ServBay 已預載 PSR，只需於 phalcon.ini 同時啟用 extension = psr.so 與 extension = phalcon.so 即可。自 PHP 8.0 及以上，Phalcon 5.x 通常不再須單獨啟用 PSR，因已內部涵蓋所需標準。

結語

ServBay 大幅簡化了本機開發環境中 Phalcon 框架的安裝及啟用流程。無論透過直覺式圖形介面或簡單設定檔編輯，開發者皆可隨時為不同 PHP 版本啟用高效能 Phalcon 模組。搭配 ServBay 建全的 Web 技術堆疊整合，您可迅速打造功能完善、性能卓越的本機開發環境，高效率開發 Phalcon 為基礎的現代化 Web 應用。在 Phalcon 超強效能加持下，讓您的應用滿足高速響應與資源優化的需求。

在 ServBay 中啟用高效能 Phalcon PHP 框架模組 ​

Phalcon 框架簡介 ​

主要特色 ​

ServBay 預載的 Phalcon 模組版本 ​

如何啟用 Phalcon 模組 ​

推薦方式：透過 ServBay 圖形介面啟用 ​

進階：手動編輯設定檔啟用（高階用戶適用） ​

步驟一：找到設定檔 ​

步驟二：編輯 Phalcon 設定檔 ​

步驟三：啟用 PSR 模組（僅適用於 PHP 7.2 - PHP 7.4） ​

步驟四：重啟 PHP 服務 ​

驗證 Phalcon 模組是否已載入 ​

使用範例 ​

步驟一：建立專案資料夾結構 ​

步驟二：設定 ServBay 網站 ​

步驟三：撰寫範例程式碼 ​

步驟四：訪問應用 ​

注意事項 ​

常見問題集 (FAQ) ​

結語 ​