Symfony 2 入門實戰教程：從安裝到第一個 Bundle 完整指南

Symfony 2 作為企業級 PHP 框架標桿，擁有嚴謹的架構設計與豐富的生態系統。本教程基於 Symfony 2.0（歷史版本），記錄在 Ubuntu 環境下的完整安裝、配置、建立 Bundle、路由、控制器、模板全流程，適合初次接觸 Symfony 的開發者建立整體認知。

環境準備與安裝

1. 下載與解壓

# 下載 Standard Edition (含 vendors)
wget https://symfony.com/download?v=Symfony_Standard_Vendors_2.0.BETA5.tgz

# 解壓至 Web 根目錄
tar zxvf Symfony_Standard_Vendors_2.0.BETA5.tgz -C /var/www

2. 目錄結構概覽

/var/www/Symfony/
├── app/                 # 核心配置目錄
│   ├── cache/           # 快取檔案
│   ├── config/          # 全域配置
│   ├── logs/            # 日誌
│   ├── autoload.php     # 自動載入註冊
│   └── AppKernel.php    # 核心 Kernel，註冊 Bundle
├── src/                 # 應用程式源碼（自建 Bundle 放這裡）
├── vendor/              # 第三方庫
└── web/                 # Web 公開入口
    ├── app.php          # 生產環境前端控制器
    └── app_dev.php      # 開發環境前端控制器

3. 權限配置（關鍵步驟）

app/cache 和 app/logs 需同時被 Web 伺服器使用者（如 www-data）與目前使用者可讀寫：

# 清空舊快取
rm -rf app/cache/* app/logs/*

# 設定 ACL（需掛載支援 acl 的檔案系統）
sudo setfacl -R -m u:www-data:rwx -m u:$(whoami):rwx app/cache app/logs
sudo setfacl -dR -m u:www-data:rwx -m u:$(whoami):rwx app/cache app/logs

若系統不支援 setfacl，需安裝 acl 套件並確認 /etc/fstab 掛載選項含 acl。

Web 配置精靈

瀏覽器訪問 https://localhost/Symfony/web/config.php，按提示填寫資料庫連線資訊（PDO MySQL）、郵件設定、Locale、Secret 等。完成後會自動生成 app/config/parameters.ini：

[parameters]
database_driver="pdo_mysql"
database_host="localhost"
database_name="symfony"
database_user="symfony"
database_password="symfony"
mailer_transport="smtp"
mailer_host="localhost"
locale="zh_CN"
secret="29f96e9e70c2797cb77dd088d3954d3c38d9b33f"

驗證安裝

訪問 https://localhost/Symfony/web/app_dev.php，若出現 Symfony 歡迎頁，代表安裝成功。

建立第一個 Bundle：AcmeHelloBundle

1. 產生 Bundle 骨架

php app/console gen:bundle "AcmeHelloBundle" src

交互式提示中選擇：YAML 配置、生成完整目錄結構。

2. 註冊命名空間自動載入

編輯 app/autoload.php：

$loader->registerNamespaces(array(
    // ...
    'Acme' => __DIR__.'/../src',
    // ...
));

3. 註冊 Bundle 到 Kernel

編輯 app/AppKernel.php：

public function registerBundles() {
    $bundles = array(
        // ...
        new Acme\HelloBundle\AcmeHelloBundle(),
    );
    return $bundles;
}

路由配置：分層管理

1. 全域路由引用 Bundle 路由

app/config/routing.yml：

homepage:
    pattern:  /
    defaults: { _controller: FrameworkBundle:Default:index }

hello:
    resource: "@AcmeHelloBundle/Resources/config/routing.yml"

2. Bundle 內部路由定義

src/Acme/HelloBundle/Resources/config/routing.yml：

hello:
    pattern:  /hello/{name}
    defaults: { _controller: AcmeHelloBundle:Hello:index, name: 'pu' }

_controller 格式：Bundle名:控制器名:動作名，對應 HelloController::indexAction()。

控制器與模板

1. 控制器

src/Acme/HelloBundle/Controller/HelloController.php：

namespace Acme\HelloBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;

class HelloController extends Controller {
    public function indexAction($name) {
        // 直接回傳 Response（簡易模式）
        // return new Response('Hello '.$name.'!');
        
        // 使用模板引擎（推薦）
        return $this->render('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));
    }
}

2. 全域佈局模板

app/Resources/views/layout.html.twig：

{# app/Resources/views/layout.html.twig #}



    
    


    {% block body %}{% endblock %}

3. 頁面專用模板

src/Acme/HelloBundle/Resources/views/Hello/index.html.twig：

{# src/Acme/HelloBundle/Resources/views/Hello/index.html.twig #}
{% extends '::layout.html.twig' %}
{% block body %}
    Hello {{ name }}!
{% endblock %}

模板繼承機制：子模板覆寫父模板的 block，實現佈局復用。

驗證成果

瀏覽器訪問 https://localhost/Symfony/web/app_dev.php/hello/World，頁面顯示「Hello World!」。

核心概念總結

後續學習路徑建議

1. 深入 Twig 模板語法（繼承、宏、過濾器、表單主題）
2. 掌握 Doctrine ORM（實體、Repository、遷移、關聯映射）
3. 理解 服務容器與依賴注入（services.yml、參數、編譯器通過）
4. 學習 表單組件（建立、驗證、CSRF、主題客製化）
5. 探索 安全組件（防火牆、認證授權、Voters、OAuth）
6. 實作 API Platform 或 FOSRestBundle 建構 RESTful API
7. 部屬優化：生產環境配置（快取預熱、資產安裝、Assetic、CDN）

Symfony 學習曲線較陡，但其嚴謹的架構與最佳實踐能幫你建立可維護、可擴展的企業級應用。建議從官方文件 The Book 系統性學習，並多動手實作。