安装 & 设置 Symfony 框架

编辑此页

视频教程

您是否更喜欢视频教程？请查看使用 Symfony 进行和谐开发视频教程系列。

技术要求

在创建您的第一个 Symfony 应用之前，您必须

安装 PHP 8.2 或更高版本以及以下 PHP 扩展（这些扩展在大多数 PHP 8 安装中默认安装并启用）：Ctype、 iconv、 PCRE、 Session、 SimpleXML 和 Tokenizer；
安装 Composer，它用于安装 PHP 扩展包。

此外，安装 Symfony CLI。这是可选的，但它为您提供了一个有用的二进制文件 symfony，它提供了您在本地开发和运行 Symfony 应用所需的所有工具。

symfony 二进制文件还提供了一个工具来检查您的计算机是否满足所有要求。打开您的控制台终端并运行此命令

        1
        $ symfony check:requirements
    

注意

Symfony CLI 是开源的，您可以在 symfony-cli/symfony-cli GitHub 仓库中为其做出贡献。

创建 Symfony 应用

打开您的控制台终端并运行以下任何命令来创建一个新的 Symfony 应用

        1
2
3
4
5
        # run this if you are building a traditional web application
$ symfony new my_project_directory --version="7.2.x" --webapp

# run this if you are building a microservice, console application or API
$ symfony new my_project_directory --version="7.2.x"
    

这两个命令之间唯一的区别是默认安装的扩展包数量。--webapp 选项安装额外的扩展包，为您提供构建 Web 应用所需的一切。

如果您不使用 Symfony 二进制文件，请运行以下命令以使用 Composer 创建新的 Symfony 应用

        1
2
3
4
5
6
7
        # run this if you are building a traditional web application
$ composer create-project symfony/skeleton:"7.2.x" my_project_directory
$ cd my_project_directory
$ composer require webapp

# run this if you are building a microservice, console application or API
$ composer create-project symfony/skeleton:"7.2.x" my_project_directory
    

无论您运行哪个命令来创建 Symfony 应用。所有这些命令都将创建一个新的 my_project_directory/ 目录，将一些依赖项下载到其中，甚至生成启动所需的基本目录和文件。换句话说，您的新应用已准备就绪！

注意

项目的缓存和日志目录（默认情况下，<project>/var/cache/ 和 <project>/var/log/）必须可由 Web 服务器写入。如果您有任何问题，请阅读如何设置 Symfony 应用的权限。

设置现有的 Symfony 项目

除了创建新的 Symfony 项目之外，您还将处理其他开发人员已经创建的项目。在这种情况下，您只需要获取项目代码并使用 Composer 安装依赖项。假设您的团队使用 Git，请使用以下命令设置您的项目

        1
2
3
4
5
6
7
        # clone the project to download its contents
$ cd projects/
$ git clone ...

# make Composer install the project's dependencies into vendor/
$ cd my-project/
$ composer install
    

您可能还需要自定义您的 .env 文件并执行一些其他特定于项目的任务（例如，创建数据库）。首次处理现有 Symfony 应用时，运行此命令可能会很有用，该命令显示有关项目的信息

        1
        $ php bin/console about
    

运行 Symfony 应用

在生产环境中，您应该安装像 Nginx 或 Apache 这样的 Web 服务器，并配置它以运行 Symfony。如果您不使用 Symfony 本地 Web 服务器进行开发，也可以使用此方法。

然而，对于本地开发，运行 Symfony 最方便的方式是使用 symfony 二进制文件提供的本地 Web 服务器。此本地服务器除了其他功能外，还提供对 HTTP/2、并发请求、TLS/SSL 和自动生成安全证书的支持。

打开您的控制台终端，移动到您的新项目目录并按如下方式启动本地 Web 服务器

        1
2
        $ cd my-project/
$ symfony server:start
    

打开您的浏览器并导航到 https://127.0.0.1:8000/。如果一切正常，您将看到一个欢迎页面。稍后，当您完成工作时，通过在终端中按 Ctrl+C 停止服务器。

提示

Web 服务器适用于任何 PHP 应用，而不仅仅是 Symfony 项目，因此它是一个非常有用的通用开发工具。

Symfony Docker 集成

如果您想将 Docker 与 Symfony 一起使用，请参阅将 Docker 与 Symfony 一起使用。

安装扩展包

开发 Symfony 应用时，常见的做法是安装提供即用型功能的扩展包（Symfony 称之为 bundles）。扩展包通常在使用前需要进行一些设置（编辑一些文件以启用扩展包，创建一些文件以添加一些初始配置等）。

