使用 ServBay 在 macOS 上建立並運行 PHPixie 專案

PHPixie 是一款輕量且高效能的 PHP 框架，專為快速開發網頁應用程式而設計。它採用 HMVC（階層式模型-視圖-控制器）設計模式，並提供簡潔的程式架構與優異的處理能力。PHPixie 以簡單、靈活和高效聞名，廣受眾多開發者喜愛。

PHPixie 的主要特色與優勢

輕量級： PHPixie 核心系統十分簡潔，僅包含建構應用所需的必要元件，啟動與運行極為迅速。
高效能： 框架注重效能，能有效處理並發請求，適合對效能有較高要求的應用場景。
易於學習： 提供清晰簡潔的 API 與完整文件，開發者可迅速上手。
高度靈活： 框架結構採用鬆耦合設計，能依需求自由整合第三方程式庫及元件。
活躍社群支持： 擁有積極的開發者社群，提供豐富的第三方擴充與各類資源。

PHPixie 能協助開發者高效建構高品質、高效能的網頁應用，適用於小型專案至大型企業級應用等各類開發情境。

使用 ServBay 建立並運行 PHPixie 專案

本文將引導你如何利用 ServBay 內建的本機網頁開發環境來建立並運行 PHPixie 專案。我們會示範如何用 ServBay 整合的 PHP 環境、Composer 依賴管理工具，以及「網站」功能來配置網頁伺服器，並經由簡單步驟進行本機專案存取與資料庫/快取整合。

先決條件

已在 macOS 安裝並執行 ServBay。ServBay 已整合 PHP、Composer、各類資料庫（MySQL、PostgreSQL、MongoDB、Redis 等）以及 Caddy 網頁伺服器。
熟悉基本命令列操作。

建立 PHPixie 專案

建議的網站存放路徑

ServBay 建議將本機網站專案統一放於 /Applications/ServBay/www 目錄下，便於管理及 ServBay 存取權限控管。

確認 Composer 已安裝： ServBay 出廠已【內建 Composer】，無需額外安裝。你可開啟終端機，輸入 composer --version 來檢查。
建立專案目錄： 在 ServBay 建議的網站根目錄下建立新目錄以儲存 PHPixie 專案並切換至該目錄：
bash
```
cd /Applications/ServBay/www
mkdir servbay-phpixie-app
cd servbay-phpixie-app
```
1
2
3
使用 Composer 建立 PHPixie 專案： 在專案目錄內執行 Composer 指令以載入 PHPixie 專案模板：
bash
```
composer create-project phpixie/project .
```
1
Composer 將會下載 PHPixie 及其所有依賴至目前目錄。

設定網頁伺服器

使用 ServBay 的【網站】功能設定 Caddy 網頁伺服器，讓其能正確指向並運行你的 PHPixie 專案。

打開 ServBay 應用程式介面。
導航至 網站 (Websites) 列表。
點選新增網站。
填寫網站設定資訊：
- 名稱： 如 My First PHPixie Dev Site（此為 ServBay 內部識別名稱）。
- 網域： 如 servbay-phpixie-test.local（你將於瀏覽器存取的本機開發網域）。
- 網站類型： 選擇 PHP。
- PHP 版本： 選擇你想使用的版本，如 8.3。
- 網站根目錄 (Document Root)： 指向你專案的 web 目錄：/Applications/ServBay/www/servbay-phpixie-app/web。
為何選擇 /web 目錄？
PHPixie 專案的入口檔為 web/index.php。為了安全及最佳實踐，網頁伺服器根目錄應直接指向含有此入口檔的 web 目錄，而非專案頂層目錄。如此可避免經由 Web 直接存取到專案敏感檔案（如配置檔、vendor 目錄等）。
儲存設定後，ServBay 會自動配置 Caddy，並更新你的本機 hosts 檔（如有需要），使 servbay-phpixie-test.local 指向本機 ServBay 伺服器。

完整設定步驟請參考新增第一個網站。

新增範例程式碼

為了驗證專案運作正常並展示資料庫及快取整合，於專案中加入部分範例程式碼。

建立範例控制器： 於 src/App/HTTP/Controller/Home.php 新增以下程式碼，若目錄或檔案不存在請自行建立。

php

<?php

namespace App\HTTP\Controller;

use PHPixie\HTTP\Request;
use PHPixie\Template;
use PHPixie\Database\Query; // 引入 Query 類別

class Home extends \PHPixie\Controller
{
    protected $template;

    public function __construct(Template $template)
    {
        $this->template = $template;
    }

    // 預設首頁 action
    public function action_index(Request $request)
    {
        // 渲染 assets/templates/app/home.php 模板
        return $this->template->render('app:home');
    }

    // Memcached 範例 action
    public function action_memcached(Request $request)
    {
        $cache = $this->components->cache();
        $cache->set('key', 'Hello Memcached from ServBay!', 60); // 儲存資料，有效期 60 秒
        $value = $cache->get('key'); // 取得資料
        return $this->response()->string($value); // 回傳字串響應
    }

