使用 ServBay 建立並運行 CakePHP 專案
ServBay 是一套支援 macOS 和 Windows 的本機網頁開發環境，整合了 PHP、Node.js、Python、Go、Java 等多種語言平台，以及 MySQL、PostgreSQL、MongoDB、Redis 等資料庫服務，並可搭配 Caddy 或 Nginx 網頁伺服器。透過它提供的高效且直覺化平台，讓開發者能輕鬆架設與管理本地專案。
本篇將帶您手把手在 ServBay 環境中建立、設定並運行 CakePHP 專案。CakePHP 是廣受歡迎的 PHP 網頁框架，依循 MVC（模型-視圖-控制器）模式，以快速開發、強大 ORM 及內建安全著稱。結合 ServBay 的便利性，您可以有效率地開始 CakePHP 的開發工作。
什麼是 CakePHP？
CakePHP 是一套開源的 PHP 網頁應用框架，提供一組基礎結構，協助開發者迅速且有架構地開發 Web 應用程式，同時保有彈性。它強調「約定優於設定」理念，使常見的開發任務變得更簡單。
CakePHP 主要特色與優勢
- 採用 MVC 架構： 清楚分離程式結構，易於維護與擴充。
- 快速開發： 提供指令工具（Bake），協助生成程式碼，提升開發效率。
- 強大的 ORM（物件關聯對映）： 簡化資料庫操作，支援多種資料庫系統。
- 內建安全防護： 具備 CSRF 防禦、SQL 注入防護、輸入驗證等功能。
- 彈性的模板引擎： 支援多元的視圖層技術。
- 活躍社群與豐富套件： 遇到問題易尋求協助，項目可擴充性高。
- 完整文件與 API： 提供詳細教學與技術參考。
CakePHP 可應用於各種規模的 Web 專案，從簡單 API 到大型企業系統皆宜。
使用 ServBay 建置 CakePHP 開發環境
ServBay 為 CakePHP 開發整合了以下便利條件：
- 預先安裝 PHP 執行環境及常用擴充。
- 預設安裝 Composer 套件管理工具。
- 網頁伺服器（Caddy/Nginx）設定簡單。
- 整合式資料庫服務（MySQL, PostgreSQL, Redis 等）。
利用 ServBay，您可省去繁複的環境安裝與細部設定。
前置準備條件
開始之前，請確認以下步驟都已完成：
- 安裝 ServBay： 請先於 macOS 完成 ServBay 的下載且安裝。
- 啟動 ServBay 服務： 開啟 ServBay 並確保必要的程式包（如 PHP、想用的資料庫例如 MySQL 或 PostgreSQL，以及快取服務如 Redis 或 Memcached）皆已啟動。可於 ServBay 控制台「軟體包」分頁管理這些服務。
- 熟悉基本操作： 理解如何在 ServBay 新增與設定網站。若不熟悉，建議先閱讀 ServBay 基本操作教學。
建立 CakePHP 專案
ServBay 建議將您的 Web 專案統一存放在 /Applications/ServBay/www 目錄，讓系統可自動辨識與管理。
打開終端機
開啟 macOS 終端機。
移動至 ServBay 網站根目錄
切換到 ServBay 建議的專案存放目錄：
bashcd /Applications/ServBay/www1建立專案資料夾
為 CakePHP 專案新增目錄。以下以
servbay-cakephp-app為範例：bashmkdir servbay-cakephp-app cd servbay-cakephp-app1
2利用 Composer 建立 CakePHP 專案
ServBay 已內建 Composer。請在專案目錄下執行：
bashcomposer create-project --prefer-dist cakephp/app .1此指令會下載 CakePHP 最新穩定版及所有依賴，安裝至目前目錄（
.）。安裝 ORM 驅動（如果使用 PostgreSQL）
若要使用 PostgreSQL，要額外安裝應用程式驅動：
bashcomposer require cakephp/orm-pgsql1若使用 MySQL 通常無需額外安裝，已預設於主程式。
初始化設定
專案建立後，需進行基本設定，尤以資料庫連線相關資訊為主。
設定環境變數與資料庫連線
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, // PostgreSQL 請改成 \Cake\Database\Driver\Postgres::class 'persistent' => false, 'host' => '127.0.0.1', // 資料庫伺服器，ServBay 預設為本機 //'port' => '3306', // MySQL 預設埠號 3306，PostgreSQL 為 5432 'username' => 'root', 'password' => 'password', 'database' => 'servbay_cakephp_app', // 設定即將建立的資料庫名稱 'encoding' => 'utf8mb4', 'timezone' => 'UTC', 'flags' => [], 'cacheMetadata' => true, 'log' => false, /** * 如果準備將 "user" 作為資料表名稱，請設為 true; * 若表名如 "cake"，可設為 false。 * 若不確定，建議使用 true。 */ 'quoteIdentifiers' => false, /** * 目前限制如下： * - 多數驅動不支援透過 PDO 選項設置隔離等級，使用時會出錯。 * - 部分驅動不支援透過 PDO 設定字元集，使用會出錯。 * - 包裝版驅動如 CakePHP 的 Postgres，不支援 PDO 選項。Postgres 設定只需編碼即可。 */ '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請依據使用資料庫型別調整
driver與port並確認資料庫名稱正確。
設定網頁伺服器（在 ServBay 建立網站）
為能透過瀏覽器存取 CakePHP 專案，需於 ServBay 配置一個指向專案資料夾的網站。
開啟 ServBay 控制台
點擊 ServBay 圖示，打開控制面板。
進入「網站」分頁
於左側選單選擇「網站」（舊版本為「主機」）。
新增網站
點擊底部
+按鈕，新增網站並填寫以下資料：- 名稱 (Name)： 輸入易辨識命名，例如
My CakePHP Dev Site。 - 網域 (Domain)： 建議本地開發域名如
servbay-cakephp-test.local。ServBay 會自動指向本機。 - 網站類型 (Site Type)： 選擇
PHP。 - PHP 版本 (PHP Version)： CakePHP 4 以上通常建議 PHP 7.4 起，CakePHP 5 以上則建議 PHP 8.1 起。範例如
8.3。 - 網站根目錄 (Document Root)： 重要！ CakePHP 專案的網站根目錄是
webroot目錄而非主目錄，請設定為/Applications/ServBay/www/servbay-cakephp-app/webroot（將servbay-cakephp-app改為您的實際目錄）。
- 名稱 (Name)： 輸入易辨識命名，例如
儲存並套用設定
填寫完畢後，點選右下角「儲存」按鈕。ServBay 會提醒套用更改，按下確認。系統將自動設定 Caddy 或 Nginx，將
servbay-cakephp-test.local網域指向專案webroot。
詳細步驟可參考 ServBay 官方文件：新增第一個網站。
驗證基本設定
此時，您已可透過瀏覽器存取新建立的網站。
打開瀏覽器，輸入在 ServBay 設定的網域（例如 https://servbay-cakephp-test.local）。
若一切正常，將看到 CakePHP 預設歡迎頁，代表 PHP 環境、網頁伺服器和網站設定皆運作順利。
整合資料庫與快取服務
CakePHP 具備強大 ORM 與快取層，能簡易整合 ServBay 提供之資料庫與快取服務。
關聯式資料庫示範（MySQL / PostgreSQL）
以下範例展示 CakePHP 連接 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'); } /** * 預設欄位驗證規則 * * @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 工具建立遷移檔
建議用資料庫遷移工具管理資料表結構。於專案根目錄（
/Applications/ServBay/www/servbay-cakephp-app）執行如下指令：bashbin/cake bake migration CreateUsers name:string email:string:unique1將會產生一個建立
users表的遷移檔，包含name（字串型）與唯一email欄位。執行資料庫遷移
運行遷移指令，將
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', 'password' => 'password', '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 { /** * 顯示頁面 * * @param array ...$path Path segments. * @return \Cake\Http\Response|null */ public function display(...$path): ?Response { // ... 預設顯示方法 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' => 'servbay-demo@servbay.test' // 品牌範例信箱 ]); // 嘗試存入資料庫 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 = $usersTable->find()->all(); // 輸出結果為 JSON return new Response(['body' => json_encode($users->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_', ], // ... 其他快取設定 ],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', 'port' => 6379, 'password' => null, // 若有設定密碼，請填入 'database' => 0, 'prefix' => 'servbay_cakephp_', ], // ... 其他快取設定 ],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測試快取範例
於瀏覽器：
- 若用 Memcached，進入
https://servbay-cakephp-test.local/cache-memcached，首訪顯示 "Cache miss"，刷新則為 "Cache hit"。 - 若用 Redis，進入
https://servbay-cakephp-test.local/cache-redis，同樣原理進行測試。
- 若用 Memcached，進入
這表示您已成功將 CakePHP 專案與 ServBay 快取服務串聯。
注意事項
- 資料庫密碼安全： ServBay 預設帳號密碼（
root/password）僅適用開發，正式環境請改用安全憑證。 - 網站根目錄設定： 請務必將 ServBay 的「網站根目錄」指到 CakePHP
webroot，非專案主目錄，為最佳實踐。 - PHP 版本相容： 選用與 CakePHP 版本相容的 PHP 版本，請參考 CakePHP 官方文件說明。
- ServBay 埠號占用： 若預設 HTTP（80/443）埠號已被其他程式占用，須於 ServBay 設定更改，並適時修改 hosts 檔或加上埠號存取。
常見問題解答（FAQ）
- Q: 訪問
servbay-cakephp-test.local顯示「找不到頁面」？- A: 請檢查 ServBay 的「網站根目錄」是否正確指到
/Applications/ServBay/www/servbay-cakephp-app/webroot。 - 檢查 Web 伺服器（Caddy/Nginx）有無運行。
- 檢查系統 hosts 檔是否將
servbay-cakephp-test.local指向127.0.0.1（ServBay 通常自動處理，但有時需人工檢查）。 - 檢查 CakePHP
.htaccess或伺服器設定是否正確（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 是否已加入 PATH，可用 ServBay 內建終端機或自行設定 PATH。
- A: 請確定終端機當前目錄為 CakePHP 專案根目錄（
總結
利用 ServBay，您可以有效率地為 CakePHP 專案打造本地開發環境。ServBay 內建 PHP、Composer、網頁伺服器及資料庫，極大簡化了繁瑣的系統設定流程。本教學詳細涵蓋專案建立、基本參數設定、伺服器配置至關聯式資料庫及快取整合，協助您快速展開 CakePHP 開發之路。善用 ServBay 的便利功能，讓您專注於撰寫程式，不必煩惱環境配套。
