萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

高性能 PHP 框架 Symfony 2 入門教學:從安裝到第一個控制器

前言

Symfony 2 (2011 發布) 確立了現代 PHP 框架標準:Bundle 架構、依賴注入容器、事件分發器、Doctrine ORM、Twig 模板、Routing、表單、驗證、安全、快取。雖 Symfony 2 已結束維護 (EOL 2017),但其核心概念完整繼承至 Symfony 6/7 LTS。本教學以 Symfony 2 為例,展示標準化專案結構與開發流程,助你快速上手現代 Symfony 開發。

一、環境需求與安裝

系統需求

  • PHP ≥ 5.3.9 (Symfony 2.8 LTS 需 PHP 5.3.9+,建議 PHP 7.4+ 配合 Symfony 4/5/6)
  • Composer 依賴管理器
  • Web Server: Nginx + PHP-FPM 或 Apache + mod_php
  • 資料庫: MySQL/PostgreSQL/SQLite
  • 擴展: intl, pdo_mysql, xml, mbstring, opcache

建立專案 (Composer)

# 建議使用 Symfony 6/7 LTS 版本 (本教學以 6.4 LTS 為例)
composer create-project symfony/skeleton my_project "6.4.*"
cd my_project

# 安裝常用套件包
composer require webapp  # 包含: framework, twig, orm, validator, security, form, maker-bundle (dev)
# 或手動挑選
composer require doctrine/orm symfony/twig-bundle symfony/validator symfony/security-bundle symfony/form symfony/maker-bundle --dev

目錄結構解析 (Symfony 4/5/6/7 Flex 結構)


my_project/
├── bin/                    # 執行腳本 (console)
├── config/                 # 設定檔 (packages/, routes/, services.yaml)
│   ├── packages/           # 各 Bundle 設定
│   ├── routes/             # 路由設定
│   └── services.yaml       # 服務容器定義 (核心)
├── public/                 # Web 根目錄 (DocumentRoot)
│   └── index.php           # 前端控制器 (唯一入口)
├── src/                    # 應用程式核心代碼
│   ├── Controller/         # 控制器
│   ├── Entity/             # Doctrine 實體
│   ├── Repository/         # 資料存取
│   ├── Service/            # 業務邏輯服務
│   ├── Form/               # 表單類別
│   └── Kernel.php          # 應用核心
├── templates/              # Twig 模板
├── translations/           # 翻譯檔
├── var/                    # 快取、日誌、暫存 (不可提交 Git)
│   ├── cache/
│   └── log/
├── vendor/                 # Composer 依賴 (不可提交 Git)
├── .env                    # 環境變數 (不可提交 Git,提交 .env.example)
├── .env.local              # 本機覆蓋 (gitignore)
├── composer.json
└── symfony.lock

二、核心概念速覽

1. Bundle (包/模組)

功能模組化單位,包含控制器、實體、服務、模板、路由、設定。src/Kernel.php 註冊啟用的 Bundle。現代 Symfony 推薦 單一 AppBundle (或直接 src/) + 第三方 Bundle。

2. 依賴注入容器

服務定義於 config/services.yaml:

# config/services.yaml
services:
  _defaults:
    autowire: true      # 自動注入型別提示的依賴
    autoconfigure: true # 自動套用標籤 (如 Controller, EventSubscriber)
    bind:
      $defaultLocale: '%locale%'
  
  App\:
    resource: '../src/'
    exclude: '../src/{DependencyInjection,Entity,Tests,Kernel.php}'
  
  # 手動定義服務
  App\Service\PaymentGateway:
    arguments:
      $apiKey: '%env(PAYMENT_API_KEY)%'
      $logger: '@monolog.logger.payment'

3. 路由

支援 YAML、XML、PHP、Annotation/Attribute (PHP 8+ 推薦 Attribute):

