在 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 設計的本機 Web 開發環境，內建 PHP、多種資料庫（如 MySQL、PostgreSQL、MongoDB、Redis）、Web 伺服器（Caddy、Nginx）及開發常用工具（Composer、Node.js、Python、Go、Java 等），旨在為開發者提供「開箱即用」的便利開發平台。

本指南將引導您如何透過 ServBay 內建 PHP 環境、Composer 工具及資料庫服務，建立並運行一個 Yii 2 基礎應用專案。我們會利用 ServBay 的「網站」功能設定本機 Web 伺服器，並步驟說明如何訪問及演示專案基本功能。

前置準備

開始前，請確保您已經：

在 macOS 上成功安裝並啟動 ServBay。
已在 ServBay 安裝並啟用所需 PHP 版本（如 PHP 8.3 或更新版本）。
已在 ServBay 安裝並啟用您將使用的資料庫服務（如 MySQL 或 PostgreSQL）及快取服務（Memcached 和 Redis）。

您可在 ServBay 主介面查看及管理已安裝套件與服務狀態。

建立 Yii 2 專案

TIP

ServBay 建議將您的專案檔案存放於 /Applications/ServBay/www 資料夾下。這可維持檔案結構整潔，亦有利於 ServBay「網站」功能集中管理。

Composer：ServBay 已內建 Composer 工具，無需額外安裝。可直接在終端執行 composer 指令。
建立專案資料夾：打開終端，切換到 ServBay 預設網站根目錄，並新建專案資料夾。
bash
```
cd /Applications/ServBay/www
mkdir servbay-yii2-app
cd servbay-yii2-app
```
1
2
3
用 Composer 建立 Yii 2 專案：在 servbay-yii2-app 資料夾中，執行 Composer 指令以建立 Yii 2 基礎應用範本。
bash
```
composer create-project --prefer-dist yiisoft/yii2-app-basic .
```
1
此指令會將 Yii 2 基礎應用模板及所有相依套件下載至目前目錄（.）。請耐心等候 Composer 完成安裝步驟。
進入專案目錄：確保目前終端在專案根目錄 /Applications/ServBay/www/servbay-yii2-app，後續所有指令皆於此執行。
bash
```
cd /Applications/ServBay/www/servbay-yii2-app
```
1

初始化設定

建立好 Yii 2 專案後，需執行一些基礎設定，尤其是資料庫連線及元件設定。

設定資料庫連線：編輯專案根目錄下的 config/db.php 檔。依照您在 ServBay 啟動的資料庫服務（MySQL 或 PostgreSQL）及其設定（預設用戶通常為 root，密碼預設為 password，除非有修改過），更新連線資訊。

首先請於 ServBay 的資料庫服務中建立一個新資料庫（例如命名為 servbay_yii2_app），可使用內建的 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 請依實際情況調整
    '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 資料庫索引
    ],

    // ... 其他元件
],

// ... 其他設定

請確認 Memcached、Redis 服務已在 ServBay 中啟動。若要以 Redis 作為快取，必須安裝 yiisoft/yii2-redis 套件（Composer 於 create-project 時會安裝基礎依賴，若尚未裝請自行使用 composer require yiisoft/yii2-redis）。Memcached 通常需 yiisoft/yii2-memcached。基礎模板可能已預含相依套件。

