在 ServBay 中建立並執行 Yii 2 專案

概述：什麼是 Yii 2？

Yii 2 是一個高效能、以元件為基礎的 PHP 框架，適合快速開發現代化的 Web 應用程式。它遵循 MVC（Model-View-Controller）設計模式，並提供豐富的功能與工具，協助開發者高效打造具延展性、高品質的 Web 應用。Yii 2 以其優秀的效能、靈活的架構與強大的內建功能（如快取、安全性、RESTful API 開發支援等）廣受開發者青睞。

Yii 2 的主要特色與優勢

高效能：Yii 2 經過針對高並發需求的優化，非常適合建構對效能要求高的應用程式。
模組化設計：框架高度模組化，方便程式碼組織與元件重複利用。
安全強化：內建多重安全機制，包括輸入驗證、輸出過濾、CSRF/XSS 防護、認證及授權架構等。
易於上手：提供直覺易懂的 API 和詳盡文件，減少入門障礙，開發者可迅速開始開發。
活躍社群：擁有活躍的開發者社群與豐富的第三方套件，遇到問題易於取得協助。
整合工具：內建命令列工具支援資料庫遷移、程式碼產生等任務，提升開發效率。

Yii 2 是開發企業級應用、RESTful API、入口網站等多元 Web 專案的理想選擇。

使用 ServBay 執行 Yii 2 專案

ServBay 是一套專為 macOS 與 Windows 設計的本機 Web 開發平台，整合了 PHP、各類資料庫（如 MySQL、PostgreSQL、MongoDB、Redis）、網站伺服器（Caddy、Nginx）和豐富開發工具（如 Composer、Node.js、Python、Go、Java 等），致力於讓開發者「開箱即用」，效率開發環境更便利。

本教學將引導你如何運用 ServBay 提供的 PHP 執行環境、Composer 工具與資料庫服務，快速建立並啟動一個 Yii 2 基礎應用專案。我們將善用 ServBay 的「網站」功能完成本地 Web 伺服器配置，並藉由步驟演示如何存取專案及實作基本功能。

前置條件

開始之前，請確定你已完成以下步驟：

已於 macOS 或 Windows 上安裝並成功運行 ServBay。
ServBay 中已安裝並啟用所需之 PHP 版本（如 PHP 8.3 或更新版本）。
ServBay 中已安裝並啟用欲使用的資料庫服務（如 MySQL 或 PostgreSQL），以及快取服務（Memcached 和 Redis）。

你可於 ServBay 首頁介面檢視及管理安裝的軟體包與運作狀態。

建立 Yii 2 專案

TIP

ServBay 建議將你的專案檔案儲存於以下路徑，有助於專案結構簡潔，並便於「網站」功能管理：

macOS: /Applications/ServBay/www
Windows: C:\ServBay\www

Composer：ServBay 已內建 Composer 工具，無須另外安裝，可直接於終端執行 composer 指令。

建立專案目錄：打開終端，切換到 ServBay 預設網站根目錄，建立新專案資料夾。

macOS:

bash

cd /Applications/ServBay/www
mkdir servbay-yii2-app
cd servbay-yii2-app

Windows:

cmd

cd C:\ServBay\www
mkdir servbay-yii2-app
cd servbay-yii2-app

使用 Composer 建立 Yii 2 專案：在 servbay-yii2-app 目錄下，運行 Composer 指令建立新的 Yii 2 基礎模板專案。
bash
```
composer create-project --prefer-dist yiisoft/yii2-app-basic .
```
1
此指令會將 Yii 2 基礎模板及所有相依套件下載至目前目錄 (.)。安裝過程可能需數分鐘，請耐心等待 Composer 完成。
切換到專案目錄：確認目前終端所在路徑為專案根目錄，後續指令與操作皆於此目錄進行。
macOS:
bash
```
cd /Applications/ServBay/www/servbay-yii2-app
```
1
Windows:
cmd
```
cd C:\ServBay\www\servbay-yii2-app
```
1

初始化設定

Yii 2 專案建立後，需進行基本設定，尤其包括資料庫連線與元件參數配置。

