建立並運行 Phalcon 專案
什麼是 Phalcon？
Phalcon 是一款開源、高效能的 PHP Web 框架，以 C 延伸（Extension）的形式實現。其特殊架構能大幅降低資源消耗，執行效能明顯優於多數傳統 PHP 框架。Phalcon 遵循 MVC（模型-視圖-控制器）設計，內建多元功能組件，包括 ORM（物件關聯對映）、模板引擎、路由、快取、事件管理器等，協助開發者快速打造功能強大且高效能的 Web 應用與 API。
Phalcon 的主要特性與優勢
- 極致效能：以 C 延伸運行，省去 PHP 腳本解譯與載入的額外負擔，帶來近乎原生層級效能。
- 資源高效：記憶體佔用極低，非常適合對擴充性與效能有高度需求的應用。
- 功能齊全：內建大多數核心 Web 組件，減少依賴第三方函式庫。
- 容易上手：API 規範、文件詳盡，即使新手也能快速學習入門。
- 高度解耦：各組件獨立設計，開發者可依實際需求自由選用或替換組件。
- 安全性：內建一系列安全性組件，如輸入過濾、CSRF 防護等。
Phalcon 非常適合用來建構高效能、可擴展的 Web 應用及 API，特別適用於對速度與資源運用極致要求的專案。
使用 ServBay 建立並運作 Phalcon 專案
ServBay 是專為 macOS 設計的本機 Web 開發環境，整合多版本 PHP、資料庫（MySQL、PostgreSQL、MongoDB、Redis）、Web 伺服器（Caddy、Nginx、Apache）及多種開發工具。善用 ServBay，您可快速架設與管理 Phalcon 專案所需之運行環境。
本教學將逐步帶領您利用 ServBay 的 PHP 環境，建立基本 Phalcon 專案、配置 Web 伺服器、整合關聯式資料庫（MySQL）與 NoSQL（Redis）。
前置條件
開始前，請確保您已經：
- 安裝並啟動 ServBay：已於 macOS 上安裝並成功啟動 ServBay。
- 啟用所需 PHP 版本：在 ServBay 內勾選並啟用了欲使用的 PHP 版本。
- 啟用 Phalcon 模組：ServBay 已內建 Phalcon 模組，預設未啟用。請依 如何啟用 ServBay 內建 Phalcon 模組 的說明，於對應 PHP 版本啟用 Phalcon 延伸，並重啟 PHP 服務。
- Composer 可用：ServBay 已內建 Composer，無需額外安裝。確認可於終端機直接執行
composer指令。
不同版本 Phalcon 與 DevTools 搭配
Phalcon 框架與其開發工具（Phalcon DevTools）需與您使用的 PHP 版本相容。下表為常見 PHP 版本與推薦 Phalcon/DevTools 對照關係：
| PHP 版本 | 推薦 Phalcon 框架版本 | 推薦 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 下。本教學亦以此為範例。
進入網站根目錄並建立專案資料夾
於終端機進入 ServBay 網站根目錄，並新建 Phalcon 專案專用資料夾（例如
servbay-phalcon-app）：bashcd /Applications/ServBay/www mkdir servbay-phalcon-app cd servbay-phalcon-app1
2
3安裝 Phalcon DevTools
Phalcon DevTools 為命令列工具組，協助快速生成專案骨架、管理資料庫遷移等。請根據欲用 PHP 版本，執行不同安裝指令：
針對 PHP 5.6、7.0、7.1（Phalcon DevTools
^3.4）:bashcomposer require phalcon/devtools:"^3.4"1針對 PHP 7.2、7.3、7.4（Phalcon DevTools
~4.1）:bashcomposer require phalcon/devtools:"~4.1"1針對 PHP 8.0、8.1、8.2、8.3、8.4（Phalcon DevTools
dev-master修正版）: 官方 DevTools 對 PHP 8.x 支援有限，需用社區修正版。於現有專案根目錄/Applications/ServBay/www/servbay-phalcon-app建立或編輯composer.json，加入修正版倉庫設定：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 }1
2
3
4
5
6
7
8
9
10
11
12
13接著執行更新：
bashcomposer update1
Composer 會於專案目錄（
servbay-phalcon-app）下建立vendor目錄，執行檔路徑為vendor/bin/phalcon。利用 DevTools 產生專案骨架
執行剛安裝的 DevTools 指令產生 Phalcon 專案基本檔案結構。預設會將專案程式碼放於子資料夾（例如同名的
servbay-phalcon-app）：bashvendor/bin/phalcon project servbay-phalcon-app1此指令會於
/Applications/ServBay/www/servbay-phalcon-app下產生/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app子目錄，裡面包含完整 Phalcon 專案骨架。進入專案程式碼目錄
進入剛新建的程式碼目錄，所有後續操作皆於此目錄下進行：
bashcd servbay-phalcon-app1您此時位置應為
/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app。
專案環境設定
Phalcon 專案設定一般集中於 app/config/config.php，需於此指定資料庫連線資訊、應用路徑等重要設定。
編輯設定檔
用喜愛的程式編輯器開啟
/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php，找到或新增資料庫設定。ServBay 的 MySQL/MariaDB 預設用戶為root，預設無密碼。為安全起見，強烈建議您自行設置密碼。示範使用password作為佔位；資料庫名稱servbay_phalcon_app僅為範例，請依實際狀況調整（需自行建立）。phpreturn new \Phalcon\Config([ // ... 其他設定 ... 'database' => [ 'adapter' => 'Mysql', // 或 'Postgres'... 'host' => '127.0.0.1', 'username' => 'root', // ServBay 預設 root 'password' => 'password', // <-- 請改為您設定的密碼 'dbname' => 'servbay_phalcon_app', // <-- 請改為您的資料庫名稱 ], // ... 其他設定 ... ]);1
2
3
4
5
6
7
8
9
10
11重要：請確認在 ServBay 已啟用對應資料庫服務（MySQL/MariaDB），且用戶與密碼正確無誤。資料庫需自行建立，可利用 ServBay 的 phpMyAdmin 或 Adminer 管理工具操作。
設定 Web 伺服器（經由 ServBay 網站功能）
若要透過瀏覽器存取您的 Phalcon 專案，請利用 ServBay 的 網站 功能建立虛擬主機，並指向專案公開瀏覽目錄。
- 開啟 ServBay 主程式
- 到「網站」設定：ServBay 主介面點選「網站」。
- 新增網站：點擊新增網站按鈕。
- 名稱：如
My First Phalcon Dev Site。 - 網域：設定欲於瀏覽器訪問的網域，例如
servbay-phalcon-test.local。ServBay 會自動將.local指向本機。 - 網站類型：選擇
PHP。 - PHP 版本：挑選已啟用 Phalcon 模組所用的 PHP 版本。
- 網站根目錄：重點！Phalcon 專案入口
index.php通常在public目錄，因此需指向：/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public。
- 名稱：如
- 存檔設定：儲存新網站，ServBay 會自動套用變更，可能需重啟 Web 伺服器（Caddy 或 Nginx）。
詳情請參見新增第一個網站。完成後，ServBay 會處理網域本地解析與伺服器設定。
新增範例程式碼
新增簡易範例程式驗證專案正常運作。
設定路由
編輯
/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php，加入簡單路由規則處理根目錄/：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;1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19建立控制器
編輯
/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php（如不存在請新建），加入簡單的indexAction方法：php<?php namespace App\Controllers; // 確保命名空間正確 use Phalcon\Mvc\Controller; class IndexController extends Controller { // 處理根目錄 '/' 的請求 public function indexAction() { // 回傳簡易字串作為響應 return 'Hello ServBay!'; } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
存取網站
儲存所有檔案後，確認 ServBay 運作中。打開瀏覽器，造訪於 ServBay 設定的網域：
https://servbay-phalcon-test.local
若設定無誤，將看到畫面顯示 Hello ServBay!。
資料庫整合
Phalcon 具備強大資料庫抽象層與 ORM。ServBay 整合多種資料庫，您能輕易將其與 Phalcon 結合。以下以 MySQL 與 Redis 為例：
關聯式資料庫範例：MySQL
將示範如何透過 Phalcon 的資料庫適配器連線 ServBay MySQL、執行新增與查詢：
建立資料結構（使用遷移）
DevTools 支援資料庫遷移，便於管理欄位結構。
產生遷移檔：於專案程式碼目錄
/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app執行：bashvendor/bin/phalcon migration generate1會在
migrations新增遷移檔，檔名如YYYYMMDDHHMMSS_MigrationName.php。編輯遷移檔：開啟該檔案，於
morph方法中定義users資料表結構：php<?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'); } }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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70注意：類名（如
UsersMigration_100）需與檔名一致。執行遷移：於程式碼目錄內執行
bashvendor/bin/phalcon migration run1若遇連線錯誤，請再檢查
app/config/config.php之資料庫設定與 ServBay 的資料庫服務狀態。
確認資料庫連線設定（前述已完成）
檢查
app/config/config.php中'database'配置是否正確指向 ServBay 運作中的 MySQL（預設host是127.0.0.1，port 3306，root 用戶，密碼依您的設定）。新增範例路由
編輯
app/config/routes.php，新增插入與查詢資料路由：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;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控制器內實作資料庫操作
編輯
app/controllers/IndexController.php，新增mysqlAddAction和mysqlAction方法：php<?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() { // 直接建立資料庫連線（建議開發時用 DI 管理） $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', '[email protected]'], // 值 ['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', ]); // 查詢所有 user 資料 $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC); // 以 JSON 輸出 header('Content-Type: application/json'); echo json_encode($users); } }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
45
46
47
48
49
50
51
52
53
54
55
56
57備註：實務上建議將連線包含於服務管理（Service Container），再於控制器透過注入取得。
範例操作說明
- 於瀏覽器造訪
https://servbay-phalcon-test.local/mysql-add，如顯示 "User added successfully." 則表示成功插入。 - 再前往
https://servbay-phalcon-test.local/mysql，將看到users表內容 JSON 輸出。
- 於瀏覽器造訪
NoSQL 資料庫範例：Redis
以下展示於 Phalcon 中整合 ServBay 的 Redis 快取服務。
確認 Redis 擴展已啟用
ServBay 內建常用擴展（含 Redis），毋須自行安裝。請於 ServBay PHP 擴展設定檢查 Redis 已勾選。
設定 Redis 連線
於
app/config/config.php新增快取資訊。預設 Redis 於127.0.0.1、6379 埠：phpreturn new \Phalcon\Config([ // ... 其他設定 ... 'cache' => [ 'adapter' => 'Redis', 'host' => '127.0.0.1', 'port' => 6379, 'index' => 0, // 預設資料庫編號 0 'persistent' => false, // 是否使用長連線 'auth' => null, // 若有設定密碼請填寫 ], // ... 其他設定 ... ]);1
2
3
4
5
6
7
8
9
10
11
12新增示範路由
編輯
app/config/routes.php，新增 Redis 快取展示路由：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', ]); // 新增 Redis 快取展示路由 $router->add( '/redis', [ 'controller' => 'index', 'action' => 'redis', ] ); $router->handle($_SERVER['REQUEST_URI']); return $router;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控制器使用 Redis 快取
編輯
app/controllers/IndexController.php，新增redisAction方法：php<?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; } }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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69備註：正式專案建議將快取設定放入服務容器，提升共用性。
體驗說明
前往
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!"，證明快取機制生效。
常見問題 (FAQ)
- Q: 網站顯示 404 Not Found？
- A: 請確定 ServBay 網站設定中的「網站根目錄」正確指向 Phalcon
public目錄（/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public）。另檢查 Web 伺服器（Caddy/Nginx）運作狀態與網域設定。
- A: 請確定 ServBay 網站設定中的「網站根目錄」正確指向 Phalcon
- Q: 提示找不到 Phalcon 模組（如 Class 'Phalcon\Mvc\Application' not found）？
- A: 代表 PHP 版本尚未啟用 Phalcon 延伸。請在 ServBay 勾選同版本的 Phalcon，並重啟 PHP。詳見如何啟用 ServBay 內建 Phalcon 模組。
- Q: 資料庫連線失敗？
- A: 再檢查
app/config/config.php的連線資訊（主機、用戶、密碼、資料庫）正確。确保 ServBay 資料庫服務運作中、權限與資料庫存在。
- A: 再檢查
總結
借助 ServBay，您可極速搭建 Phalcon 框架的本機高效能開發環境。本篇詳述自專案誕生、Web 伺服器配置到 MySQL 與 Redis 整合的完整流程。ServBay 整合多元軟體套件與圖型管理介面，大幅簡化在地開發環境維運，讓您能專注於 Phalcon 應用開發。期望本教學能幫助您無縫起步，體驗 ServBay 與 Phalcon 帶來的專業開發利器！