大多数时候，这种设置可以自动化，这就是 Symfony 包含 Symfony Flex 的原因，Symfony Flex 是一种简化 Symfony 应用中扩展包安装/删除的工具。从技术上讲，Symfony Flex 是一个 Composer 插件，在创建新的 Symfony 应用时默认安装，它自动化了 Symfony 应用的最常见任务。

提示

您也可以将 Symfony Flex 添加到现有项目。

Symfony Flex 修改了 require、update 和 remove Composer 命令的行为，以提供高级功能。考虑以下示例

        1
2
        $ cd my-project/
$ composer require logger
    

如果您在不使用 Flex 的 Symfony 应用中运行该命令，您将看到一个 Composer 错误，解释说 logger 不是有效的扩展包名称。但是，如果应用安装了 Symfony Flex，则该命令将安装并启用使用官方 Symfony logger 所需的所有扩展包。

这是可能的，因为许多 Symfony 扩展包/bundles 定义了 “recipes”，这是一组自动化指令，用于在 Symfony 应用中安装和启用扩展包。Flex 在 symfony.lock 文件中跟踪其安装的 recipes，该文件必须提交到您的代码仓库。

Symfony Flex recipes 由社区贡献，它们存储在两个公共仓库中

主 recipe 仓库，是高质量和维护的扩展包的精选 recipe 列表。默认情况下，Symfony Flex 仅在此仓库中查找。
Contrib recipe 仓库，包含社区创建的所有 recipes。所有这些都保证可以工作，但它们关联的扩展包可能未维护。Symfony Flex 会在安装任何这些 recipes 之前征求您的许可。

阅读 Symfony Recipes 文档以了解有关如何为自己的扩展包创建 recipes 的所有信息。

Symfony 包

有时，单个功能需要安装多个扩展包和 bundles。Symfony 提供了 packs，它们是包含多个依赖项的 Composer 元扩展包，而不是单独安装它们。

例如，要在您的应用中添加调试功能，您可以运行 composer require --dev debug 命令。这会安装 symfony/debug-pack，它反过来安装多个扩展包，如 symfony/debug-bundle、symfony/monolog-bundle、symfony/var-dumper 等。

您不会在 composer.json 中看到 symfony/debug-pack 依赖项，因为 Flex 会自动解包该包。这意味着它只会将真正的扩展包添加为依赖项（例如，您将在 require-dev 中看到一个新的 symfony/var-dumper）。

检查安全漏洞

当您安装 Symfony CLI 时创建的 symfony 二进制文件提供了一个命令来检查您的项目依赖项是否包含任何已知的安全漏洞

        1
        $ symfony check:security
    

一个好的安全实践是定期执行此命令，以便能够尽快更新或替换受损的依赖项。安全检查在本地完成，方法是获取公共 PHP 安全公告数据库，因此您的 composer.lock 文件不会在网络上发送。

如果您的任何依赖项受到已知安全漏洞的影响，check:security 命令将以非零退出代码终止。这样，您可以将其添加到您的项目构建过程和持续集成工作流程中，以在存在漏洞时使其失败。

提示

在持续集成服务中，您可以使用一个名为 Local PHP Security Checker 的不同独立项目来检查安全漏洞。这与 check:security 内部使用的项目相同，但尺寸比整个 Symfony CLI 小得多。

Symfony LTS 版本

根据 Symfony 发布流程，“长期支持”（或简称 LTS）版本每两年发布一次。查看 Symfony 版本以了解哪个是最新的 LTS 版本。

默认情况下，创建新的 Symfony 应用的命令使用最新的稳定版本。如果您想使用 LTS 版本，请添加 --version 选项

        1
2
3
4
5
6
7
8
        # use the most recent LTS version
$ symfony new my_project_directory --version=lts

# use the 'next' Symfony version to be released (still in development)
$ symfony new my_project_directory --version=next

# you can also select an exact specific Symfony version
$ symfony new my_project_directory --version="6.4.*"
    

仅当使用 Symfony 创建新项目时，lts 和 next 快捷方式才可用。如果您使用 Composer，则需要告知确切的版本

        1
        $ composer create-project symfony/skeleton:"6.4.*" my_project_directory
    

Symfony Demo 应用

Symfony Demo 应用是一个功能齐全的应用，展示了开发 Symfony 应用的推荐方法。对于 Symfony 新手来说，它是一个很棒的学习工具，其代码包含大量注释和有用的注释。

运行此命令以创建基于 Symfony Demo 应用的新项目

        1
        $ symfony new my_project_directory --demo
    

开始编码！

完成设置后，就该在 Symfony 中创建您的第一个页面了。

了解更多

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。

版本