Agavi MVC 框架入門 (一)：核心理念、安裝與第一個 Action

為什麼選擇 Agavi？

• 嚴格 MVC 分離：Action (Controller)、View (模板)、Model (領域模型) 職責極清晰，適合大型團隊長期維護。
• 零配置慣例：目錄結構固定，類別命名對應路由，減少 XML/YAML 設定。
• 內建驗證、快取、I18N、安全 (CSRF/XSS/輸出過濾)，開箱即用。
• 輸出類型多態：同一 Action 可輸出 HTML、JSON、XML、RSS、SOAP，只需切換 View 類別。
• 命令列工具鏈：`agavi` 指令快速產生骨架、模組、Action、驗證器、模型。

適合：**企業級專案、API 服務、多輸出格式需求、重視架構規範的團隊**。

安裝 (Composer)

composer create-project agavi/agavi myproject "~1.0"
cd myproject
# 產生專案骨架
./bin/agavi project-create

目錄結構：

myproject/
├── app/                    # 應用程式核心
│   ├── config/             # 路由、資料庫、驗證、快取等設定
│   ├── modules/            # 模組 (Default, Admin, Api...)
│   │   └── Default/
│   │       ├── actions/    # Action 類別
│   │       ├── views/      # View 類別 + 模板
│   │       ├── templates/  # .php 模板檔
│   │       └── config/     # 模組級路由、驗證
│   ├── lib/                # 共用類別、Model、Service
│   └── templates/          # 全域母版頁
├── pub/                    # 公開資產 (CSS, JS, 圖片)
├── bin/agavi               # CLI 工具
└── vendor/

建立第一個 Action + View

# 互動式產生
./bin/agavi action-wizard
# Module name: Default
# Action name: Hello
# Views: Success

產生檔案：

• `app/modules/Default/actions/HelloAction.class.php`
• `app/modules/Default/views/HelloSuccessView.class.php`
• `app/modules/Default/templates/HelloSuccess.php`

Action 類別

<?php
// app/modules/Default/actions/HelloAction.class.php
class Default_HelloAction extends AgaviAction
{
    public function execute(AgaviRequestDataHolder $rd)
    {
        // 1. 取得輸入 (GET/POST/COOKIE/FILES)
        $name = $rd->getParameter('name', 'World');

        // 2. 業務邏輯 (通常委派給 Model/Service)
        $greeting = "Hello, {$name}! Welcome to Agavi.";

        // 3. 設定輸出資料給 View
        $this->setAttribute('greeting', $greeting);
        $this->setAttribute('currentTime', date('Y-m-d H:i:s'));

        return 'Success'; // 對應 HelloSuccessView
    }

    // 可選：輸入驗證
    public function validate(AgaviValidator $validator)
    {
        $validator->addRule('name', new AgaviStringValidator(['max_length' => 50]));
    }
}

View 類別

<?php
// app/modules/Default/views/HelloSuccessView.class.php
class Default_HelloSuccessView extends AgaviHtmlView
{
    public function setupHtml()
    {
        // 設定母版頁 (預設 app/templates/Master.php)
        $this->setLayout('Master');
    }
}

模板 (PHP 原生語法)

<?php // app/modules/Default/templates/HelloSuccess.php ?>
<h1><?= $t->get('greeting') ?></h1>
<p>Current time: <?= $t->get('currentTime') ?></p>
<p><a href="<?= $ro->gen('default.index') ?>">Back to Home</a></p>

路由設定 (app/config/routing.xml)

<?xml version="1.0" encoding="UTF-8"?>
<ae:configurations xmlns:ae="https://agavi.org/agavi/config/global/envelope/1.0"
                   xmlns="https://agavi.org/agavi/config/parts/routing/1.0">
  <ae:configuration>
    <routes>
      <route name="default.index" pattern="^/$" module="Default" action="Index" />
      <route name="default.hello" pattern="^/hello(?:/(?P[^/]+))?$" module="Default" action="Hello" />
    </routes>
  </ae:configuration>
</ae:configurations>

• `pattern` 使用 **PCRE 正則**，命名捕獲組 `(?P...)` 自動對應 `$rd->getParameter('name')`。
• 路由名稱 `default.hello` 供 `$ro->gen('default.hello', ['name' => 'Agavi'])` 產生 URL。

啟動測試

# 內建開發伺服器 (需 PHP 5.4+)
cd myproject
php -S localhost:8000 -t pub
# 訪問 https://localhost:8000/hello/Agavi

下一步預告

下一篇將介紹：**表單處理、輸入驗證器、資料庫整合 (Doctrine/Propel)、錯誤處理與自訂輸出類型 (JSON/XML/RSS)**。