在 ServBay 本機開發環境中建立和運行 FuelPHP 專案

什麼是 FuelPHP？

FuelPHP 是一套靈活且模組化的 PHP 框架，專為打造現代 Web 應用程式設計。它採用階層式模型-視圖-控制器（HMVC - Hierarchical Model-View-Controller）架構，提供豐富的功能與工具，能協助開發者高效構建高品質的 Web 應用程式。FuelPHP 以優異的靈活性、高效能和易擴充性，成為許多 PHP 開發者的首選框架。

FuelPHP 的主要特點與優勢

HMVC 架構：支援分層的 MVC 設計模式，有助於程式碼組織、重用及模組化開發，特別適合大型或複雜專案。
高效能：FuelPHP 在設計時著重效能優化，以高速和資源運用效率聞名，能夠有效處理高併發請求。
易於擴充：框架具備強大擴充機制，開發者可輕鬆整合第三方程式庫或自訂功能，以滿足特定專案需求。
安全性：內建多重安全功能，包括自動輸入驗證、輸出過濾（防止 XSS）、CSRF 防護、SQL 注入預防等，協助開發更安全的應用程式。
強大社群支援：FuelPHP 擁有活躍的開發者社群，可取得即時協助與豐富第三方資源。

借助上述特點，FuelPHP 能協助開發者快速打造高效能、安全且易於維護的 Web 應用，適用於各種規模，無論是小型專案還是大型企業級應用。

使用 ServBay 架設 FuelPHP 開發環境

ServBay 是專為開發者打造的本機 Web 開發環境，預載 PHP、Caddy/Nginx/Apache、MySQL/PostgreSQL/MongoDB、Redis 等多項開發服務與工具。透過 ServBay，您可以快速為 FuelPHP 專案搭建所需的運行環境，無需手動安裝與設定各類依賴。

本指南將詳細介紹如何利用 ServBay 提供的 PHP 執行環境、Web 伺服器（Caddy）、以及各項資料庫與快取服務來建立並運行 FuelPHP 專案。我們將運用 ServBay 的網站功能來設定 Web 伺服器，並透過簡單步驟實現專案的快速存取與測試。

前置條件

開始之前，請確保您已滿足下列條件：

您已經在 macOS 上正確安裝並運行 ServBay。
ServBay 的 PHP 環境已啟用（預設為啟用）。
ServBay 中您計劃使用的資料庫服務（如 MySQL）及快取服務（如 Redis、Memcached）已啟動並正常運行。
ServBay 已內建 Composer，無需額外安裝。

建立 FuelPHP 專案

建議的專案存放路徑

ServBay 建議開發者將網站專案統一存放於 /Applications/ServBay/www 目錄，便於 ServBay 管理與設定。本指南亦以該路徑為範例。

切換到網站根目錄
開啟終端機，切換至 ServBay 建議的網站專案根目錄：
bash
```
cd /Applications/ServBay/www
```
1
建立專案目錄
為您的 FuelPHP 專案建立一個新目錄，並切換進入：
bash
```
mkdir servbay-fuelphp-app
cd servbay-fuelphp-app
```
1
2
使用 Composer 建立 FuelPHP 專案
在專案目錄下，使用 Composer 下載並初始化 FuelPHP 框架。. 代表直接在當前目錄建立專案：
bash
```
composer create-project fuel/fuel .
```
1
Composer 會自動將 FuelPHP 框架及所需依賴下載至 servbay-fuelphp-app 目錄。

設定網頁伺服器（利用 ServBay 網站功能）

為了透過瀏覽器存取您的 FuelPHP 專案，請透過 ServBay 的網站功能設定對應的虛擬主機。

