使用 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 專案範本:bashComposer 即會將 PHPixie 及其所有依賴安裝於當前目錄。
composer create-project phpixie/project .
1
設定網頁伺服器
使用 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 格式回傳使用者清單 } }
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
60
61
62
63
64
65
66
67**建立範例模板:**在
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>
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
訪問網站首頁
配置好 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
return [
'default' => [
'driver' => 'pdo',
// connection 字串請依您的資料庫及 ServBay 設定調整
'connection' => 'mysql:host=127.0.0.1;dbname=servbay_phpixie_app',
'user' => 'root', // ServBay 預設帳號
'password' => 'password', // ServBay 預設密碼(依實際調整)
'options' => []
]
];
2
3
4
5
6
7
8
9
10
11
12
PostgreSQL 設定範例(assets/config/database.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' => []
]
];
2
3
4
5
6
7
8
9
10
11
12
建立資料表(使用遷移 migration)
PHPixie 提供 CLI 工具管理資料庫遷移(migrations),用於版本化控制資料表結構。
- 開啟終端,切換至專案根目錄:bash
cd /Applications/ServBay/www/servbay-phpixie-app
1 - **建立遷移檔案:**執行 PHPixie CLI 指令,產生一個用於建立
users
表的新遷移檔:bash會於php pixie generate:migration create_users_table
1assets/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'); } }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 - **執行遷移:**於專案根目錄開終端,執行下列命令,建立
users
表:bash若成功,終端會顯示遷移執行成功提示。您也可利用資料庫管理工具確認php pixie migrate
1servbay_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
return [
'default' => [
'driver' => 'memcached',
'servers' => [
[
'host' => '127.0.0.1', // ServBay Memcached 預設位址
'port' => 11211, // ServBay Memcached 預設埠
'weight' => 100,
],
],
],
];
2
3
4
5
6
7
8
9
10
11
12
13
14
Redis 設定(assets/config/redis.php
):
編輯或建立 assets/config/redis.php
,加入以下組態:
<?php
return [
'default' => [
'hostname' => '127.0.0.1', // ServBay Redis 預設位址
'port' => 6379, // ServBay Redis 預設埠
'timeout' => 0,
'database' => 0, // Redis 資料庫 index
],
];
2
3
4
5
6
7
8
9
10
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 專案有所助益!