<?php
// src/Controller/ArticleController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ArticleController extends AbstractController {
  #[Route('/article/{id<\d+>}', name: 'app_article_show', methods: ['GET'])]
  public function show(int $id): Response {
    $article = $this->getDoctrine()->getRepository(Article::class)->find($id);
    if (!$article) {
      throw $this->createNotFoundException('文章不存在');
    }
    return $this->render('article/show.html.twig', ['article' => $article]);
  }
  
  #[Route('/article/create', name: 'app_article_create', methods: ['GET', 'POST'])]
  public function create(Request $request, EntityManagerInterface $em): Response {
    $article = new Article();
    $form = $this->createForm(ArticleType::class, $article);
    $form->handleRequest($request);
    
    if ($form->isSubmitted() && $form->isValid()) {
      $em->persist($article);
      $em->flush();
      $this->addFlash('success', '文章發布成功');
      return $this->redirectToRoute('app_article_show', ['id' => $article->getId()]);
    }
    
    return $this->render('article/create.html.twig', ['form' => $form->createView()]);
  }
}

4. Doctrine ORM 實體

<?php
// src/Entity/Article.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity(repositoryClass: ArticleRepository::class)]
#[ORM\Table(name: 'articles')]
class Article {
  #[ORM\Id, ORM\GeneratedValue, ORM\Column(type: 'integer')]
  private ?int $id = null;
  
  #[ORM\Column(type: 'string', length: 255)]
  #[Assert\NotBlank, Assert\Length(max: 255)]
  private string $title = '';
  
  #[ORM\Column(type: 'text')]
  #[Assert\NotBlank]
  private string $content = '';
  
  #[ORM\Column(type: 'datetime_immutable')]
  private \DateTimeImmutable $createdAt;
  
  // Getter/Setter (可用 maker:entity 自動生成)
  public function getId(): ?int { return $this->id; }
  public function getTitle(): string { return $this->title; }
  public function setTitle(string $title): self { $this->title = $title; return $this; }
  // ...
}

5. Twig 模板

{# templates/article/show.html.twig #}
{% extends 'base.html.twig' %}

{% block title %}{{ article.title }}{% endblock %}

{% block body %}
  

{{ article.title }}

{{ article.content|raw }}
返回列表 {% endblock %}

三、開發工作流

  1. 建立實體:php bin/console make:entity Article
  2. 生成遷移:php bin/console make:migration → php bin/console doctrine:migrations:migrate
  3. 建立 CRUD:php bin/console make:crud Article (自動生成 Controller、Form、Repository、模板)
  4. 開發伺服器:symfony server:start -d (需安裝 Symfony CLI) 或 php -S 127.0.0.1:8000 -t public
  5. 測試:php bin/console phpunit (PHPUnit + Symfony Test Pack)
  6. 程式碼風格:php-cs-fixer fix (配合 .php-cs-fixer.php)
  7. 靜態分析:phpstan analyse src --level=8

四、部署檢查清單

  • APP_ENV=prod APP_DEBUG=0 在 .env.local 或伺服器環境變數
  • composer install --no-dev --optimize-autoloader --classmap-authoritative
  • php bin/console cache:clear --env=prod
  • php bin/console assets:install public
  • 設定 Nginx/Apache DocumentRoot 指向 public/
  • 配置 OPcache、Redis Session、資料庫連線池
  • 啟用 opcache.preload (PHP 7.4+)
  • 健康檢查端點:#[Route('/health')] 回傳 200 OK

五、學習資源

  • 官方文檔:symfony.com/doc (極詳盡、版本化、中文翻譯社群活躍)
  • SymfonyCasts:付費影片教學,品質極高
  • 最佳實踐:Symfony Best Practices
  • 元件獨立使用:每個 Component (HttpFoundation, Routing, DependencyInjection, Validator...) 可獨立於框架外使用

結語

Symfony 以「企業級、標準化、長期支援」著稱。掌握其 服務容器、依賴注入、事件驅動、Doctrine ORM、Twig、表單/驗證/安全元件 核心抽象,不僅能高效開發 Symfony 應用,更能深刻理解現代 PHP 架構設計哲學。從今天開始,用 composer create-project symfony/skeleton 建立你的第一個專案,體驗「標準化帶來的自由」。

copyright © 萬盛學電腦網 all rights reserved