建立並運行 Symfony 專案

ServBay 是專為 macOS 與 Windows 設計的本地 Web 開發環境，整合了 PHP、Node.js、Python、Go、Java 等多種語言執行環境，以及 MySQL、PostgreSQL、MongoDB、Redis 等資料庫，並支援 Apache 及 Caddy Web 伺服器。本指南將詳盡介紹如何利用 ServBay 在 macOS 與 Windows 上快速搭建並運行 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 檔案。該檔包含應用程式的環境設定，例如資料庫連線資訊、應用密鑰等。依需求修改或新增設定項目。

   請確保以下設定正確，並根據您的 ServBay 環境調整：

   # .env 檔案範例
   APP_ENV=dev # 開發環境
   APP_SECRET=your_secret_key # 請改成唯一隨機字串（安全用）
   
   # 資料庫連線資訊（範例為 MySQL，後續詳細說明）
   # DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=8.0&charset=utf8mb4"
   # DATABASE_URL="postgresql://db_user:db_password@127.0.0.1:5432/db_name?serverVersion=13&charset=utf8"
   # DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"

   請將 your_secret_key 換成安全隨機字串。資料庫連線部分，ServBay 預設用戶為 root，密碼為 password（生產環境務必更改預設憑證）。本文以 servbay_symfony_app 為範例資料庫名。

網站（Web 伺服器）設定（ServBay 網站）

為讓瀏覽器能存取您的 Symfony 專案，需使用 ServBay「網站」功能設定本地虛擬主機。Symfony 專案的 Web 根目錄是專案下的 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 伺服器設定。ServBay 預設用 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/ 資料夾建立新的 PHP 檔 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 擴充，您可輕鬆整合進 Symfony 專案。

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

ServBay 支援 MySQL 及 PostgreSQL。以下示範 Symfony 如何設定及使用這兩種資料庫。

1. 設定資料庫連線

   在 .env 檔案根據所用資料庫取消註解、並編輯 DATABASE_URL 項目。

   • 若為 MySQL： ServBay 預設 MySQL 使用者為 root，密碼 password，端口 3306。請依您的 ServBay 設定填寫。

     # .env
     DATABASE_URL="mysql://root:password@127.0.0.1:3306/servbay_symfony_app?serverVersion=8.0&charset=utf8mb4"

   • 若為 PostgreSQL： ServBay 預設 PostgreSQL 使用者為 root，密碼 password，端口 5432。請依您的 ServBay 設定填寫。

     # .env
     DATABASE_URL="postgresql://root:password@127.0.0.1:5432/servbay_symfony_app?serverVersion=13&charset=utf8"

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

2. 建立資料庫

   若尚無 servbay_symfony_app 資料庫，可用 ServBay 資料庫管理工具（如 phpMyAdmin 或 pgAdmin，ServBay 控制台可直接打開）手動新增，或用 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('demo-user@servbay.test');
   
           // 持久化物件（準備寫入）
           $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 預設端口為 11211。

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

     確保 ServBay 控制台有啟動 Memcached 服務。
   • 若為 Redis： ServBay 預設端口為 6379。

     # .env
     # ... 其他設定 ...
     CACHE_DSN=redis://127.0.0.1:6379
     # 若 Redis 需密碼（ServBay 預設無密碼），可如下設定：
     # CACHE_DSN=redis://:your_password@127.0.0.1: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); // 快取一小時
   
               // 模擬耗時操作，例如查詢資料庫複雜資料
               $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 網站設定網域 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。

小結

本指南已帶您用 ServBay 在 macOS 上成功建立、設定並運行一個基本的 Symfony 專案。ServBay 提供了 Symfony 開發所需的所有核心元件（PHP、Composer、Web 伺服器、資料庫、快取），並大幅簡化環境設定流程，讓您能專注於應用開發。您可在此基礎上深入探索更多 Symfony 功能，並活用 ServBay 所支援的其他軟體包與服務。