設定資料庫連線：編輯專案根目錄下的 config/db.php 檔案。根據你於 ServBay 啟用的資料庫服務（MySQL 或 PostgreSQL）及其設定（預設使用者通常為 root，密碼預設為 password，除非你有自訂），請更新資料庫連線資訊。

首先，需於 ServBay 中啟用的資料庫服務建立新的資料庫，如命名為 servbay_yii2_app。可使用 ServBay 內含的 Adminer 工具或你習慣的資料庫客戶端（如 Sequel Ace、TablePlus 等）建立資料庫。Adminer 可從 ServBay 應用介面的資料庫區塊存取。

針對 MySQL：

php

<?php

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=servbay_yii2_app', // dbname 請填入你建立的資料庫名稱
    'username' => 'root', // 資料庫使用者名稱
    'password' => 'password', // 資料庫密碼
    'charset' => 'utf8mb4', // 建議用 utf8mb4，支援更多字元集
];

針對 PostgreSQL：

php

<?php

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'pgsql:host=127.0.0.1;port=5432;dbname=servbay_yii2_app', // dbname 為你建立的資料庫名稱, port 預設為 5432
    'username' => 'root', // 資料庫使用者名稱
    'password' => 'password', // 資料庫密碼
    'charset' => 'utf8',
    'schemaMap' => [
        'pgsql' => [
            'class' => 'yii\pgsql\Schema',
            'defaultSchema' => 'public', // PostgreSQL 預設 schema
        ],
    ],
];

請依據實際需求選用並調整 config/db.php 設定檔。

設定快取與 Redis 元件：編輯專案根目錄的 config/web.php，在 components 配置段落增修 Memcached 與 Redis。ServBay 預設 Memcached 埠號為 11211，Redis 為 6379。

php

<?php
// ... 其他設定項

'components' => [
    // ... 其他元件設定 (如 request, cache, user, errorHandler, log, urlManager)

    'cache' => [
        'class' => 'yii\caching\MemCache',
        'servers' => [
            [
                'host' => '127.0.0.1',
                'port' => 11211, // Memcached 預設埠號
                'weight' => 100,
            ],
        ],
    ],

    'redis' => [
        'class' => 'yii\redis\Connection',
        'hostname' => '127.0.0.1',
        'port' => 6379, // Redis 預設埠號
        'database' => 0, // Redis 資料庫索引
    ],

    // ... 其他元件
],

// ... 其他設定項

請確保已於 ServBay 啟動 Memcached 及 Redis 服務。使用 Redis 作為快取來源需要安裝 yiisoft/yii2-redis 套件（Composer 安裝基礎模板時會包含基本相依，若未安裝可用 composer require yiisoft/yii2-redis）。Memcached 通常使用 yiisoft/yii2-memcached。基礎模板通常已涵蓋主要套件。

設定網站伺服器（ServBay 網站）

透過 ServBay 的「網站」功能，指派本機 Web 伺服器（Caddy 或 Nginx）指向你的 Yii 2 專案目錄。

啟動 ServBay 應用程式：開啟 ServBay。
進入網站設定頁：於 ServBay 主介面點擊「網站」或類似導覽選項。
新增網站：點擊新增網站（通常是 + 或 新增 按鈕）。
填寫網站資訊：
- 名稱：輸入容易辨識的名稱，如 My First Yii 2 Dev Site。
- 網域：指定本地開發用網域，如 servbay-yii2-test.local。ServBay 會自動設定本機 DNS，使其指向 127.0.0.1。
- 網站型態：選擇 PHP。
- PHP 版本：設定欲使用 PHP 版本（如 8.3），請確定該版本已安裝並啟用。
- 網站根目錄：此步請特別注意。對 Yii 2 基礎模板，網頁入口為專案根下的 web 子目錄，故網站根目錄應設為：
  - macOS: /Applications/ServBay/www/servbay-yii2-app/web
  - Windows: C:\ServBay\www\servbay-yii2-app\web
儲存並套用：儲存網站設定，ServBay 會自動重新載入 Web 伺服器設定，立即生效。

網站詳細設定亦可參考官方說明：新增第一個網站。

ServBay 會為本機開發網域自動簽發並信任 SSL 憑證（由 ServBay User CA 或 ServBay Public CA 核發），因此可放心以 HTTPS 存取網站。