打開 ServBay 主介面。
點選側邊欄網站項目。
點擊右上角的 新增網站 按鈕。
在彈出的設定視窗中填寫以下資訊：
- 名稱：設定一個易於識別的網站名稱，例如 My First FuelPHP Dev Site。
- 網域名稱：設定本機開發用網域，如 servbay-fuelphp-test.local。ServBay 會自動將此網域解析指向本機。
- 網站類型：選擇 PHP。
- PHP 版本：選擇您欲使用的 PHP 版本，如 8.3。
- 網站根目錄：指定 FuelPHP 專案入口目錄。FuelPHP 公共入口為 public/index.php，因此網站根目錄應設為專案的 public 子目錄：/Applications/ServBay/www/servbay-fuelphp-app/public。
點擊新增儲存設定。

ServBay 會自動更新 Caddy 配置並重載服務，讓新網域立即生效。

詳細網站新增步驟可參考 ServBay 文件說明：新增第一個網站。

設定 FuelPHP 專案服務連線

FuelPHP 專案通常需要自行設定資料庫、快取等多種服務連線資訊。

資料庫設定

FuelPHP 的資料庫設定檔位於 fuel/app/config/development/db.php。請編輯該檔案填入您的資料庫連線資訊。假設您使用 ServBay 預設的 MySQL 服務：

php

<?php
/**
 * 開發環境下的資料庫設定，將會與全域設定合併。
 */
return [
    'default' => [
        'connection' => [
            'dsn'      => 'mysql:host=localhost;dbname=fuel_dev', // 請確保已建立 fuel_dev 資料庫
            'username' => 'root', // ServBay MySQL 預設使用者
            'password' => 'root', // ServBay MySQL 預設密碼（僅供本機開發用！）
        ],
        'identifier' => '`', // MySQL 需使用反引號作為識別符號
    ],
];

注意：

