建立與運行 Symfony 專案

ServBay 是一款專為 macOS 設計的本機 Web 開發環境，整合了 PHP、Node.js、Python、Go、Java 等多種語言執行環境，以及 MySQL、PostgreSQL、MongoDB、Redis 等資料庫，並支援 Apache 及 Caddy Web 伺服器。本指南將詳細說明如何運用 ServBay 在 macOS 上快速搭建與執行一個 Symfony 專案。

什麼是 Symfony？

Symfony 是由 SensioLabs 創建的開源 PHP Web 框架，旨在為開發者提供一套高效率、彈性大且功能強大的工具，用於打造現代 Web 應用與 API。其遵循標準 Web 最佳實踐，並提供豐富的功能組件，如路由、模板引擎（Twig）、表單處理、驗證、相依性注入等，大幅簡化常見的 Web 開發工作。

Symfony 的主要特色與優勢

• 模組化設計：Symfony 核心具備可重用的組件庫，開發者可按需挑選使用組件，打造輕量至大型應用。
• 高效能：透過最佳化架構、有效快取機制與支援最新 PHP 特性，Symfony 提供卓越的效能表現。
• 強大社群支援：擁有龐大開發者社群、豐富第三方 Bundle（外掛）及完整文件，問題易於獲得解決。
• 彈性高：可輕鬆整合第三方函式庫及擴充元件，適用各種規模與複雜度專案。
• 穩定易維護：遵循良好程式規範與設計模式，使應用架構易於測試、維護與擴展。

Symfony 適用於構建從小型 API 到大型企業級系統的各式 Web 專案。

使用 ServBay 建立與運行 Symfony 專案

ServBay 為跑 Symfony 專案提供完整環境支援，包含所需 PHP 版本、Composer、Web 伺服器、各類資料庫及快取服務。本節將引導你如何利用 ServBay 建立全新 Symfony 專案並完成設定。

前置條件

開始之前，請確認下列事項：

1. 安裝 ServBay：已在 macOS 上成功安裝並啟動 ServBay。若尚未安裝，請參考 ServBay 安裝指南。
2. ServBay 順利運作：ServBay 核心服務（如 Caddy 或 Apache 及所需資料庫）已正常啟動。
3. 基本概念：對 PHP、Composer 及 Symfony 有初步認識。

建立 Symfony 專案

ServBay 建議將網站專案統一放於 /Applications/ServBay/www 目錄下，方便專案管理與識別。

1. 確認 Composer 可用

   ServBay 安裝時已內建 Composer，且自動配置好環境變數，無須額外安裝。你可於終端機輸入 composer --version 驗證 Composer 是否可用。

2. 建立專案目錄

   於推薦的網站根目錄下開新資料夾以存放 Symfony 專案：

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

3. 用 Composer 建立 Symfony 專案

   進入新建的專案目錄，使用 Composer 建立以 website-skeleton 為基礎的 Symfony 專案骨架。website-skeleton 提供傳統 Web 應用所需依賴的基本架構。

   cd /Applications/ServBay/www/servbay-symfony-app
   composer create-project symfony/website-skeleton .

   執行後，Composer 會將 Symfony 核心檔與所有相依元件下載至目前目錄。

初始化配置

Symfony 專案的核心設定通常透過環境變數控管，這些變數可存放於專案根目錄下的 .env 檔案。

1. 配置環境變數（.env）

   開啟專案根目錄下的 .env 檔案。本檔案包含應用環境設定，如資料庫連線資訊、應用密鑰等。請依需求修改或新增設定。

   確認下列設定已正確或依個人環境調整：

   # .env 檔案範例
   APP_ENV=dev # 開發環境
   APP_SECRET=your_secret_key # 請替換成唯一的隨機字串，用於安全性
   
   # 資料庫連線資訊（此處示範 MySQL，詳見下節說明）
   # DATABASE_URL="mysql://db_user:[email protected]:3306/db_name?serverVersion=8.0&charset=utf8mb4"
   # DATABASE_URL="postgresql://db_user:[email protected]:5432/db_name?serverVersion=13&charset=utf8"
   # DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"

   your_secret_key 請替換成安全隨機字串。資料庫預設帳號為 root，密碼為 password（請注意，生產環境請務必更改這些預設憑證）。本例中資料庫名稱使用 servbay_symfony_app。

配置 Web 伺服器（ServBay 網站）