範例程式碼演示功能

為展示資料庫與快取功能，可於 Yii 2 的預設控制器中新增測試操作。

編輯專案根目錄下 controllers/SiteController.php，於 SiteController 類別加入下列方法：

php

<?php

namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;
use yii\db\Exception as DbException; // 匯入資料庫例外處理類別

class SiteController extends Controller
{
    /**
     * 顯示首頁。
     *
     * @return string
     */
    public function actionIndex()
    {
        return $this->render('index');
    }

    /**
     * 演示 Memcached 使用。
     *
     * @return Response
     */
    public function actionMemcached()
    {
        $cache = Yii::$app->cache;
        $key = 'my_memcached_test_key';
        $data = 'Hello Memcached from ServBay!';
        $duration = 60; // 快取 60 秒

        if ($cache->set($key, $data, $duration)) {
            $value = $cache->get($key);
            return $this->asText("Memcached 設置成功。取得的數值：" . $value);
        } else {
            return $this->asText("Memcached 儲存失敗。請確認 Memcached 服務與設定。");
        }
    }

    /**
     * 演示 Redis 使用。
     *
     * @return Response
     */
    public function actionRedis()
    {
        $redis = Yii::$app->redis;
        $key = 'my_redis_test_key';
        $data = 'Hello Redis from ServBay!';

        try {
            if ($redis->set($key, $data)) {
                $value = $redis->get($key);
                return $this->asText("Redis 設置成功。取得的數值：" . $value);
            } else {
                 return $this->asText("Redis 儲存失敗。請確認 Redis 服務與相關設定。");
            }
        } catch (\yii\base\Exception $e) {
             return $this->asText("Redis 錯誤：" . $e->getMessage() . "。請檢查 Redis 服務與設定。");
        }
    }

    /**
     * 演示資料庫新增使用者。
     * 假設已建立 'users' 資料表。
     *
     * @return Response
     */
    public function actionMysqlAdd() // PostgreSQL 亦可用, 請正確設定 config
    {
        try {
            $count = Yii::$app->db->createCommand()->insert('users', [
                'name' => 'ServBay Demo User', // 品牌相關演示使用者名稱
                'email' => 'demo-user@servbay.test', // 品牌相關演示信箱
            ])->execute();
            return $this->asText("使用者新增成功。影響筆數：" . $count);
        } catch (DbException $e) {
            return $this->asText("新增使用者失敗。錯誤：" . $e->getMessage() . "。請檢查資料庫服務、設定，以及 'users' 資料表是否存在。");
        }
    }

    /**
     * 演示資料庫查詢使用者。
     * 假設已建立 'users' 資料表。
     *
     * @return Response
     */
    public function actionMysql() // PostgreSQL 亦可用, 請正確設定 config
    {
        try {
            $users = Yii::$app->db->createCommand('SELECT id, name, email FROM users')->queryAll();
             // 格式化輸出，避免直接回傳敏感資訊或混亂格式
            $output = "查詢使用者列表：\n";
            foreach ($users as $user) {
                $output .= "- ID: {$user['id']}, Name: {$user['name']}, Email: {$user['email']}\n";
            }
            return $this->asText($output);

        } catch (DbException $e) {
            return $this->asText("資料庫查詢失敗。錯誤：" . $e->getMessage() . "。請檢查資料庫服務、設定，以及 'users' 資料表是否存在。");
        }
    }

    // 若使用 PostgreSQL，可另外加 action 方法，但多數情況共用 db 元件即可
    // public function actionPgsqlAdd() { ... }
    // public function actionPgsql() { ... }

    /**
     * 輸出純文字格式。
     * @param string $text
     * @return Response
     */
    protected function asText($text)
    {
        Yii::$app->response->format = Response::FORMAT_RAW;
        Yii::$app->response->getHeaders()->add('Content-Type', 'text/plain');
        return $text;
    }

    /**
     * 輸出 JSON 格式。
     * @param mixed $data
     * @return Response
     */
    protected function asJson($data)
    {
        Yii::$app->response->format = Response::FORMAT_JSON;
        return $data;
    }
}

上述範例在 actionMysqlAdd 與 actionMysql 中加入了錯誤處理與輸出格式優化，並示範品牌化的使用者名稱與信箱。

