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

PHPixie 是一款輕量且高效能的 PHP 框架，專為快速開發 Web 應用程式而設計。它遵循 HMVC（階層式模型-視圖-控制器）架構設計，提供簡潔的程式碼結構與高效的處理能力。PHPixie 因其簡單、靈活與高效能而受到許多開發者的青睞。

PHPixie 主要特性與優勢

**輕量級：**PHPixie 核心系統極為精簡，只包含建構應用所需的核心元件，啟動與執行速度極快。
**高效能：**框架設計著重於效能，能夠有效處理高併發請求，適用於對性能要求高的應用。
**易於學習：**提供清晰簡潔的 API 以及完整詳細的文件，讓開發者能快速上手。
**高度彈性：**框架結構鬆耦合，可依專案需求自由選用及整合第三方函式庫或元件。
**活躍的社群支援：**擁有積極的開發者社群，持續提供豐富的第三方擴展與支援資源。

PHPixie 能幫助開發者高效率建構高效能、高品質的 Web 應用，無論是小型專案或大型企業級應用皆適用。

使用 ServBay 建立並運行 PHPixie 專案

本文將引導您，如何利用 ServBay 所提供的本機 Web 開發環境來建立並運行一個 PHPixie 專案。我們將運用 ServBay 整合的 PHP 環境、Composer 依賴管理工具，以及「網站」功能來設定 Web 伺服器，並透過簡單步驟實現專案的本機訪問與資料庫／快取整合。

前置條件

已在 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 版本：**選擇您要使用的 PHP 版本，如 8.3。
- **網站根目錄（Document Root）：**指向專案的 web 目錄：/Applications/ServBay/www/servbay-phpixie-app/web。
為何要指定 /web 目錄？
PHPixie 專案的網站進入點在 web/index.php。依循最佳實踐與安全性考量，應將 Web 伺服器根目錄指向含有此進入點檔案的 web 目錄，而非專案上層資料夾，以防止敏感檔案（如設定檔、vendor 資料夾等）被 Web 直連。
儲存設定。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（請依實際設定確認）。

設定資料庫連線

依您使用的資料庫（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'   => []
    ]
];

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

PHPixie 提供 CLI 工具管理資料庫遷移（migrations），用於版本化控制資料表結構。

開啟終端，切換至專案根目錄：

bash

cd /Applications/ServBay/www/servbay-phpixie-app

**建立遷移檔案：**執行 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(); // Email 欄，唯一
            $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 extension，僅須於 PHPixie 內作對應設定即可。

Memcached 設定（assets/config/cache.php）：

編輯或建立 assets/config/cache.php，加入以下組態：

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，加入以下組態：

php

<?php

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

Memcached／Redis 實際使用方式：

前述 src/App/HTTP/Controller/Home.php 範例控制器已加入分別示範如何以 PHPixie 快取組件操作 Memcached 及 Redis 的 action_memcached 和 action_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 開發下一個 Web 專案有所助益！

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

PHPixie 主要特性與優勢 ​

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

前置條件 ​

建立 PHPixie 專案 ​

設定網頁伺服器 ​

新增範例程式碼 ​

訪問網站首頁 ​

資料庫與快取整合範例 ​

設定資料庫連線 ​

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

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

設定與使用 NoSQL（Memcached／Redis） ​

總結 ​