建立並執行 Phalcon 專案

什麼是 Phalcon？

Phalcon 是一個開源、高效能的 PHP Web 框架，以 C 擴充套件形式實作。由於這項獨特的架構，Phalcon 佔用資源極少、執行速度極快，在性能表現上顯著優於多數傳統 PHP 框架。Phalcon 採用 MVC（模型-檢視-控制器）架構，並提供豐富功能元件，包含 ORM（物件關聯對映）、模板引擎、路由、快取、事件管理等，可協助你快速開發功能齊全且高效率的網站及 API。

Phalcon 的主要特色及優勢

• 極致效能：以 C 延伸模組執行，避免 PHP 腳本解析與加載延遲，達到原生級速度與表現。
• 資源效率高：佔用記憶體非常低，非常適合對效能和擴展性有高需求的專案。
• 功能豐富：內建多數 Web 應用所需核心模組，減少對第三方套件的依賴。
• 易於學習與操作：API 清晰一致，且文件完善，初學者也能快速上手。
• 高度解耦：各元件獨立設計，可依專案需要自由選用或替換特定模組。
• 安全性加強：內建多項安全元件，如輸入過濾、CSRF 防護等。

如果你需要打造極高效能且可擴展的 Web 應用或 API，Phalcon 絕對是理想首選，尤其適合對資源利用及速度有嚴格要求的情境。

使用 ServBay 建立並執行 Phalcon 專案

ServBay 是專為 macOS 設計的本地 Web 開發環境，整合多版本 PHP、常用資料庫（如 MySQL, PostgreSQL, MongoDB, Redis）、Web 伺服器（Caddy, Nginx, Apache）及其他開發工具。透過 ServBay，你可以輕鬆架設及管理 Phalcon 專案所需環境。

本教學將引導你在 ServBay 的 PHP 環境下建立基本 Phalcon 專案、配置 Web 伺服器並使其可正常瀏覽，同時示範如何連接關聯式資料庫（MySQL）與 NoSQL 資料庫（Redis）。

前置條件

在開始之前，請確認以下條件皆已滿足：

1. ServBay 已安裝並啟動：請先於 macOS 上順利安裝並啟動 ServBay。
2. 所需 PHP 版本已啟用：在 ServBay 內啟用你打算使用的 PHP 版本。
3. Phalcon 模組已啟用：ServBay 已內建 Phalcon，但預設未必開啟。請依照 如何啟用 ServBay 內建的 Phalcon 模組 文件說明開啟指定 PHP 版本並重啟 PHP。
4. Composer 可正常使用：ServBay 內建 Composer，無需額外安裝。請確定你可在終端機直接執行 composer 指令。

Phalcon 各版本與 DevTools 對應

Phalcon 框架及其配套開發工具 (Phalcon DevTools) 必須和你選用的 PHP 版本相容。下表列出常見 PHP 版本與建議使用的 Phalcon 與 DevTools 對應：

PHP 版本	推薦 Phalcon 版本	推薦 DevTools 版本	注意事項
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1（或 4.3.x）
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x（官方）	官方 DevTools 在 PHP 8.x 可能有相容性問題。
PHP 8.3, 8.4	Phalcon 5.x	dev-master（修正版倉庫）	建議使用社群修正版提升相容性。

重要提醒：若使用 PHP 8.x 以上版本，官方 Phalcon DevTools 相容性不佳。請按建議採用社群修正版。後續建專案流程會說明如何用 Composer 安裝修正版 DevTools。

建立 Phalcon 專案

建議網站資料夾路徑

為便於管理，ServBay 建議全部網站專案均放在網站根目錄 /Applications/ServBay/www。範例也將於此建立新專案。

1. 切換至網站根目錄並新增專案資料夾

   開啟終端機，前往 ServBay 網站根目錄，並新建你的 Phalcon 專案資料夾（如 servbay-phalcon-app）：

   cd /Applications/ServBay/www
   mkdir servbay-phalcon-app
   cd servbay-phalcon-app

