使用 ServBay 建立並運行 CakePHP 專案
ServBay 是專為 macOS 打造的本機 Web 開發環境，整合了 PHP、Node.js、Python、Go、Java 等多種語言環境，以及 MySQL、PostgreSQL、MongoDB、Redis 等資料庫服務，並支援 Caddy 或 Nginx Web 伺服器。ServBay 提供方便高效的開發平台，讓開發者可輕鬆搭建與管理本地專案。
本文將帶您瞭解如何在 ServBay 環境中建立、設定並運行 CakePHP 專案。CakePHP 是一套流行的 PHP Web 框架，遵循 MVC（模型-檢視-控制器）架構，具備快速開發、高效 ORM 與內建安全特性。結合 ServBay 的便捷，您能迅速啟動 CakePHP 的開發工作。
什麼是 CakePHP？
CakePHP 是一個開源的 PHP Web 應用框架，提供強大且結構化的基礎結構，使您能快速且有組織地開發應用程式，而不犧牲靈活性。它遵循「約定優於設定」原則，簡化許多常見開發任務。
CakePHP 的主要特點與優勢
- 基於 MVC 架構： 代碼組織明確，易於維護與擴展。
- 快速開發： 提供命令列工具（Bake），能自動產生代碼，加快開發速度。
- 強大 ORM (物件關聯對應)： 簡化資料庫操作，支援多種資料庫系統。
- 內建安全性： 包含 CSRF 防護、SQL 注入防禦、輸入驗證等機制。
- 靈活的樣板引擎： 支援多種檢視層技術。
- 活躍社群與豐富外掛： 遇到問題容易獲得協助，功能可彈性擴充。
- 完整文件： 提供詳盡指南與 API 文件。
CakePHP 適合打造各種規模的 Web 應用，從簡單 API 到複雜企業系統皆適用。
使用 ServBay 建立 CakePHP 開發環境
ServBay 為 CakePHP 開發提供高度整合的便捷環境，包括：
- 已預裝的 PHP 直譯器與常用擴充套件
- 已預裝的 Composer 套件管理器
- 容易設定的 Web 伺服器（Caddy/Nginx）
- 整合型資料庫服務（MySQL、PostgreSQL、Redis 等）
使用 ServBay，您可省去手動安裝設定各元件的繁雜步驟。
前置作業
在開始前，請確認下列準備已完成：
- 安裝 ServBay： 請確保您已於 macOS 上下載並成功安裝 ServBay。
- 啟動 ServBay 服務： 開啟 ServBay 應用，並確認所需套件（如 PHP、欲使用的資料庫如 MySQL 或 PostgreSQL，以及快取服務如 Redis 或 Memcached）皆已啟動。您可在 ServBay 控制台的「套件」頁籤管理這些服務。
- 熟悉 ServBay 基礎操作： 了解如何在 ServBay 新增及設定網站。若不熟悉，建議先參閱 ServBay 基本用法指南。
建立 CakePHP 專案
ServBay 建議您將 Web 專案統一存放於 /Applications/ServBay/www 資料夾內，以利 ServBay 自動辨識並管理您的網站。
開啟終端機
啟動 macOS 內建的終端機應用程式。
切換至 ServBay 網站根目錄
切換至 ServBay 建議的網站儲存位置：
bashcd /Applications/ServBay/www1建立專案資料夾
建立 CakePHP 專案的子資料夾。本例以
servbay-cakephp-app為專案名稱：bashmkdir servbay-cakephp-app cd servbay-cakephp-app1
2利用 Composer 建立 CakePHP 專案
ServBay 已預裝 Composer。於資料夾中執行下列指令建立 CakePHP 專案骨架：
bashcomposer create-project --prefer-dist cakephp/app .1此指令將下載最新穩定版 CakePHP 及其相依套件，並安裝至目前目錄 (
.)。安裝 ORM 驅動（如需使用 PostgreSQL）
若您打算使用 PostgreSQL 資料庫，需額外安裝其 ORM 驅動套件：
bashcomposer require cakephp/orm-pgsql1若使用 MySQL，CakePHP 核心已內建驅動，無需額外安裝。
初始化設定
專案建立後，需完成基本設定，特別是資料庫連線資訊。
設定環境變數與資料庫連線
CakePHP 的本地設定主要集中於
config/app_local.php。請編輯本檔案，找到Datasources區塊，設定資料庫連線資料。ServBay 資料庫預設帳號為root，密碼為password。例如，設定 MySQL 連線：
php// config/app_local.php 'Datasources' => [ 'default' => [ 'className' => \Cake\Database\Connection::class, 'driver' => \Cake\Database\Driver\Mysql::class, // 或 \Cake\Database\Driver\Postgres::class 用於 PostgreSQL 'persistent' => false, 'host' => '127.0.0.1', // 資料庫伺服器位置，ServBay 預設為本機 //'port' => '3306', // MySQL 預設埠 3306，PostgreSQL 為 5432 'username' => 'root', // ServBay 預設帳號 'password' => 'password', // ServBay 預設密碼 'database' => 'servbay_cakephp_app', // 您日後建立的資料庫名稱 'encoding' => 'utf8mb4', 'timezone' => 'UTC', 'flags' => [], 'cacheMetadata' => true, 'log' => false, /** * 若您使用如 "user" 為資料表名稱，請設為 true。 * 若非保留字，則可設為 false。若不確定請使用 true。 */ 'quoteIdentifiers' => false, /** * 目前限制包括： * - 多數驅動不支援透過 PDO options 設定 isolation level。 * 使用時會出現錯誤。 * - 並非所有驅動都支援 PDO options 設定字集。 * 使用時會出現錯誤。 * - CakePHP 套件驅動（如 Postgres）不支援 PDO options。 * 對於 Postgres 僅需設定 encoding。 */ 'options' => [], //'url' => env('DATABASE_URL', null), // 若您使用 DATABASE_URL 環境變數，可啟用本行 ], ],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請依您選用的資料庫（MySQL 或 PostgreSQL）調整
driver與port，並確認database名稱吻合您日後所創建的資料庫。
設定 Web 伺服器（於 ServBay 中建立網站）
為了可透過瀏覽器存取 CakePHP 專案，您須於 ServBay 建立網站並指向專案資料夾。
開啟 ServBay 控制台
點選 ServBay 圖示以開啟控制台。
切換至「網站」頁籤
於控制台點選左側「網站」選項（舊版名稱為「主機」）。
新增網站
點選下方
+按鈕新增網站，並填寫下列資訊：- 名稱 (Name): 取一個方便辨識的網站名稱，例如
My CakePHP Dev Site。 - 網域 (Domain): 設定一個本機開發網域，如
servbay-cakephp-test.local。ServBay 會自動指向本機。 - 網站類型 (Site Type): 選擇
PHP。 - PHP 版本 (PHP Version): 選擇符合 CakePHP 版本的 PHP 版本（如 CakePHP 4+ 需 PHP 7.4+，CakePHP 5+ 需 PHP 8.1+），例如選用
8.3。 - 網站根目錄 (Document Root): 重要！ CakePHP Web 伺服器根目錄非專案主目錄，而是
webroot。請設為/Applications/ServBay/www/servbay-cakephp-app/webroot（將servbay-cakephp-app替換為實際資料夾名稱）。
- 名稱 (Name): 取一個方便辨識的網站名稱，例如
儲存並套用設定
完成後點選右下「保存」。ServBay 會提示您套用變更，請點選確認。ServBay 會自動設定 Web 伺服器（Caddy/Nginx）處理
servbay-cakephp-test.local，並指向專案webroot目錄。
更詳細網站新增流程，請參考 ServBay 文件的 新增第一個網站。
驗證基本安裝
現在，您應可於瀏覽器開啟設定的網站。
打開瀏覽器，前往您設定的網域，例如 https://servbay-cakephp-test.local。
若一切無誤，您將看到 CakePHP 的歡迎頁。這表示 PHP、Web 伺服器與 ServBay 網站設定皆已運作正常。
整合資料庫與快取服務
CakePHP 提供強大的 ORM 與快取抽象層，讓您能輕鬆整合 ServBay 所提供的資料庫與快取服務。
關聯式資料庫範例（MySQL / PostgreSQL）
本例會示範如何透過 CakePHP ORM 連線至 ServBay 中的 MySQL 或 PostgreSQL，建立 users 資料表並進行新增/查詢等操作。
於 ServBay 建立資料庫
進行資料庫遷移前，您須先於 ServBay 的資料庫伺服器建立新資料庫。可用 ServBay 內建之 phpMyAdmin（MySQL/MariaDB）、pgAdmin（PostgreSQL），或第三方工具（Navicat/DBeaver 等）連到 127.0.0.1，帳號
root，密碼password，建立名為servbay_cakephp_app的新資料庫。建立 ORM Model 檔案
CakePHP ORM 需有一個 Model 對應資料表。可建立
UsersTable.php代表users。儲存以下程式至
src/Model/Table/UsersTable.php：php<?php namespace App\Model\Table; use Cake\ORM\Table; use Cake\Validation\Validator; // 若需驗證規則 class UsersTable extends Table { /** * Initialize method * * @param array $config The configuration for the Table. * @return void */ public function initialize(array $config): void { parent::initialize($config); $this->setTable('users'); // 明確指定表名稱 $this->setDisplayField('name'); // 預設關聯顯示欄位 $this->setPrimaryKey('id'); // 設定主鍵 // 若需自動維護時間戳，啟用下行 // $this->addBehavior('Timestamp'); } /** * Default validation rules. * * @param \Cake\Validation\Validator $validator Validator instance. * @return \Cake\Validation\Validator */ public function validationDefault(Validator $validator): Validator { $validator ->scalar('name') ->maxLength('name', 255) ->requirePresence('name', 'create') ->notEmptyString('name'); $validator ->email('email') ->requirePresence('email', 'create') ->notEmptyString('email') ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // Email 必須唯一 return $validator; } }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使用 Bake 工具建立遷移檔
CakePHP 建議以遷移管理資料表結構。在專案根目錄執行：
bashbin/cake bake migration CreateUsers name:string email:string:unique1上述指令會建立含有
users表結構的遷移檔，內含name（string）與email（唯一的 string）。執行資料庫遷移
執行下列命令將
users表寫入資料庫：bashbin/cake migrations migrate1成功後，資料庫中會出現新建立的
users表。設定資料庫連線（如之前未設定）
確認
config/app_local.php內Datasources.default設定正確。MySQL 範例:
php'Datasources' => [ 'default' => [ 'className' => \Cake\Database\Connection::class, 'driver' => \Cake\Database\Driver\Mysql::class, 'host' => '127.0.0.1', 'username' => 'root', 'password' => 'password', 'database' => 'servbay_cakephp_app', // ... 其他設定 ], ],1
2
3
4
5
6
7
8
9
10
11PostgreSQL 範例:
php'Datasources' => [ 'default' => [ 'className' => \Cake\Database\Connection::class, 'driver' => \Cake\Database\Driver\Postgres::class, 'host' => '127.0.0.1', // 'port' => '5432', // 預設埠 'username' => 'root', // ServBay 預設帳號 'password' => 'password', // ServBay 預設密碼 'database' => 'servbay_cakephp_app', // ... 其他設定 ], ],1
2
3
4
5
6
7
8
9
10
11
12
新增範例路由與控制器方法
編輯
config/routes.php，加入下列路由以操作資料庫：php// config/routes.php use Cake\Routing\RouteBuilder; use Cake\Routing\Router; use Cake\Routing\Route\DashedRoute; Router::defaultRouteClass(DashedRoute::class); Router::scope('/', function (RouteBuilder $routes) { // ... 其他路由 $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']); // 資料庫示例路由 $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']); $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']); // ... 其他路由 $routes->fallbacks(DashedRoute::class); });1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18編輯
src/Controller/PagesController.php，增添資料庫操作方法：php<?php namespace App\Controller; use Cake\Http\Response; use Cake\ORM\TableRegistry; use Cake\Datasource\Exception\RecordNotFoundException; // 找不到資料時的例外處理 class PagesController extends AppController { /** * Displays a view * * @param array ...$path Path segments. * @return \Cake\Http\Response|null */ public function display(...$path): ?Response { // ... 預設 display 方法 return new Response(['body' => 'Hello ServBay! This is the default page.']); } /** * 資料庫範例：新增使用者 */ public function dbAddUser(): Response { $usersTable = TableRegistry::getTableLocator()->get('Users'); // 取得 Users Table // 建立新使用者 $user = $usersTable->newEntity([ 'name' => 'ServBay Demo User', 'email' => '[email protected]' // 使用 ServBay 示範信箱 ]); // 嘗試寫入資料庫 if ($usersTable->save($user)) { return new Response(['body' => 'User added successfully! User ID: ' . $user->id]); } else { // 若寫入失敗，如驗證錯誤 $errors = $user->getErrors(); return new Response(['body' => 'Failed to add user. Errors: ' . json_encode($errors)]); } } /** * 資料庫範例：列出所有使用者 */ public function dbListUsers(): Response { $usersTable = TableRegistry::getTableLocator()->get('Users'); // 取得 Users Table // 取得所有使用者 $users = $usersTable->find()->all(); // 輸出 JSON return new Response(['body' => json_encode($users->toArray())]); // toArray() 輸出為陣列 } }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測試資料庫範例
於瀏覽器輸入：
https://servbay-cakephp-test.local/db-add-user新增使用者，應會看到成功訊息。https://servbay-cakephp-test.local/db-list-users查看所有使用者列表（應已包含剛新增者）。
依上述步驟，您已成功將 CakePHP 專案連結至 ServBay 的關聯式資料庫，並執行基本 ORM 操作。
快取服務範例（Memcached / Redis）
CakePHP 提供統一快取 API，方便切換各種引擎，如 Memcached、Redis。ServBay 預設已安裝 PHP 之 Memcached、Redis 擴充，以及對應服務。
請先於 ServBay 控制台「套件」確保已啟動 Memcached/Redis 服務。
設定快取連線
編輯
config/app_local.php內Cache區塊，設定快取連線。Memcached 範例:
php// config/app_local.php 'Cache' => [ 'default' => [ 'className' => \Cake\Cache\Engine\MemcachedEngine::class, 'servers' => ['127.0.0.1:11211'], // ServBay 預設 Memcached 位址 'prefix' => 'servbay_cakephp_', // 快取 key 前綴 ], // ... 其他快取設定 ],1
2
3
4
5
6
7
8
9Redis 範例:
php// config/app_local.php 'Cache' => [ 'default' => [ 'className' => \Cake\Cache\Engine\RedisEngine::class, 'host' => '127.0.0.1', // ServBay 預設 Redis 位址 'port' => 6379, // ServBay 預設 Port 'password' => null, // 若 Redis 有設定密碼，填入此 'database' => 0, // Redis DB 編號 'prefix' => 'servbay_cakephp_', // 快取 key 前綴 ], // ... 其他快取設定 ],1
2
3
4
5
6
7
8
9
10
11
12
請依所使用的快取服務調整設定。
新增範例路由與控制器方法
編輯
config/routes.php，加上下列快取示例路由：php// config/routes.php // ... 其他路由 $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']); $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']); // ... 其他路由1
2
3
4
5編輯
src/Controller/PagesController.php，增加快取方法：php<?php namespace App\Controller; use Cake\Http\Response; use Cake\Cache\Cache; // 匯入 Cache 類別 // ... 其他 use class PagesController extends AppController { // ... 其他 display, dbAddUser, dbListUsers /** * 快取範例：Memcached */ public function cacheMemcached(): Response { // 確認 app_local.php 'default' 快取已設為 MemcachedEngine $cacheKey = 'servbay_memcached_test_key'; $cachedData = Cache::read($cacheKey); $responseBody = ''; if ($cachedData === false) { // 未命中快取 $responseBody = 'Cache miss! Writing "Hello Memcached!" to cache.'; $dataToCache = 'Hello Memcached!'; Cache::write($cacheKey, $dataToCache, 'default'); } else { // 命中快取 $responseBody = 'Cache hit! Data from cache: ' . $cachedData; } return new Response(['body' => $responseBody]); } /** * 快取範例：Redis */ public function cacheRedis(): Response { // 確認 app_local.php 'default' 快取已設為 RedisEngine $cacheKey = 'servbay_redis_test_key'; $cachedData = Cache::read($cacheKey); $responseBody = ''; if ($cachedData === false) { // 未命中快取 $responseBody = 'Cache miss! Writing "Hello Redis!" to cache.'; $dataToCache = 'Hello Redis!'; Cache::write($cacheKey, $dataToCache, 'default'); } else { // 命中快取 $responseBody = 'Cache hit! Data from cache: ' . $cachedData; } return new Response(['body' => $responseBody]); } }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測試快取範例
於瀏覽器試訪：
- 若設定 Memcached，前往
https://servbay-cakephp-test.local/cache-memcached。首次為 “Cache miss”，刷新則為 “Cache hit”。 - 若設定 Redis，前往
https://servbay-cakephp-test.local/cache-redis。首次為 “Cache miss”，刷新則為 “Cache hit”。
- 若設定 Memcached，前往
這表示，您的 CakePHP 專案已成功連接並使用 ServBay 快取服務。
注意事項
- 資料庫帳號密碼： ServBay 預設資料庫帳密（
root/password）僅用於本地開發，請於正式環境更換為安全組合。 - 網站根目錄： 務必讓 ServBay 網站「網站根目錄」指向 CakePHP 專案下
webroot資料夾，這是 CakePHP 官方建議。 - PHP 版本兼容性： 請確認您選用的 PHP 版本與使用 CakePHP 版本相容，詳細需求請參考官方文件。
- ServBay 埠號： 若 ServBay 預設埠號（如 80、443）被占用，請於 ServBay 設定中更改，並適當調整 hosts 或帶 Port 存取。
常見問題說明（FAQ）
- Q: 開啟
servbay-cakephp-test.local出現「找不到頁面」？- A: 請檢查 ServBay 網站「網站根目錄」是否正確設為
/Applications/ServBay/www/servbay-cakephp-app/webroot。 - 檢查 ServBay Web 伺服器（Caddy/Nginx）是否有啟動。
- 檢查系統 hosts 是否已將
servbay-cakephp-test.local指向127.0.0.1（ServBay 會自動處理，多數情況不需手動）。 - 檢查 CakePHP
.htaccess或 Web 伺服器設定是否正確（一般webroot/.htaccess預設已正確）。
- A: 請檢查 ServBay 網站「網站根目錄」是否正確設為
- Q: 資料庫連線失敗？
- A: 檢查 ServBay 對應資料庫服務（MySQL/PostgreSQL）是否運作中。
- 檢查
config/app_local.php相關資料庫設定（host、port、username、password、database）與 ServBay 服務相符。 - 確認資料庫伺服器已建立
servbay_cakephp_app資料庫。
- Q: Composer 指令（
bin/cake）無法執行？- A: 請確認終端機目錄於 CakePHP 專案根目錄（
/Applications/ServBay/www/servbay-cakephp-app）。 - 確認 ServBay PHP 與 Composer 套件有啟動。
- 檢查終端機能否正常呼叫
php指令（ServBay 通常已自動加至 PATH）。亦可使用 ServBay 內建終端機或手動調整 PATH。
- A: 請確認終端機目錄於 CakePHP 專案根目錄（
總結
透過 ServBay，您能高效率地在 macOS 上架設 CakePHP 專案本機開發環境。ServBay 已整合 PHP、Composer、Web 伺服器及資料庫服務，大幅簡化配置流程。本文詳細說明從專案建立、基礎設定、Web 伺服器設置，到關聯式資料庫與快取整合的全流程，協助您快速展開 CakePHP 開發。善用 ServBay 的便利，讓您專注於程式撰寫，而非環境佈署細節。