    // Redis 範例 action
    public function action_redis(Request $request)
    {
        $redis = $this->components->redis();
        $redis->set('key', 'Hello Redis from ServBay!'); // 儲存資料
        $value = $redis->get('key'); // 取得資料
        return $this->response()->string($value); // 回傳字串響應
    }

    // MySQL/PostgreSQL 新增使用者範例 action
    public function action_add_user(Request $request)
    {
        // 使用資料庫元件取得查詢建構器
        $query = $this->components->database()->query();
        // 向 'users' 資料表插入新使用者資料
        $query->insert('users')->data([
            'name' => 'ServBay Demo User',
            'email' => 'demo-' . uniqid() . '@servbay.test', // 使用唯一 email
        ])->execute(); // 執行插入操作

        return $this->response()->string('User added successfully.'); // 回傳成功訊息
    }

    // MySQL/PostgreSQL 取得使用者列表範例 action
    public function action_list_users(Request $request)
    {
        // 使用資料庫元件取得查詢建構器
        $query = $this->components->database()->query();
        // 查詢 'users' 資料表裡的所有使用者
        $users = $query->select('*')->from('users')->execute()->fetchAll(); // 執行查詢並取得所有結果

        return $this->response()->json($users); // 回傳 JSON 格式使用者列表
    }
}

建立範例模板： 於 assets/templates/app/home.php 新增以下程式碼，若目錄或檔案不存在請自行建立。