請先在 ServBay 的資料庫管理工具（如 phpMyAdmin 或 Adminer）中手動建立名為 fuel_dev 的資料庫。ServBay MySQL 預設使用者 root 密碼為 root，僅建議用於本機開發。
'identifier' => ''` 對於 MySQL 是必要設定，以確保表名和欄位名稱正確引用。

快取設定（Memcached 與 Redis）

FuelPHP 支援多種快取驅動。您可在 fuel/app/config/cache.php 設定快取驅動與連線資訊，並確保已啟動 ServBay 的 Memcached 與/或 Redis 服務。

Memcached 設定（fuel/app/config/cache.php）：

若要將 Memcached 設為預設快取：

php

<?php
return [
    'driver' => 'memcached', // 設定預設驅動為 memcached
    'memcached' => [
        'cache_id' => 'fuel', // 快取 ID
        'servers' => [
             'default' => [
                'host'   => '127.0.0.1', // Memcached 預設監聽位址
                'port'   => 11211,      // Memcached 預設埠號
                'weight' => 100,
            ],
        ],
        'compression' => false, // 是否啟用壓縮
    ],
    // ... 其他快取驅動設定
];

ServBay 所提供 PHP 通常已預載 Memcached 擴充套件。

Redis 設定（fuel/app/config/redis.php）：

若欲使用 Redis，可在獨立的 redis.php 設定連線資訊：

php

<?php
return [
    'default' => [
        'hostname' => '127.0.0.1', // Redis 預設監聽位址
        'port'     => 6379,      // Redis 預設埠號
        'database' => 0,         // Redis 資料庫編號
    ],
    // 可以設定多組 Redis 連線
];

ServBay 提供的 PHP 亦預載 Redis 擴充套件。

資料庫與快取服務範例

為展示 FuelPHP 與資料庫、快取服務的互動方式，以下提供些簡單範例。

建立資料表（使用 FuelPHP Migrations）

FuelPHP 提供 Oil 工具來管理資料庫遷移（Migrations），讓您能對資料庫結構進行版本控管。

建立遷移檔案
在專案根目錄（servbay-fuelphp-app）下，利用 Oil 工具建立新的遷移檔以定義 users 資料表結構：
bash
```
php oil generate migration create_users_table
```
1
這會在 fuel/app/migrations 目錄生成一個帶有時間戳記的新檔案。

編輯遷移檔案

開啟新產生的檔案（fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php），於 up() 方法定義表格結構，於 down() 方法撰寫回滾邏輯：

php

<?php
namespace Fuel\Migrations;

use Fuel\Core\DBUtil;

class Create_users_table
{
    public function up()
    {
        // 建立 users 資料表
        DBUtil::create_table('users', [
            'id'          => ['type' => 'int', 'constraint' => 11, 'auto_increment' => true],
            'name'        => ['type' => 'varchar', 'constraint' => 100],
            'email'       => ['type' => 'varchar', 'constraint' => 100, 'unique' => true],
        ], ['id'], true, 'InnoDB', 'utf8mb4_unicode_ci'); // 設定主鍵、開啟索引、指定引擎與字元集
    }

    public function down()
    {
        // 回滾：刪除 users 資料表
        DBUtil::drop_table('users');
    }
}

執行遷移
在專案根目錄下，執行資料庫遷移，建立資料表：
bash
```
php oil refine migrate
```
1
如一切順利，users 資料表會建立於 fuel_dev 資料庫中。

新增範例控制器程式碼

編輯 fuel/app/classes/controller/welcome.php，新增演示資料庫及快取操作方法：

php

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // 載入 DB facade
use Fuel\Core\Redis; // 載入 Redis facade

class Controller_Welcome extends Controller
{
    // 預設首頁 Action
    public function action_index()
    {
        return Response::forge('Hello ServBay!');
    }

    // Memcached 範例 Action
    public function action_memcached()
    {
        // 嘗試從快取取得資料
        $value = Cache::get('servbay_memcached_key');

        if ($value === false) {
            // 若快取沒有，則寫入資料
            $value = 'Hello Memcached from ServBay!';
            Cache::set('servbay_memcached_key', $value, 60); // 快取 60 秒
            $value .= ' (from cache)';
        } else {
            $value .= ' (cached)';
        }

        return Response::forge($value);
    }

    // Redis 範例 Action
    public function action_redis()
    {
        // 取得 Redis 實例（採預設連線）
        $redis = \Redis_Db::instance(); // FuelPHP 1.x 使用 Redis_Db::instance()
        // 若有多連線可用 \Redis_Db::instance('connection_name')

        // 寫入資料至 Redis
        $redis->set('servbay_redis_key', 'Hello Redis from ServBay!');

        // 從 Redis 取得資料
        $value = $redis->get('servbay_redis_key');

        return Response::forge($value);
    }

    // MySQL 寫入範例 Action
    public function action_mysql_add()
    {
        try {
            // 插入一筆記錄至 users 資料表
            $result = DB::insert('users')->set([
                'name' => 'ServBay Demo User ' . time(), // 加入時間戳確保唯一
                'email' => 'demo_user_' . time() . '@servbay.test',
            ])->execute(); // execute() 會回傳新插入的 ID 陣列

            return Response::forge('User added with ID: ' . $result[0]);
        } catch (\Database_Exception $e) {
            // 捕捉資料庫例外，例如 email 重複
            return Response::forge('Error adding user: ' . $e->getMessage(), 500);
        }
    }

    // MySQL 讀取範例 Action
    public function action_mysql()
    {
        // 查詢 users 資料表所有紀錄
        $users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();

        // 回傳 JSON 格式的用戶清單
        return Response::forge(json_encode($users, JSON_PRETTY_PRINT));
    }
}

注意：

此範例引入了 DB 與 Redis facades（use Fuel\Core\DB;、use Fuel\Core\Redis;）方便直接調用。
Memcached 與 Redis 的 key 名稱加上 servbay_ 前綴以避免名稱衝突。
MySQL 寫入範例中會附加時間戳，並做簡易錯誤管理，彙整出真實測試文案。
在 FuelPHP 1.x 版可用 \Redis_Db::instance() 取得 Redis 實體。

設定路由

為了用網址直接存取新增的控制器 Action 請於 fuel/app/config/routes.php 配置對應路由。FuelPHP 預設已設定 Controller_Welcome 路由，但對於 memcached、redis、mysql_add、mysql 需明確設定。

請在設定檔新增或修改返回陣列如下：

php

<?php
return array(
    '_root_'  => 'welcome/index',  // 預設路由指向 welcome 控制器 index Action
    '_404_'   => 'welcome/404',    // 404 錯誤頁路由

    // 新增範例 Action 對應路由
    'memcached'   => 'welcome/memcached',
    'redis'       => 'welcome/redis',
    'mysql_add'   => 'welcome/mysql_add',
    'mysql'       => 'welcome/mysql',

    // ... 其他路由設定
);

存取與測試您的網站

您現在可開啟瀏覽器透過先前於 ServBay 設定的網域（如 https://servbay-fuelphp-test.local）來測試 FuelPHP 專案及服務串接。

首頁測試： https://servbay-fuelphp-test.local
- 預期出現：Hello ServBay!
Memcached 測試： https://servbay-fuelphp-test.local/memcached
- 第一次存取可能顯示：Hello Memcached from ServBay! (from cache)（快取服務正常時）
- 再訪問則可能顯示：Hello Memcached from ServBay! (cached)（快取服務仍在有效期時）
Redis 測試： https://servbay-fuelphp-test.local/redis
- 預期出現：Hello Redis from ServBay!（Redis 服務正常時）
加入 MySQL 用戶： https://servbay-fuelphp-test.local/mysql_add
- 預期出現：User added with ID: [新插入的ID]（MySQL 服務正常且已建資料庫與表時）
查詢 MySQL 用戶列表： https://servbay-fuelphp-test.local/mysql
- 預期出現：一個 JSON 陣列，列出 users 資料表所有紀錄（MySQL 服務正常且表非空時）

關於 HTTPS： ServBay 預設為本機網站安裝 SSL 憑證，並以 ServBay User CA 或 ServBay Public CA 作為信任單位。如果瀏覽器出現憑證不受信任提示，請於系統信任 ServBay 的 CA 憑證。

注意事項

請確認於 ServBay 主介面 PHP 版本、Caddy（或 Nginx/Apache）、MySQL（若需資料庫）、Redis（如用 Redis）、Memcached（如用 Memcached）等服務全為執行中狀態。
請在 ServBay 的資料庫管理工具中，手動建立 fuel_dev 資料庫（或於 db.php 設定已存在的其他資料庫）。FuelPHP 的遷移工具 oil refine migrate 僅會在指定資料庫中建立資料表，不會自動新建資料庫。
FuelPHP 的 web 公開入口為 public/index.php，因此在 ServBay 網站設定時，網站根目錄必須指向專案之 public 子目錄。

總結

透過 ServBay，您可在 macOS 上輕鬆為 FuelPHP 專案搭建完整的本機開發環境。本文詳細介紹了專案建立、ServBay 網站功能設定、資料庫與快取服務串接，以及驗證功能的範例程式碼。ServBay 集成豐富服務、簡化設定流程，將大幅提升您的開發效率。

希望本指南能協助您順利於 ServBay 展開 FuelPHP 的開發之旅！

在 ServBay 本機開發環境中建立和運行 FuelPHP 專案 ​

什麼是 FuelPHP？ ​

FuelPHP 的主要特點與優勢 ​

使用 ServBay 架設 FuelPHP 開發環境 ​

前置條件 ​

建立 FuelPHP 專案 ​

設定網頁伺服器（利用 ServBay 網站功能） ​

設定 FuelPHP 專案服務連線 ​

資料庫設定 ​

快取設定（Memcached 與 Redis） ​

資料庫與快取服務範例 ​

建立資料表（使用 FuelPHP Migrations） ​

新增範例控制器程式碼 ​

設定路由 ​

存取與測試您的網站 ​

注意事項 ​

總結 ​