編輯專案根目錄下的 views/site/index.php，此檔為 actionIndex 對應的前台畫面，可保持預設內容或進行自訂：

php

<?php
/* @var $this yii\web\View */
/* @var $name string */
/* @var $message string */
/* @var $exception Exception */

use yii\helpers\Html;

$this->title = 'My Yii2 Application on ServBay'; // 更新標題
?>
<div class="site-index">
    <div class="jumbotron">
        <h1>恭喜！</h1>
        <p class="lead">你已成功建立 Yii2 專案並完成 ServBay 設定！</p>
        <p><a class="btn btn-lg btn-success" href="https://www.yiiframework.com">開始使用 Yii</a></p>
    </div>

    <div class="body-content">
        <h2>示範功能</h2>
        <ul>
            <li><a href="<?= Html::toRoute('site/memcached') ?>">測試 Memcached</a></li>
            <li><a href="<?= Html::toRoute('site/redis') ?>">測試 Redis</a></li>
            <li><a href="<?= Html::toRoute('site/mysql-add') ?>">新增使用者至資料庫</a>（需有 'users' 資料表）</li>
            <li><a href="<?= Html::toRoute('site/mysql') ?>">查詢資料庫使用者</a>（需有 'users' 資料表）</li>
        </ul>
        <p>請確保 Memcached、Redis，及你的資料庫（MySQL/PostgreSQL）服務已於 ServBay 啟動並正確設定於 `config/web.php` 與 `config/db.php`。</p>
        <p>若要進行資料庫範例，請先透過遷移建立 'users' 資料表（見下方說明）。</p>
    </div>
</div>

已於前台示意頁面加上連結，便於測試新增的控制器功能。

關聯式資料庫：建立資料表（遷移）

若要執行 actionMysqlAdd, actionMysql 相關資料庫示範，需先於資料庫建立 users 表。Yii 建議以資料庫遷移（migrations）方式管理 schema 變更。

使用 Gii 工具建立遷移檔：開啟終端，確保目前路徑為專案根目錄，執行 Yii 控制台指令建立新遷移檔案。
專案根目錄路徑：
- macOS: /Applications/ServBay/www/servbay-yii2-app
- Windows: C:\ServBay\www\servbay-yii2-app
bash
```
php yii migrate/create create_users_table
```
1
系統會顯示確認訊息，輸入 yes 繼續，將於 migrations 資料夾產生一個名為 mYYYYMMDD_HHMMSS_create_users_table.php 的遷移檔。

編輯遷移檔案：打開產生的遷移檔，在 up() 方法設定 users 資料表結構。

php

<?php

use yii\db\Migration;

/**
 * 建立資料表 `{{%users}}`。
 */
class mXXXXXXXXXXXXXX_create_users_table extends Migration // XXXXXXXXXXXXXX 為時間戳
{
    /**
     * {@inheritdoc}
     */
    public function up()
    {
        $this->createTable('{{%users}}', [ // 使用 {{%users}} 支援表前綴（若有設定）
            'id' => $this->primaryKey(),
            'name' => $this->string()->notNull(),
            'email' => $this->string()->notNull()->unique(),
            'created_at' => $this->timestamp()->defaultExpression('CURRENT_TIMESTAMP'),
            'updated_at' => $this->timestamp()->defaultExpression('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'),
        ]);

        // 選用：建立索引提升查詢效率
        $this->createIndex(
            'idx-users-email',
            '{{%users}}',
            'email',
            true // true 代表唯一索引
        );
    }

    /**
     * {@inheritdoc}
     */
    public function down()
    {
        // 刪除索引
        $this->dropIndex(
            'idx-users-email',
            '{{%users}}'
        );

        // 刪除資料表
        $this->dropTable('{{%users}}');
    }
}

請將 mXXXXXXXXXXXXXX_create_users_table 替換為實際檔名。

執行遷移：於終端，仍在專案根目錄，輸入 Yii 控制台指令執行遷移，依 up() 內容於資料庫建立表結構。
bash
```
php yii migrate
```
1
系統提示時請輸入 yes，若順利完成則會看到表建立成功訊息。

存取網站並測試