2. 安裝 Phalcon DevTools

   Phalcon DevTools 是一套命令列工具，能協助產生程式骨架、管理資料庫遷移等。可用 Composer 安裝，依你的 PHP 版本指令略有不同：

   • PHP 5.6, 7.0, 7.1 (DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • PHP 7.2, 7.3, 7.4 (DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • PHP 8.0 以上（DevTools 修正版 dev-master）: 因官方 DevTools 不完全支援 PHP 8.x，需以社群修正版安裝。請先於專案根目錄 (/Applications/ServBay/www/servbay-phalcon-app) 建立或編輯 composer.json，加入修正版倉庫設定：

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     接著執行 Composer 更新安裝 DevTools：

     composer update

   完成後，Composer 會於專案根目錄（servbay-phalcon-app）產生 vendor/bin/phalcon 執行檔。

3. 使用 DevTools 產生專案骨架

   利用剛安裝好的 DevTools 產生 Phalcon 專案基本結構。預設會將程式放於一個子目錄（如也叫 servbay-phalcon-app）：

   vendor/bin/phalcon project servbay-phalcon-app

   這會於 /Applications/ServBay/www/servbay-phalcon-app 內建立子資料夾 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app 並產生完整專案骨架。

4. 進入程式碼目錄

   切換至新建立的專案目錄，後續操作都在此進行：

   cd servbay-phalcon-app

   現在你所在路徑應為 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app。

配置專案環境

Phalcon 專案設定通常寫在 app/config/config.php。你需在此指定資料庫連線資訊及其他重要設置。

1. 編輯設定檔

   用熟悉的編輯器開啟 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php。找到或新增資料庫設定區。ServBay MySQL/MariaDB 預設帳號為 root，密碼空白，但強烈建議自行設定密碼。範例用 password 為佔位，請依你的實際資料寫入。資料庫名 servbay_phalcon_app 僅作範例，你需手動建立此資料庫。

   return new \Phalcon\Config([
       // ... 其他設定 ...
       'database' => [
           'adapter' => 'Mysql', // 或 'Postgres' 等
           'host' => '127.0.0.1',
           'username' => 'root', // ServBay 預設 root 帳號
           'password' => 'password', // <-- 請換成你的密碼
           'dbname' => 'servbay_phalcon_app', // <-- 請換成你的資料庫
       ],
       // ... 其他設定 ...
   ]);

   注意：必須確保你已啟動 ServBay 的資料庫服務（如 MySQL/MariaDB），且登入密碼符合設定。你也需手動建立 servbay_phalcon_app 資料庫，可用 ServBay 的資料庫管理工具（如 phpMyAdmin 或 Adminer）操作。

配置 Web 伺服器（使用 ServBay 網站功能）

要從瀏覽器存取你的 Phalcon 專案，請用 ServBay 的「網站」功能設置虛擬主機並指向專案的可瀏覽目錄。

1. 開啟 ServBay 應用程式
2. 進入「網站」設定：在主介面點選「網站」。
3. 新增網站：按下「新增網站」鈕。
   • 名稱：設定容易辨識的名稱，例如 My First Phalcon Dev Site。
   • 網域：自訂欲用於瀏覽器的網域，如 servbay-phalcon-test.local。ServBay 會自動將 .local 解至本地端。
   • 網站型態：選擇 PHP。
   • PHP 版本：挑選已啟用 Phalcon 模組之 PHP 版本。
   • 網站根目錄：Phalcon 專案入口檔一般在 public 內，根目錄請指向 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public。
4. 儲存設定：儲存完畢，ServBay 會自動套用變更，可能需重啟 Web 伺服器（Caddy 或 Nginx）。

完整操作請見 新增第一個網站。設置完後，ServBay 會自動處理網域本機解析及伺服器設定。

新增範例程式

下面加入幾段簡易程式以驗證專案是否運作正常。

1. 設置路由

   編輯 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php，新增處理根路徑 / 的簡單路由：

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // 設定預設路徑，把根目錄 '/' 指向 IndexController 的 indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... 可再加入其他路由設定 ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. 新增控制器

   編輯或新增 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php，加入簡易 indexAction 方法：

   <?php
   namespace App\Controllers; // 請確保命名空間正確
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // 處理根目錄 '/' 請求
       public function indexAction()
       {
           // 回傳一段簡單文字
           return 'Hello ServBay!';
       }
   }

瀏覽網站

儲存所有檔案後，確認 ServBay 運作正常。打開瀏覽器，輸入你設定的網域：

https://servbay-phalcon-test.local

如一切正常，你會在頁面看到 Hello ServBay! 字樣。

整合資料庫功能

Phalcon 具備強大資料庫抽象層及 ORM，ServBay 整合多種資料庫，能輕鬆與 Phalcon 專案串接。以下以 MySQL 和 Redis 為例說明。

關聯式資料庫：MySQL

下面展示如何使用 Phalcon 的資料庫介接器連線至 ServBay MySQL 並執行插入查詢。

1. 建立資料表架構（使用遷移）

   Phalcon DevTools 支援資料庫遷移，可進行結構版本控管。

   • 產生遷移檔：於程式目錄 (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app) 執行產生空遷移檔指令：

     vendor/bin/phalcon migration generate

     會在 migrations 下建立新檔名類似 YYYYMMDDHHMMSS_MigrationName.php 的檔案。

   • 編輯遷移檔：於新檔案的 morph 方法內定義 users 表：

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // 需與檔名類型一致
     {
         /**
          * Run the migrations
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * Reverse the migrations
          *
          * @return void
          */
         public function down()
         {
             // 可選：回滾方法，例如直接刪除資料表
             // $this->getConnection()->dropTable('users');
         }
     }

     注意：Class 名稱如 UsersMigration_100 須與檔案名稱一致。

   • 執行遷移：於程式目錄下執行指令建立資料表：

     vendor/bin/phalcon migration run

     若連線失敗，請檢查 app/config/config.php 設定或 ServBay MySQL/MariaDB 是否啟動。

2. 資料庫連線設定（先前已設置）

   請確認 app/config/config.php 的 'database' 區段指向 ServBay 的 MySQL/MariaDB（預設 host 為 127.0.0.1，port 3306，user root，密碼按你的設定）。

3. 新增路由

   編輯 app/config/routes.php 加入插入與查詢用戶資料的路由：

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // 插入用戶路由
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // 查詢用戶路由
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. 於控制器實作資料庫操作

   編輯 app/controllers/IndexController.php，加入 mysqlAddAction 與 mysqlAction：

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // 匯入 MySQL 介接器
   use Phalcon\Db\Enum; // fetchAll 模式常數
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // 新增用戶範例
       public function mysqlAddAction()
       {
           // 直接建立資料庫連線（實際應用建議服務化）
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- 請更換你的密碼
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
           // 插入範例用戶
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', 'demo@servbay.test'],
               ['name', 'email']
           );
           // 顯示結果
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // 查詢用戶範例
       public function mysqlAction()
       {
            // 建立連線
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- 請更換你的密碼
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
           // 查詢全部用戶
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           // JSON 輸出
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   注意：實際專案請將資料庫連線設為服務於控制器注入，而非每 action 新建連線。

5. 瀏覽示例

   • 瀏覽 https://servbay-phalcon-test.local/mysql-add。成功時會顯示 "User added successfully."
   • 再瀏覽 https://servbay-phalcon-test.local/mysql。可看到 users 資料表的 JSON 資料，包含你新增的記錄。

NoSQL 資料庫：Redis

以下展示如何在 Phalcon 專案中使用 ServBay 的 Redis 快取。

1. 安裝 Redis 延伸模組

   ServBay PHP 普遍已內建 Redis 延伸。只需確認你使用的 PHP 版本有啟用 Redis。

2. 設定 Redis 連線

   於 app/config/config.php 加入 Redis 連線設定，ServBay Redis 預設在 127.0.0.1 的 6379 port。

   return new \Phalcon\Config([
       // ... 其他設定 ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Redis 資料庫索引，預設 0
           'persistent' => false, // 是否持久連線
           'auth' => null, // 若有密碼則填
       ],
       // ... 其他設定 ...
   ]);

3. 新增快取路由

   編輯 app/config/routes.php，加一條 Redis 範例路由：

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // Redis 快取範例路由
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. 於控制器使用 Redis 快取

   編輯 app/controllers/IndexController.php，新增 redisAction 方法：

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // 匯入 Redis 快取器
   use Phalcon\Storage\SerializerFactory; // 匯入序列化工廠
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Redis 快取示例
       public function redisAction()
       {
           // 建立序列化工廠
           $serializerFactory = new SerializerFactory();
           // Redis 設定
           // 注意：此設定須與 config.php cache 部分一致
           $options = [
               'defaultSerializer' => 'Json', // 預設為 JSON 存儲
               'lifetime'          => 3600, // 有效期（秒）
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'your_redis_password',
           ];
           // 產生 Redis 快取器
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // 嘗試取快取
   
           if ($cachedData === null) {
               // 快取不存在
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Data stored in cache.";
           } else {
               // 快取已存在
               echo "Data found in cache: ";
           }
           // 回傳快取內容
           return $cachedData;
       }
   }

   注意：正式專案建議快取設定服務化集中管理。