設定 Web 伺服器 (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 資料夾，請設為：/Applications/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
{
    /**
     * Displays homepage.
     *
     * @return string
     */
    public function actionIndex()
    {
        return $this->render('index');
    }

    /**
     * Demonstrates Memcached usage.
     *
     * @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 set successfully. Retrieved value: " . $value);
        } else {
            return $this->asText("Failed to set data in Memcached. Please check Memcached service and configuration.");
        }
    }

    /**
     * Demonstrates Redis usage.
     *
     * @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 set successfully. Retrieved value: " . $value);
            } else {
                 return $this->asText("Failed to set data in Redis. Please check Redis service and configuration.");
            }
        } catch (\yii\base\Exception $e) {
             return $this->asText("Redis error: " . $e->getMessage() . ". Please check Redis service and configuration.");
        }
    }

    /**
     * Demonstrates adding a user to the database.
     * Assumes a 'users' table exists.
     *
     * @return Response
     */
    public function actionMysqlAdd() // 亦可用於 PostgreSQL，只要設定正確
    {
        try {
            $count = Yii::$app->db->createCommand()->insert('users', [
                'name' => 'ServBay Demo User', // 品牌展示用名稱
                'email' => '[email protected]', // 品牌展示用信箱
            ])->execute();
            return $this->asText("User added successfully. Rows affected: " . $count);
        } catch (DbException $e) {
            return $this->asText("Failed to add user to database. Error: " . $e->getMessage() . ". Please check database service, configuration, and ensure 'users' table exists.");
        }
    }

    /**
     * Demonstrates fetching users from the database.
     * Assumes a 'users' table exists.
     *
     * @return Response
     */
    public function actionMysql() // 亦可用於 PostgreSQL，只要設定正確
    {
        try {
            $users = Yii::$app->db->createCommand('SELECT id, name, email FROM users')->queryAll();
             // 格式化輸出，避免顯示敏感資訊或格式錯亂
            $output = "Fetched Users:\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("Failed to fetch users from database. Error: " . $e->getMessage() . ". Please check database service, configuration, and ensure 'users' table exists.");
        }
    }

    // 若您使用 PostgreSQL，可另外加寫 action，但一般共用 db 元件即可
    // public function actionPgsqlAdd() { ... }
    // public function actionPgsql() { ... }

    /**
     * Formats output as plain text.
     * @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;
    }

    /**
     * Formats output as JSON.
     * @param mixed $data
     * @return Response
     */
    protected function asJson($data)
    {
        Yii::$app->response->format = Response::FORMAT_JSON;
        return $data;
    }
}

請注意，actionMysqlAdd 與 actionMysql 中已加入錯誤處理，並稍作輸出格式調整，更貼合實際需求，使用示範數據符合 ServBay 品牌規範。

編輯專案根目錄下的 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>Congratulations!</h1>
        <p class="lead">You have successfully created your Yii2 application and configured it with ServBay!</p>
        <p><a class="btn btn-lg btn-success" href="https://www.yiiframework.com">Get started with Yii</a></p>
    </div>

    <div class="body-content">
        <h2>Demonstrations</h2>
        <ul>
            <li><a href="<?= Html::toRoute('site/memcached') ?>">Test Memcached</a></li>
            <li><a href="<?= Html::toRoute('site/redis') ?>">Test Redis</a></li>
            <li><a href="<?= Html::toRoute('site/mysql-add') ?>">Add a user to DB</a> (Requires 'users' table)</li>
            <li><a href="<?= Html::toRoute('site/mysql') ?>">Fetch users from DB</a> (Requires 'users' table)</li>
        </ul>
        <p>Please ensure Memcached, Redis, and your chosen database (MySQL/PostgreSQL) services are running in ServBay and configured correctly in `config/web.php` and `config/db.php`.</p>
        <p>For database examples, you need to create the 'users' table using Yii migrations (see below).</p>
    </div>
</div>

視圖中增加了鏈結，方便直接測試新加的控制器動作。

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

若要測試資料庫相關動作（actionMysqlAdd, actionMysql），需預先於資料庫建立 users 資料表。Yii 建議使用「遷移」功能管理資料表結構。

用 Gii 工具創建遷移檔：打開終端，切換至專案根目錄 /Applications/ServBay/www/servbay-yii2-app，執行 Yii 命令建立遷移檔。
bash
```
php yii migrate/create create_users_table
```
1
系統會提示確認，輸入 yes 並 Enter。系統會於 migrations 目錄建立新遷移 PHP 檔名如 mYYYYMMDD_HHMMSS_create_users_table.php。

編輯遷移檔：開啟剛創建的檔案，於 up() 定義 users 資料表結構。

php

<?php

use yii\db\Migration;

/**
 * Handles the creation of table `{{%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 換為實際檔案名稱。

執行遷移：確保在專案跟目錄下，用終端執行：
bash
```
php yii migrate
```
1
系統會提示確認，輸入 yes 執行。完成後，即會建立好資料表。

訪問網站並測試

至此，您可於瀏覽器中訪問設定的網域 https://servbay-yii2-test.local。

訪問 https://servbay-yii2-test.local：應可見到 Yii 2 歡迎頁，並有我們於 views/site/index.php 加入的測試連結。
點擊 "Test Memcached" 或訪問 https://servbay-yii2-test.local/index.php?r=site/memcached：若 Memcached 設定及服務正常，即會看到 "Memcached set successfully..." 等訊息。
點擊 "Test Redis" 或訪問 https://servbay-yii2-test.local/index.php?r=site/redis：Redis 正常即會見 "Redis set successfully..." 的訊息。
點擊 "Add a user to DB" 或訪問 https://servbay-yii2-test.local/index.php?r=site/mysql-add：資料庫與 users 表正常即會見 "User added successfully..."，每次點擊會新增一筆用戶（email 為唯一時則不會重複）。
點擊 "Fetch users from DB" 或訪問 https://servbay-yii2-test.local/index.php?r=site/mysql：若資料庫正常並有 users 表，會顯示目前所有用戶。

遇有問題請檢查 ServBay 相關服務（PHP、Web 伺服器、資料庫、Memcached、Redis）是否啟動，確認專案設定（config/db.php, config/web.php）及資料表已正確建立。

常見問答（FAQ）

為何訪問域名時顯示「無法開啟此網站」或憑證錯誤？ 請確認已於 ServBay「網站」設定新增域名，且 ServBay 應用本身有運作。ServBay 會自動設定本機 DNS 與 SSL 憑證。如憑證有問題，請確認已信任 ServBay User CA 或 Public CA，詳情見官方文件。
Composer 指令無法執行？ 請確認已於 ServBay 介面啟用 Composer，且於 macOS 終端下執行命令。ServBay 會自動將 Composer 加入 PATH。
資料庫連線失敗？ 請確認 MySQL/PostgreSQL 服務是否運行。檢查 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 上建構一套功能齊全的本機開發環境，順利執行 Yii 2 專案。ServBay 內建 Composer、PHP 版本管理、多元資料庫與快取服務、方便的網站配置等，大幅簡化開發流程。按本指南操作，您將能迅速展開 Yii 2 開發並善用 ServBay 強大工具提升開發效率。

祝您開發順利！

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

概述：什麼是 Yii 2？ ​

Yii 2 的主要特色與優勢 ​

使用 ServBay 運行 Yii 2 專案 ​

前置準備 ​

建立 Yii 2 專案 ​

初始化設定 ​

設定 Web 伺服器 (ServBay 網站) ​

新增示範程式碼以演示功能 ​

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

訪問網站並測試 ​

常見問答（FAQ） ​

總結 ​