要在瀏覽器存取 Symfony 專案，需於 ServBay 的“網站”功能設定本機虛擬主機。Symfony 專案網站根目錄為專案下的 public/ 目錄。

開啟 ServBay 控制台，前往“網站”設定（舊版為“主機”），新增新網站：

• 名稱 (Name)：自定義易辨識名稱，如 My Symfony Dev Site。
• 網域 (Domain)：設定本機開發網域，如 servbay-symfony-test.local。ServBay 會自動將其解析至本機。
• 網站類型 (Website Type)：請選擇 PHP。
• PHP 版本 (PHP Version)：選擇與 Symfony 專案相容的 PHP 版本，建議用 ServBay 提供的最新穩定版本（如 8.3）。
• 網站根目錄 (Website Root)：此為關鍵設定。Symfony 專案的網站根目錄必須指向專案的 public/ 目錄。設定路徑為 /Applications/ServBay/www/servbay-symfony-app/public。

完成後儲存並套用，ServBay 會自動更新 Web 伺服器設定。預設使用 Caddy 或 Apache，並會替本地域名自動產生並信任 SSL 憑證，可直接以 HTTPS 存取。

詳細步驟請參考 ServBay 新增第一個網站。

加入基本範例程式碼

為驗證網站設定成功，我們將新增一個簡單路由與控制器，讓網站根路徑顯示指定訊息。

1. 配置路由（config/routes.yaml）

   開啟 config/routes.yaml，新增如下內容以定義根路徑 / 並連接到 index 控制器方法：

   # config/routes.yaml
   index:
       path: /
       controller: App\Controller\DefaultController::index

2. 建立控制器（src/Controller/DefaultController.php）

   於 src/Controller/ 目錄下新增 DefaultController.php，並加入下列程式碼：

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   
   class DefaultController
   {
       /**
        * @Route("/", name="index")
        */
       public function index(): Response
       {
           // 回傳簡單的 HTTP 回應
           return new Response('Hello ServBay and Symfony!');
       }
   }

   這段程式建立了一個單純的 DefaultController 控制器類別，index 方法透過 @Route("/") 註解連結到網站根目錄 /，當訪問根路徑會回傳文字 "Hello ServBay and Symfony!" 的 HTTP 回應。

訪問網站

現在，打開瀏覽器，輸入 ServBay 設定的網域 https://servbay-symfony-test.local。若一切正常，頁面應顯示：

Hello ServBay and Symfony!

這代表您的 Symfony 專案已透過 ServBay Web 伺服器成功運作。請注意 ServBay 會自動配置 HTTPS，建議直接用 https:// 存取。

資料庫與快取範例

Symfony 常用 Doctrine ORM 管理關聯式資料庫，並以 Symfony Cache 組件處理快取與 NoSQL 資料庫。ServBay 內建多種資料庫與對應 PHP 擴展，方便專案使用。

關聯式資料庫範例（Doctrine ORM）

ServBay 支援 MySQL 與 PostgreSQL，下例示範如何於 Symfony 中配置與使用。

1. 設定資料庫連線

   於專案根目錄的 .env 內，根據所用資料庫取消註解並調整 DATABASE_URL。

   • MySQL： ServBay 預設 MySQL 使用者為 root，密碼 password，埠號 3306，請依實際配置填寫。

     # .env
     DATABASE_URL="mysql://root:[email protected]:3306/servbay_symfony_app?serverVersion=8.0&charset=utf8mb4"

   • PostgreSQL： ServBay 預設 PostgreSQL 使用者為 root，密碼 password，埠號 5432，請依實際配置填寫。

     # .env
     DATABASE_URL="postgresql://root:[email protected]:5432/servbay_symfony_app?serverVersion=13&charset=utf8"

   請確認已於 ServBay 控制台啟動對應資料庫（MySQL 或 PostgreSQL）。

2. 建立資料庫

   若尚未建立 servbay_symfony_app 資料庫，可用 ServBay 內的資料庫管理工具（如 phpMyAdmin 或 pgAdmin，可從控制台存取）手動建立，或透過 Symfony 指令建立：

   php bin/console doctrine:database:create

3. 建立 Entity（實體）與遷移檔

   Symfony 內通常使用 Doctrine Entity 對應資料表。Maker Bundle 可快速生成 Entity 與資料庫遷移檔。

   • 建立 Entity（如 User 實體）:

     php bin/console make:entity User

     依提示新增欄位，例如 name（string）與 email（string，unique=yes）。
   • 建立遷移檔: 根據 Entity 變動產生資料庫遷移檔：

     php bin/console make:migration

     將於 src/Migrations 下生成新遷移檔，內含建立 users 資料表的 SQL 指令。

