创建并运行 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 项目并进行配置。

前提条件

在开始之前，请确保您已完成以下准备工作：

安装 ServBay：您已在 macOS 上成功安装并启动 ServBay。如果尚未安装，请参考 ServBay 安装指南。
ServBay 运行正常：ServBay 的核心服务（如 Caddy 或 Apache，以及您需要的数据库）正在运行。
基本了解：对 PHP、Composer 以及 Symfony 的基本概念有初步了解。

创建 Symfony 项目

ServBay 建议将您的网站项目统一存放在 /Applications/ServBay/www 目录下，这有助于 ServBay 识别和管理您的项目。

确认 Composer 可用
ServBay 在安装时已经集成了 Composer，并且已经配置好环境变量，您无需单独安装。您可以在终端中输入 composer --version 来确认 Composer 是否可用。
创建项目目录
在推荐的网站根目录下创建一个新的目录用于存放您的 Symfony 项目：
bash
```
cd /Applications/ServBay/www
mkdir servbay-symfony-app
```
1
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::index
```
1
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!');
    }
}

这段代码创建了一个简单的控制器类 DefaultController，其中的 index 方法通过 @Route("/") 注解被关联到网站的根路径 /。当访问根路径时，该方法会返回一个包含文本 "Hello ServBay and Symfony!" 的 HTTP 响应。

访问网站

现在，打开您的 Web 浏览器，访问您在 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 中配置并使用这两种数据库。

配置数据库连接
在项目根目录的 .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）。
创建数据库
如果数据库 servbay_symfony_app 不存在，您可以通过 ServBay 的数据库管理工具（如 phpMyAdmin 或 pgAdmin，可通过 ServBay 控制面板访问）手动创建，或者使用 Symfony 命令创建：
bash
```
php bin/console doctrine:database:create
```
1
创建 Entity (实体) 和迁移文件
在 Symfony 中，您通常使用 Doctrine Entity 来表示数据库表。使用 Maker Bundle 可以方便地生成 Entity 和数据库迁移文件。
- 创建 Entity (例如 User 实体):
  bash
```
php bin/console make:entity User
```
  1
  按照提示添加字段，例如 name (string) 和 email (string, unique=yes)。
- 创建迁移文件: 根据 Entity 的变化，生成数据库迁移文件：
  bash
```
php bin/console make:migration
```
  1
  这会在 src/Migrations 目录下创建一个新的迁移文件，其中包含了创建 users 表的 SQL 语句。
运行迁移
执行迁移命令，将数据库结构应用到您的数据库中：
bash
```
php bin/console doctrine:migrations:migrate
```
1

添加数据库操作示例

修改 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!');
    }

    // ... 其他方法 ...
}

然后，在 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::getUsers

在 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);
    }
}

访问示例
- 访问 https://servbay-symfony-test.local/add-user 来添加一个用户。
- 访问 https://servbay-symfony-test.local/get-users 来查看已添加的用户列表（以 JSON 格式）。

缓存与 NoSQL 数据库示例 (Symfony Cache)

ServBay 内置了 Redis 和 Memcached 服务，以及相应的 PHP 扩展，您可以直接在 Symfony 中使用 Symfony Cache 组件来利用这些服务。

配置缓存连接
在 .env 文件中配置您的缓存服务连接。
- 对于 Memcached: ServBay 默认的 Memcached 端口是 11211。
  dotenv
```
# .env
# ... 其他配置 ...
CACHE_DSN=memcached://127.0.0.1:11211
```
  1
  2
  3
  确保您在 ServBay 控制面板中启动了 Memcached 服务。
- 对于 Redis: ServBay 默认的 Redis 端口是 6379。
  dotenv
```
# .env
# ... 其他配置 ...
CACHE_DSN=redis://127.0.0.1:6379
# 如果 Redis 需要密码 (ServBay 默认无密码), 可以这样配置:
# CACHE_DSN=redis://:your_password@127.0.0.1:6379
```
  1
  2
  3
  4
  5
  确保您在 ServBay 控制面板中启动了 Redis 服务。

添加缓存使用示例

修改 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; // 赋值
    }

    // ... 其他方法 ...
}

然后，在 config/routes.yaml 中添加新的路由：

yaml

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

在 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); // 设置缓存有效期为 1 小时

            // 模拟一个耗时操作，例如从数据库查询复杂数据
            $data = "Data generated at " . date('Y-m-d H:i:s');

            // 返回要缓存的数据
            return $data;
        });

        // $cacheItem 已经是缓存中的数据（如果命中）或新生成的数据
        $output = "From Cache: " . $cacheItem;

        return new Response($output);
    }
}

访问示例
- 访问 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 提供的其他软件包和服务。

创建并运行 Symfony 项目 ​

什么是 Symfony？ ​

Symfony 的主要特性和优势 ​

使用 ServBay 创建并运行 Symfony 项目 ​

前提条件 ​

创建 Symfony 项目 ​

初始化配置 ​

配置 Web 服务器 (ServBay 网站) ​

添加基础示例代码 ​

访问网站 ​

数据库与缓存示例 ​

关系型数据库示例 (Doctrine ORM) ​

缓存与 NoSQL 数据库示例 (Symfony Cache) ​

常见问题 (FAQ) ​

总结 ​