在 ServBay 本地開發環境中建立與運行 FuelPHP 專案

什麼是 FuelPHP？

FuelPHP 是一套具有高度彈性與模組化的 PHP 框架，專為構建現代化網頁應用程式而設計。它遵循層次化模型-視圖-控制器（HMVC, Hierarchical Model-View-Controller）設計模式，並提供許多實用功能與工具，協助開發者迅速且高效地建置高品質的網頁應用。FuelPHP 憑藉優異的彈性、高效能以及易於擴充的特色，成為 PHP 開發者的熱門選擇之一。

FuelPHP 的主要特色與優勢

HMVC 架構：支援階層式 MVC 設計，有助於程式碼組織、重複利用與模組化，特別適合大型或複雜專案。
高效能：FuelPHP 在設計上重視效能最佳化，執行速度快且資源運用效率高，能有效應對高併發請求。
易於擴充：框架內建擴充機制，開發者可輕鬆整合第三方套件或新增自訂功能，滿足多元專案需求。
安全性佳：內建多項安全防護，包括自動輸入驗證、輸出過濾（預防 XSS）、CSRF 防護、SQL 注入防範等，協助打造安全可靠的應用程式。
強大的社群支援：FuelPHP 擁有活躍的開發者社群，可取得即時協助及豐富的資源分享。

憑藉上述特性，FuelPHP 可協助開發者快速打造高效能、安全且易於維護的網頁應用，適用於小型至大型企業等各種規模的建置需求。

使用 ServBay 建立 FuelPHP 開發環境

ServBay 是專為開發者打造的本地網頁開發環境，預先整合 PHP、Caddy/Nginx/Apache、MySQL/PostgreSQL/MongoDB、Redis 等多種常用服務與工具。利用 ServBay，您能快速建立 FuelPHP 專案所需的執行環境，無需手動安裝和設定各項依賴。

本教學將一步步說明如何運用 ServBay 的 PHP 環境、網頁伺服器（Caddy）、資料庫與快取服務來建立並運作 FuelPHP 專案。我們將運用 ServBay 的網站功能設定虛擬主機，並透過簡單步驟完成專案的快速存取與測試。

前置條件

在開始之前，請先確保下列條件均已完成：

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

建立 FuelPHP 專案

建議專案存放路徑

ServBay 建議開發者將網站專案統一放置於 /Applications/ServBay/www 目錄，方便進行管理與設定。本文也將以此路徑作為範例。

切換至網站根目錄
開啟終端機，切換至 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 連線資訊。FuelPHP 的 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 遷移工具）

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');
    }
}

執行遷移
於專案根目錄（servbay-fuelphp-app）運用 Oil 工具執行遷移，建立資料表：
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 facade（use Fuel\Core\DB;、use Fuel\Core\Redis;）以便直接調用。
Memcached 與 Redis 之快取鍵名皆使用 servbay_ 前綴，避免衝突。
MySQL 新增範例包含目前時間戳及簡易錯誤處理，以貼近實務需求。
FuelPHP 1.x 使用 \Redis_Db::instance() 獲取 Redis 實例。

路由設定

欲經由網址存取剛新增的控制器 Action，請於 fuel/app/config/routes.php 檔案中新增相應路由。FuelPHP 已預設路由至 Controller_Welcome，但針對 memcached、redis、mysql_add、mysql 等 Action，應加以明確指定。

於 fuel/app/config/routes.php 新增或修改回傳陣列如下：

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（若有用）、Memcached（若有用）等服務均顯示執行中。
請於 ServBay 的資料庫管理工具手動建立名為 fuel_dev 的資料庫（或在 db.php 設定已存在之資料庫）。FuelPHP 遷移工具 oil refine migrate 會於指定資料庫中建立資料表，但不會自動新增資料庫本身。
FuelPHP 公開入口為 public/index.php，在 ServBay 網站設定中，網站根目錄務必指向專案 public 子目錄。

結語

透過 ServBay，您能輕鬆於 macOS 上為 FuelPHP 專案打造完整的本地開發環境。本文詳述建立 FuelPHP 專案、設定 ServBay 網站功能、連接資料庫與快取服務，以及以範例程式碼測試所有功能。 ServBay 內建多元服務與簡化設定流程，能大幅提升開發效率。

祝您順利展開在 ServBay 的 FuelPHP 開發之旅！

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

什麼是 FuelPHP？ ​

FuelPHP 的主要特色與優勢 ​

使用 ServBay 建立 FuelPHP 開發環境 ​

前置條件 ​

建立 FuelPHP 專案 ​

網頁伺服器設定 (利用 ServBay 網站功能) ​

設定 FuelPHP 專案服務連線 ​

資料庫設定 ​

快取設定 (Memcached 與 Redis) ​

資料庫與快取服務範例 ​

建立資料表（使用 FuelPHP 遷移工具） ​

加入範例控制器程式碼 ​

路由設定 ​

網站存取與測試 ​

注意事項 ​

結語 ​