php

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Welcome to PHPixie on ServBay</title>
    <style>
        body { font-family: sans-serif; line-height: 1.6; margin: 20px; }
        h1 { color: #333; }
        p { margin-bottom: 15px; }
        code { background-color: #f4f4f4; padding: 2px 5px; border-radius: 4px; }
        ul { list-style: none; padding: 0; }
        li { margin-bottom: 10px; }
        li a { text-decoration: none; color: #007bff; }
        li a:hover { text-decoration: underline; }
    </style>
</head>
<body>
    <h1>Welcome to PHPixie on ServBay</h1>
    <p>This page is being generated dynamically by your PHPixie application running on ServBay.</p>

    <h2>功能範例連結：</h2>
    <ul>
        <li><a href="/home/memcached">測試 Memcached</a></li>
        <li><a href="/home/redis">測試 Redis</a></li>
        <li><a href="/home/add_user">新增使用者至資料庫</a></li>
        <li><a href="/home/list_users">列出資料庫使用者</a></li>
    </ul>

    <p>請確認你已依步驟完成相關資料庫與快取設定。</p>

</body>
</html>

存取基本網站

完成 ServBay 網站設定與加入範例程式碼後，現在你可於瀏覽器存取設定之網域：

開啟瀏覽器，前往 https://servbay-phpixie-test.local
應能看到「Welcome to PHPixie on ServBay」頁面，以及各項功能範例連結。

如無法正常存取，請檢查：

ServBay 是否正在執行。
ServBay 此網站設定是否正確，包含網域、類型與網站根目錄。
本機 hosts 檔是否正常解析 servbay-phpixie-test.local（ServBay 通常會自動處理）。
ServBay 使用的 PHP 版本是否已啟用。

資料庫與快取整合範例

PHPixie 直接支援多種資料庫與快取系統。ServBay 提供 MySQL、PostgreSQL、Redis、Memcached 等安裝包，可輕鬆整合至 PHPixie 專案。

重要提示： 在進行資料庫操作前，請確認已啟動 ServBay 對應資料庫服務（如 MySQL 或 PostgreSQL），並已建立專案用的資料庫。本範例使用之資料庫名稱為 servbay_phpixie_app。你可利用 ServBay 內建的資料庫管理工具（如 Sequel Ace、Postico、TablePlus 等）或命令列工具建立資料庫。ServBay 預設的資料庫使用者通常為 root，密碼為 password（請依你的 ServBay 設定確認）。

配置資料庫連線

根據你使用的資料庫類型（MySQL 或 PostgreSQL），請編輯專案根目錄下的 assets/config/database.php 檔案。ServBay 預設資料庫主機通常為 127.0.0.1。

MySQL 配置範例 (assets/config/database.php)：

php

<?php

return [
    'default' => [
        'driver'    => 'pdo',
        // connection 字串請依據你的資料庫類型及 ServBay 設定調整
        'connection' => 'mysql:host=127.0.0.1;dbname=servbay_phpixie_app',
        'user'      => 'root', // ServBay 預設使用者
        'password'  => 'password', // ServBay 預設密碼（請根據實際設定修改）
        'options'   => []
    ]
];

PostgreSQL 配置範例 (assets/config/database.php)：

php

<?php

return [
    'default' => [
        'driver'    => 'pdo',
        // connection 字串請依據你的資料庫類型及 ServBay 設定調整
        'connection' => 'pgsql:host=127.0.0.1;dbname=servbay_phpixie_app',
        'user'      => 'root', // ServBay 預設使用者
        'password'  => 'password', // ServBay 預設密碼（請根據實際設定修改）
        'options'   => []
    ]
];

建立資料表（使用遷移）

PHPixie 提供命令列工具管理資料庫遷移，可版本控制資料表結構。

開啟終端機： 切換至你的 PHPixie 專案根目錄：
bash
```
cd /Applications/ServBay/www/servbay-phpixie-app
```
1
建立遷移檔： 執行 PHPixie CLI 工具以產生新的遷移檔，這裡以建立 users 資料表為例：
bash
```
php pixie generate:migration create_users_table
```
1
此指令會在 assets/migrations 目錄下產生一個新的 PHP 檔，檔名包含時間戳。

編輯遷移檔： 開啟 assets/migrations 新產生的遷移檔（如 YYYY_MM_DD_HHMMSS_create_users_table.php），編輯其中的 up() 與 down() 方法以定義 users 資料表結構：

php

<?php

use PHPixie\Database\Migration;
use PHPixie\Database\Schema\Table;

class CreateUsersTable extends Migration
{
    public function up()
    {
        // 使用 schema 建構器建立 'users' 資料表
        $this->schema->create('users', function(Table $table) {
            $table->increments('id'); // 自動遞增主鍵
            $table->string('name'); // 姓名欄位
            $table->string('email')->unique(); // 信箱欄位，唯一
            $table->timestamps(); // created_at 與 updated_at 時間戳欄位
        });
    }

    public function down()
    {
        // 使用 schema 建構器刪除 'users' 資料表
        $this->schema->drop('users');
    }
}

執行遷移： 於專案根目錄終端機執行以下指令以建立 users 資料表：
bash
```
php pixie migrate
```
1
若一切順利，終端機會顯示遷移成功提示。你也可透過資料庫管理工具確認 servbay_phpixie_app 資料庫已建立 users 表。

使用關聯式資料庫（MySQL/PostgreSQL）

於上述範例控制器 src/App/HTTP/Controller/Home.php 中，我們已提供了 action_add_user 和 action_list_users 方法，示範如何以 PHPixie 資料庫元件與 MySQL 或 PostgreSQL 互動。

新增使用者： 前往 https://servbay-phpixie-test.local/home/add_user 會向 users 資料表插入一筆新使用者。
列出使用者： 前往 https://servbay-phpixie-test.local/home/list_users 會查詢 users 資料表所有使用者並以 JSON 格式回傳。

配置及使用 NoSQL 資料庫（Memcached/Redis）

ServBay 已預裝 Memcached 和 Redis 套件及其 PHP 擴充，只需在 PHPixie 專案中進行設定即可使用。

Memcached 配置 (assets/config/cache.php)：

編輯或建立 assets/config/cache.php 檔案，加入 Memcached 設定：

php

<?php

return [
    'default' => [
        'driver' => 'memcached',
        'servers' => [
            [
                'host'   => '127.0.0.1', // ServBay Memcached 預設位置
                'port'   => 11211, // ServBay Memcached 預設埠
                'weight' => 100,
            ],
        ],
    ],
];

Redis 配置 (assets/config/redis.php)：

編輯或建立 assets/config/redis.php 檔案，加入 Redis 設定：

php

<?php

return [
    'default' => [
        'hostname' => '127.0.0.1', // ServBay Redis 預設位置
        'port'     => 6379, // ServBay Redis 預設埠號
        'timeout'  => 0,
        'database' => 0, // Redis 資料庫索引
    ],
];

Memcached/Redis 使用方式：

在上面控制器範例 src/App/HTTP/Controller/Home.php 已示範了 action_memcached 及 action_redis，可用於測試 PHPixie 的快取元件（透過設定後端可為 Memcached 或 Redis）。

測試 Memcached： 前往 https://servbay-phpixie-test.local/home/memcached 會寫入一個鍵值至 Memcached，再讀取並顯示其值。
測試 Redis： 前往 https://servbay-phpixie-test.local/home/redis 會寫入一個鍵值至 Redis，再讀取並顯示其值。

請確認 ServBay 已啟動對應軟體包（Memcached 與 Redis）。

結語

依前述步驟，你已順利運用 ServBay，在 macOS 本機環境下建立、配置並執行一個 PHPixie 專案。你學會了如何使用 Composer 建立專案、利用 ServBay 的【網站】功能設定網頁伺服器、完成基本資料庫及快取整合設定，並成功驗證各功能服務可用性。

ServBay 所帶來的一站式整合環境，大幅簡化 PHP 開發環境的配置流程，讓你能更專注程式本身的開發。希望此教學能助你快速啟動 PHPixie，開發你的下一個網頁專案！

使用 ServBay 在 macOS 上建立並運行 PHPixie 專案 ​

PHPixie 的主要特色與優勢 ​

使用 ServBay 建立並運行 PHPixie 專案 ​

先決條件 ​

建立 PHPixie 專案 ​

設定網頁伺服器 ​

新增範例程式碼 ​

存取基本網站 ​

資料庫與快取整合範例 ​

配置資料庫連線 ​

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

使用關聯式資料庫（MySQL/PostgreSQL） ​

配置及使用 NoSQL 資料庫（Memcached/Redis） ​

結語 ​