此時可於瀏覽器打開 ServBay 設定的網域 https://servbay-yii2-test.local。

訪問 https://servbay-yii2-test.local：預設會出現 Yii 2 基礎模板歡迎畫面，同時可見先前於 views/site/index.php 加入的各項示範連結。
點擊「測試 Memcached」或前往 https://servbay-yii2-test.local/index.php?r=site/memcached：若 Memcached 服務運作且設定正確，將看到 "Memcached 設置成功…" 的純文字回饋。
點擊「測試 Redis」或前往 https://servbay-yii2-test.local/index.php?r=site/redis：若 Redis 服務運作且設定正確，將看到 "Redis 設置成功…" 的純文字回饋。
點擊「新增使用者至資料庫」或前往 https://servbay-yii2-test.local/index.php?r=site/mysql-add：若資料庫服務運作、設定正確且已建立 users 表，將看到 "使用者新增成功…" 的純文字回饋。每次點擊均會嘗試新增一筆新用戶（若 email 已唯一且存在則可能失敗）。
點擊「查詢資料庫使用者」或前往 https://servbay-yii2-test.local/index.php?r=site/mysql：若資料庫服務運作、設定正確且 users 表存在，將查詢並顯示所有使用者列表。

如遇問題，請檢查 ServBay 中 PHP、Web 伺服器、資料庫、Memcached、Redis 各項服務是否啟動，並確認 Yii 2 專案設定（config/db.php, config/web.php）無誤，以及資料表已順利建立。

常見問題解答（FAQ）

為何網域造訪時出現「無法存取此網站」或憑證錯誤？ 請確定已於 ServBay「網站」設定中正確新增網域，並確保 ServBay 應用程式運行中。ServBay 會自動配置本機 DNS 與 SSL 憑證，若出現憑證錯誤請確認已信任 ServBay User CA 或 ServBay Public CA，詳情請參考 ServBay 官方說明。
Composer 指令無法執行？ 請確認已在 ServBay 主介面啟用 Composer 軟體包，並於 macOS 終端執行命令。ServBay 會自動將內建 Composer 加入你的 PATH。
資料庫連線失敗？ 請檢查所需的資料庫服務（MySQL/PostgreSQL）是否於 ServBay 執行中，並確認 config/db.php 內的 dsn、username、password 與 ServBay 資料庫設定一致。此外，請確認已建立 servbay_yii2_app 資料庫，可利用 Adminer 工具檢查連線與資料庫清單。
Memcached/Redis 連線失敗？ 請查驗 Memcached、Redis 服務於 ServBay 是否啟動，並確認 config/web.php 內對應元件之 host 與 port 正確（預設為 127.0.0.1 及相應預設埠號）。
資料庫遷移（php yii migrate）執行失敗？ 請確認 config/db.php 設定正確無誤，且資料庫服務已啟動且已創建目標資料庫。遷移指令需能連線成功方可操作。
執行 actionMysqlAdd / actionMysql 時提示表不存在？ 請先執行資料庫遷移指令 php yii migrate 建立 users 表。
如何查看 PHP 錯誤日誌？ ServBay 集中管理 PHP 錯誤日誌、Web 伺服器日誌等。可於 ServBay 主介面「日誌」區塊查看詳細記錄，協助錯誤診斷。

結語

經由 ServBay，你可輕鬆於 macOS 與 Windows 上建置功能完整的本機開發環境，快速執行 Yii 2 專案。ServBay 預載 Composer、可選 PHP 版本管理、內建資料庫及快取服務，以及便利的網站配置，大幅簡化 Yii 2 專案部署與開發流程。依循本教學，你將可以高效率展開 Yii 2 開發之旅，全面活用 ServBay 工具提升工作效能。

祝開發順利！

在 ServBay 中建立並執行 Yii 2 專案 ​

概述：什麼是 Yii 2？ ​

Yii 2 的主要特色與優勢 ​

使用 ServBay 執行 Yii 2 專案 ​

前置條件 ​

建立 Yii 2 專案 ​

初始化設定 ​

設定網站伺服器（ServBay 網站） ​

範例程式碼演示功能 ​

關聯式資料庫：建立資料表（遷移） ​

存取網站並測試 ​

常見問題解答（FAQ） ​

結語 ​