建立並運行 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-app
1
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 update
1
Composer 會於專案目錄(
servbay-phalcon-app
)下建立vendor
目錄,執行檔路徑為vendor/bin/phalcon
。利用 DevTools 產生專案骨架
執行剛安裝的 DevTools 指令產生 Phalcon 專案基本檔案結構。預設會將專案程式碼放於子資料夾(例如同名的
servbay-phalcon-app
):bashvendor/bin/phalcon project servbay-phalcon-app
1此指令會於
/Applications/ServBay/www/servbay-phalcon-app
下產生/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app
子目錄,裡面包含完整 Phalcon 專案骨架。進入專案程式碼目錄
進入剛新建的程式碼目錄,所有後續操作皆於此目錄下進行:
bashcd servbay-phalcon-app
1您此時位置應為
/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 generate
1會在
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 run
1若遇連線錯誤,請再檢查
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 帶來的專業開發利器!