建立並運行 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 專案並完成基本設定。
前置準備 
開始前,請確保您已完成以下準備事項:
- 安裝 ServBay:已在 macOS 上成功安裝並啟動 ServBay。尚未安裝請參考 ServBay 安裝指南。
- ServBay 正常運作:ServBay 的核心服務(如 Caddy 或 Apache,以及所需的資料庫)已啟動。
- 基本概念:具備 PHP、Composer 及 Symfony 基本認知。
建立 Symfony 專案 
ServBay 建議將所有網站專案統一存放在 /Applications/ServBay/www 目錄中,便於識別與管理。
- 確認 Composer 可用 - ServBay 安裝時已整合 Composer 並自動配置好環境變數,不需額外安裝。您可在終端輸入 - composer --version確認 Composer 是否可用。
- 建立專案目錄 - 在建議的網站根目錄中建立新資料夾存放 Symfony 專案: bash- cd /Applications/ServBay/www mkdir servbay-symfony-app1
 2
- 使用 Composer 建立 Symfony 專案 - 進入新建立的專案目錄,用 Composer 建立基於 - website-skeleton的 Symfony 專案骨架。- website-skeleton是常見 Web 應用的標準起始架構。bash- cd /Applications/ServBay/www/servbay-symfony-app composer create-project symfony/website-skeleton .1
 2- 執行此命令,Composer 會將 Symfony 核心與相關依賴下載到本目錄。 
初始化設定 
Symfony 專案的核心設定一般用環境變數管理,這些變數可存放在專案根目錄下的 .env 檔案。
- 設定環境變數( - .env)- 開啟專案根目錄下的 - .env檔案。該檔包含應用程式的環境設定,例如資料庫連線資訊、應用密鑰等。依需求修改或新增設定項目。- 請確保以下設定正確,並根據您的 ServBay 環境調整: dotenv- # .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"1
 2
 3
 4
 5
 6
 7
 8- 請將 - 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 添加第一個網站。
加入基礎範例程式 
為驗證網站設定是否成功,接下來加一個簡單的路由及控制器,讓瀏覽根目錄時顯示訊息。
- 設定路由( - config/routes.yaml)- 開啟 - config/routes.yaml檔案,加入下列內容定義根目錄- /路由,並指定控制器方法為- index:yaml- # config/routes.yaml index: path: / controller: App\Controller\DefaultController::index1
 2
 3
 4
- 建立控制器( - src/Controller/DefaultController.php)- 在 - src/Controller/資料夾建立新的 PHP 檔- DefaultController.php並加入下列程式: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!'); } }1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18- 上述程式建立了 - DefaultController控制器類別,其中- index方法利用- @Route("/")註解綁定根目錄。瀏覽根目錄時,會回傳 "Hello ServBay and Symfony!" 字串的 HTTP 響應。
存取網站 
現在打開您的瀏覽器,輸入您在 ServBay 設定的網域 https://servbay-symfony-test.local。若所有設定正確,頁面將顯示:
Hello ServBay and Symfony!1
這代表您的 Symfony 專案已透過 ServBay 的 Web 伺服器成功運行。ServBay 會自動配置 HTTPS,建議固定用 https:// 存取。
資料庫與快取範例 
Symfony 通常利用 Doctrine ORM 處理關聯式資料庫,並用 Symfony Cache 元件處理快取或 NoSQL 資料庫。ServBay 內建多種資料庫服務和相對應 PHP 擴充,您可輕鬆整合進 Symfony 專案。
關聯式資料庫範例(Doctrine ORM) 
ServBay 支援 MySQL 及 PostgreSQL。以下示範 Symfony 如何設定及使用這兩種資料庫。
- 設定資料庫連線 - 在 - .env檔案根據所用資料庫取消註解、並編輯- DATABASE_URL項目。- 若為 MySQL: ServBay 預設 MySQL 使用者為 root,密碼password,端口3306。請依您的 ServBay 設定填寫。dotenv# .env DATABASE_URL="mysql://root:password@127.0.0.1:3306/servbay_symfony_app?serverVersion=8.0&charset=utf8mb4"1
 2
- 若為 PostgreSQL: ServBay 預設 PostgreSQL 使用者為 root,密碼password,端口5432。請依您的 ServBay 設定填寫。dotenv# .env DATABASE_URL="postgresql://root:password@127.0.0.1:5432/servbay_symfony_app?serverVersion=13&charset=utf8"1
 2
 - 請確認 ServBay 控制台已啟動相應資料庫服務(MySQL 或 PostgreSQL)。 