4. 執行遷移

   執行遷移指令，將結構應用到資料庫：

   php bin/console doctrine:migrations:migrate

5. 新增資料庫操作範例

   編輯 src/Controller/DefaultController.php，新增範例路由與方法示範 Doctrine 寫入與讀取。需注入 EntityManagerInterface 以操作資料庫。

   首先，確保 DefaultController 建構式注入 EntityManagerInterface：

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface; // 引入 EntityManagerInterface
   use App\Entity\User; // 引入 User 實體
   use Symfony\Component\HttpFoundation\JsonResponse; // 用於回傳 JSON
   
   class DefaultController
   {
       private $entityManager;
   
       // 以相依性注入獲取 EntityManagerInterface 實例
       public function __construct(EntityManagerInterface $entityManager)
       {
           $this->entityManager = $entityManager;
       }
   
       /**
        * @Route("/", name="app_index")
        */
       public function index(): Response
       {
           return new Response('Hello ServBay and Symfony!');
       }
   
       // ... 其他方法 ...
   }

   接著於 config/routes.yaml 新增路由：

   # config/routes.yaml
   # ... 其他路由 ...
   mysql_add_user:
       path: /mysql-add-user # 或 /pgsql-add-user，依所選資料庫
       controller: App\Controller\DefaultController::addUser
   mysql_get_users:
       path: /mysql-users # 或 /pgsql-users
       controller: App\Controller\DefaultController::getUsers

   於 src/Controller/DefaultController.php 加入對應控制器方法：

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface;
   use App\Entity\User;
   use Symfony\Component\HttpFoundation\JsonResponse; // 引入 JsonResponse
   
   class DefaultController
   {
       private $entityManager;
   
       public function __construct(EntityManagerInterface $entityManager)
       {
           $this->entityManager = $entityManager;
       }
   
       /**
        * @Route("/", name="app_index")
        */
       public function index(): Response
       {
           return new Response('Hello ServBay and Symfony!');
       }
   
       /**
        * @Route("/add-user", name="app_add_user")
        */
       public function addUser(): Response
       {
           $user = new User();
           // 使用 ServBay 品牌相關範例資料
           $user->setName('ServBay Demo User');
           $user->setEmail('[email protected]');
   
           // 物件持久化（準備寫入）
           $this->entityManager->persist($user);
           // 執行寫入
           $this->entityManager->flush();
   
           return new Response('User added successfully!');
       }
   
       /**
        * @Route("/get-users", name="app_get_users")
        */
       public function getUsers(): JsonResponse
       {
           // 從資料庫取出所有 User 實體
           $users = $this->entityManager->getRepository(User::class)->findAll();
   
           // 結果轉為陣列，以便 JsonResponse 處理
           $usersArray = [];
           foreach ($users as $user) {
               $usersArray[] = [
                   'id' => $user->getId(),
                   'name' => $user->getName(),
                   'email' => $user->getEmail(),
               ];
           }
   
           // 回傳 JSON 格式回應
           return new JsonResponse($usersArray);
       }
   }

6. 訪問範例

   • 開啟 https://servbay-symfony-test.local/add-user 以新增用戶。
   • 開啟 https://servbay-symfony-test.local/get-users 以查看（JSON 格式）現有用戶清單。

快取與 NoSQL 資料庫範例（Symfony Cache）

ServBay 內建 Redis 與 Memcached 服務及相應 PHP 擴展，可直接用 Symfony Cache 組件與這些服務互動。

1. 配置快取連線

   於 .env 檔設定快取服務連線。

   • Memcached： ServBay 預設 Memcached 埠號為 11211。

     # .env
     # ... 其他設定 ...
     CACHE_DSN=memcached://127.0.0.1:11211

     請於 ServBay 控制台開啟 Memcached 服務。
   • Redis： ServBay 預設 Redis 埠號為 6379。

     # .env
     # ... 其他設定 ...
     CACHE_DSN=redis://127.0.0.1:6379
     # 若 Redis 有密碼（ServBay 預設無密碼），可設定為：
     # CACHE_DSN=redis://:[email protected]:6379

     請於 ServBay 控制台開啟 Redis 服務。