5. 瀏覽快取範例

   瀏覽 https://servbay-phalcon-test.local/redis。

   • 首次進入會看到 "Data not found in cache, fetching from source...Data stored in cache." 及 "Data fetched from source: Hello Redis from ServBay!"。
   • 再訪問會顯示 "Data found in cache: " 及 "Data fetched from source: Hello Redis from ServBay!"，說明資料已從 Redis 快取取得。

常見問題集 (FAQ)

• Q: 網站顯示 404 Not Found 怎麼辦？
  • A: 報錯多半是網站根目錄未正確指到 Phalcon 的 public 資料夾（/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public）。請檢查 ServBay 設定、Web 伺服器（Caddy/Nginx）運作及網域解析。
• Q: Phalcon 模組未找到（如 Class 'Phalcon\Mvc\Application' not found）？
  • A: 這代表你選用的 PHP 尚未啟用 Phalcon。回 ServBay 介面勾選正確 PHP 版本的 Phalcon 並重啟 PHP。詳參 如何啟用 ServBay 內建的 Phalcon 模組。
• Q: 資料庫連線失敗？
  • A: 檢查 app/config/config.php 的資料庫連線設定（主機、帳號、密碼、資料庫名稱），並確認 ServBay MySQL/MariaDB 有正常啟動。用戶權限及資料庫也要事先設定妥當。

結語

運用 ServBay，你能輕鬆建立 Phalcon 框架的高效能本地開發環境。本篇說明從專案骨架生成、Web 伺服器設定，到資料庫（MySQL/Redis）整合等核心流程。ServBay 豐富的軟體整合與簡單易用管理介面，大幅降低本地開發環境配置與維護難度，讓你能更加專注在 Phalcon 程式本身的開發。希望此教學可以助你順利開始用 ServBay + Phalcon 開發高品質網站！