- 若為 MySQL: ServBay 預設 MySQL 使用者為 
- 建立資料庫 - 若尚無 - servbay_symfony_app資料庫,可用 ServBay 資料庫管理工具(如 phpMyAdmin 或 pgAdmin,ServBay 控制台可直接打開)手動新增,或用 Symfony 指令建立:bash- php bin/console doctrine:database:create1
- 建立 Entity(實體)與遷移檔 - 在 Symfony,通常利用 Doctrine Entity 表示資料表。Maker Bundle 可協助快速產生 Entity 及資料庫遷移檔。 - 建立 Entity(以 User實體為例):bash按提示加欄位,例如php bin/console make:entity User1name(string)及email(string,unique=yes)。
- 建立遷移檔: 根據 Entity 變化,產生資料庫遷移檔:bash會在php bin/console make:migration1src/Migrations資料夾生成遷移檔,內含建立users表的 SQL。
 
- 建立 Entity(以 
- 執行遷移 - 運行指令將資料表結構套用到資料庫: bash- php bin/console doctrine:migrations:migrate1
- 加入資料庫操作範例 - 修改 - src/Controller/DefaultController.php,新增路由及方法示範如何用 Doctrine 寫入及讀取資料。需將- EntityManagerInterface注入建構函數。- 首先,確保 - DefaultController建構函數已注入- EntityManagerInterface:php- <?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!'); } // ... 其他方法 ... }1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30- 然後在 - config/routes.yaml加入新路由: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::getUsers1
 2
 3
 4
 5
 6
 7
 8- 在 - src/Controller/DefaultController.php加入相關控制器方法: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); } }1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
- 存取範例 - 訪問 https://servbay-symfony-test.local/add-user可新增一位使用者。
- 訪問 https://servbay-symfony-test.local/get-users查看已新增的使用者列表(JSON 格式)。
 
- 訪問 
快取與 NoSQL 資料庫範例(Symfony Cache) 
ServBay 內建 Redis 及 Memcached 服務和對應 PHP 擴充,可直接透過 Symfony Cache 元件使用。
- 設定快取連線 - 在 - .env檔案加入快取服務連線設定。- 若為 Memcached: ServBay 預設端口為 11211。dotenv確保 ServBay 控制台有啟動 Memcached 服務。# .env # ... 其他設定 ... CACHE_DSN=memcached://127.0.0.1:112111
 2
 3
- 若為 Redis: ServBay 預設端口為 6379。dotenv確保 ServBay 控制台已啟動 Redis 服務。# .env # ... 其他設定 ... CACHE_DSN=redis://127.0.0.1:6379 # 若 Redis 需密碼(ServBay 預設無密碼),可如下設定: # CACHE_DSN=redis://:your_password@127.0.0.1:63791
 2
 3
 4
 5
 
- 若為 Memcached: ServBay 預設端口為 
- 加入快取使用範例 - 修改 - src/Controller/DefaultController.php,新增路由及方法示範 Symfony Cache 結合 Memcached 或 Redis。需將- CacheInterface注入建構函數。- 首先,確保 - DefaultController建構函數已注入- CacheInterface: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; // 引入 CacheInterface class DefaultController { private $entityManager; private $cache; // 新增 cache 成員 // 建構函數注入 CacheInterface public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache) { $this->entityManager = $entityManager; $this->cache = $cache; // 賦值 } // ... 其他方法 ... }1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25- 接著在 - config/routes.yaml加入新路由:yaml- # config/routes.yaml # ... 其他路由 ... cache_example: path: /cache-example controller: App\Controller\DefaultController::cacheExample1
 2
 3
 4
 5- 在 - src/Controller/DefaultController.php加入控制器方法: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); } }1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
- 存取範例 - 訪問 https://servbay-symfony-test.local/cache-example。 首次存取會執行回呼並將資料寫入快取,後續存取只要未過期,便直接從 Memcached 或 Redis 取資料。
 
- 訪問 
常見問題 FAQ 
Q: 訪問 https://servbay-symfony-test.local 出現找不到頁面或 500 錯誤怎麼辦?
A: 請檢查:
- ServBay 是否運作且已啟動網站服務(Caddy 或 Apache)。
- 查 ServBay 網站設定網域 servbay-symfony-test.local是否正確,且「網站根目錄」是否精確指向/Applications/ServBay/www/servbay-symfony-app/public。
- 查看 Symfony 專案日誌(var/log/dev.log)取得詳細錯誤訊息。
- 在專案根目錄運行 composer install,確認所有依賴已安裝。
- 檢查 PHP 版本是否與 Symfony 專案兼容。
Q: 資料庫連線失敗怎辦?
A: 請檢查:
- ServBay 控制台所需資料庫服務(MySQL 或 PostgreSQL)是否啟動。
- .env檔案- DATABASE_URL設定是否正確,包括用戶名稱、密碼、主機 (127.0.0.1)、端口(MySQL 3306、PostgreSQL 5432)及資料庫名。
- 資料庫用戶及密碼要與 ServBay 預設或自行更改憑證一致。
- 請確認要連線的 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 所支援的其他軟體包與服務。