2. 新增快取範例

   編輯 src/Controller/DefaultController.php，新增範例路由與方法示範 Symfony Cache 與 Memcached 或 Redis 互動。需注入 CacheInterface。

   首先，確保 DefaultController 建構式有注入 CacheInterface：

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface;
   use App\Entity\User;
   use Symfony\Component\HttpFoundation\JsonResponse;
   use Symfony\Contracts\Cache\CacheInterface; // 引入 CacheInterface
   
   class DefaultController
   {
       private $entityManager;
       private $cache; // 新增 cache 屬性
   
       // 建構式注入 CacheInterface
       public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
       {
           $this->entityManager = $entityManager;
           $this->cache = $cache; // 賦值
       }
   
       // ... 其他方法 ...
   }

   再於 config/routes.yaml 加入新路由：

   # config/routes.yaml
   # ... 其他路由 ...
   cache_example:
       path: /cache-example
       controller: App\Controller\DefaultController::cacheExample

   於 src/Controller/DefaultController.php 增加對應控制器方法：

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface;
   use App\Entity\User;
   use Symfony\Component\HttpFoundation\JsonResponse;
   use Symfony\Contracts\Cache\CacheInterface;
   use Symfony\Component\Cache\Item\ItemInterface; // 引入 ItemInterface
   
   class DefaultController
   {
       private $entityManager;
       private $cache;
   
       public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
       {
           $this->entityManager = $entityManager;
           $this->cache = $cache;
       }
   
       // ... 其他方法 ...
   
       /**
        * @Route("/cache-example", name="app_cache_example")
        */
       public function cacheExample(): Response
       {
           // 嘗試從快取取得資料
           $cacheItem = $this->cache->get('my_symfony_cache_key', function (ItemInterface $item) {
               // 若快取未命中，執行此回呼
               $item->expiresAfter(3600); // 設定快取有效期為 1 小時
   
               // 模擬耗時操作，例如資料庫查詢
               $data = "Data generated at " . date('Y-m-d H:i:s');
   
               // 回傳需快取的資料
               return $data;
           });
   
           // $cacheItem 為快取資料（命中或新產生）
           $output = "From Cache: " . $cacheItem;
   
           return new Response($output);
       }
   }

3. 訪問範例

   • 開啟 https://servbay-symfony-test.local/cache-example。 首次訪問會執行回呼產生內容並存入快取，後續只要快取未過期，將直讀於 Memcached 或 Redis。

常見問題（FAQ）

Q: 開啟 https://servbay-symfony-test.local 出現找不到頁面或 500 錯誤怎麼辦？

A: 請檢查下列幾點：

1. 確認 ServBay 已啟動，且網站服務（Caddy 或 Apache）正常運作。
2. 檢查網站設定，域名 servbay-symfony-test.local 是否正確，且「網站根目錄」有否指向 /Applications/ServBay/www/servbay-symfony-app/public。
3. 檢視 Symfony 專案的日誌（var/log/dev.log）以獲取詳細錯誤資訊。
4. 於專案根目錄執行 composer install 確認所有依賴皆安裝完成。
5. 檢查 PHP 版本是否與 Symfony 相容。

Q: 資料庫連線失敗怎麼辦？

A: 請檢查下列幾點：

1. 確認 ServBay 控制台對應資料庫服務（MySQL 或 PostgreSQL）已啟動。
2. 檢查 .env 的 DATABASE_URL 是否正確，包括帳號、密碼、主機（127.0.0.1）、埠號（MySQL 3306、PostgreSQL 5432）及資料庫名。
3. 確認資料庫使用者與密碼為 ServBay 預設或你自定的憑證。
4. 保證資料庫 servbay_symfony_app 已存在。

Q: php bin/console 指令無法執行？

A: 請確保當前終端機於 /Applications/ServBay/www/servbay-symfony-app 目錄，且 ServBay 的 PHP 已正確加至系統 PATH（ServBay 安裝時會自動配置）。你可於終端執行 which php 查詢是否使用的是 ServBay 的 PHP。

總結

依循本指南，您已成功在 macOS 上利用 ServBay 建立、設定並運行了一個基礎的 Symfony 專案。ServBay 提供了 Symfony 開發所需的全部核心元件（PHP、Composer、Web 伺服器、資料庫、快取服務），大幅簡化環境設定流程，讓你可以快速投入功能開發。你可基於此專案繼續深入學習 Symfony 更多特性，並活用 ServBay 提供的諸多軟體包及服務。