可重用包的最佳实践

编辑本页

警告:您正在浏览的文档欧宝体育电话欧宝娱乐app下载地址Symfony 5.2,现已不再维护。

本页的更新版本用于Sy欧宝娱乐app下载地址mfony 6.2(当前稳定版本)。

可重用包的最佳实践

这篇文章是关于如何组织你的可重复使用的包可配置和可扩展。可重用包是指那些在许多公司项目之间私下或公开共享的包,以便任何Symfony项目都可以安装它们。欧宝娱乐app下载地址

包的名字

bundle也是一个PHP名称空间。名称空间必须跟在PSR-4PHP名称空间和类名的互操作性标准:它以供应商段开始,后面跟着零个或多个类别段,以名称空间短名称结束,名称空间短名称必须以

一旦您向命名空间添加“一个包类”(这是一个扩展的类),命名空间就变成了一个包).bundle类名称必须遵循以下规则:

  • 只使用字母数字字符和下划线;
  • 使用StudlyCaps名称(即驼峰大写首字母);
  • 使用描述性和简短的名称(不超过两个词);
  • 在名称前加上供应商的连接(可选的类别名称空间);
  • 名称后缀为

下面是一些有效的包名称空间和类名称:

名称空间 Bundle类名称
Acme \包\ BlogBundle AcmeBlogBundle
Acme \ BlogBundle AcmeBlogBundle

按照惯例,getName ()方法应该返回类名。

请注意

如果您公开共享您的包,则必须使用包类名作为存储库的名称(例如AcmeBlogBundle而不是BlogBundle)。

请注意

欧宝娱乐app下载地址Symfony的核心Bundle不会给Bundle类加上前缀欧宝娱乐app下载地址总是加上sub-namespace;例如:FrameworkBundle

每个bundle都有一个别名,它是使用下划线(acme_blogAcmeBlogBundle)。这个别名用于强制项目内的唯一性,并用于定义bundle的配置选项(参见下面的一些使用示例)。

目录结构

以下是AcmeBlogBundle的推荐目录结构:

12 3 4 5 6 7 8 9 10 11 12 13 14

                 
                  /├──config/├──docs/│├─index。md├──public/├──src/│├──Controller/│├──DependencyInjection/│├──AcmeBlogBundle.php├──templates/├──tests/├──translations/├──LICENSE├──README.md

这个目录结构需要将bundle路径配置到它的根目录,如下所示:

1 2 3 4 5 6 7
AcmeBlogBundle扩展公共函数getPath()字符串返回\目录名(__DIR__);}}

以下文件是必须的,因为它们确保了自动化工具可以依赖的结构约定:

  • src / AcmeBlogBundle.php:这是一个将普通目录转换为Symfony包的类(更改为您的包的名称);欧宝娱乐app下载地址
  • README.md:这个文件包含包的基本描述,通常会显示一些基本示例和完整文档的链接(它可以使用GitHub支持的任何标记格式,例如欧宝体育电话README.rst);
  • 许可证:代码使用的许可证的全部内容。大多数第三方捆绑包是在MIT许可下发布的,但是您可以选择任何许可证
  • 文档/ index.md: Bundle文档的根文件。欧宝体育电话

对于最常用的类和文件,子目录的深度应该保持在最小值。两级是最大的。

bundle目录是只读的。如果需要写入临时文件,请将它们存储在缓存/日志/主机应用程序的目录。工具可以在bundle目录结构中生成文件,但前提是生成的文件将成为存储库的一部分。

以下类和文件有特定的位置(一些是强制性的,其他只是大多数开发人员遵循的约定):

类型 目录
命令 src /命令/
控制器 src /控制器/
服务容器扩展 src / DependencyInjection /
Doctrine ORM实体(不使用注释时) src /实体
ODM文档(不使用注释时) src /文档/
事件监听器 src / EventListener /
配置(路由、服务等) 配置/
Web资产(CSS, JS,图像) 公共/
翻译文件 翻译/
验证(不使用注释时) 配置/验证/
序列化(不使用注释时) 配置/序列化/
模板 模板/
单元和功能测试 测试/

包目录结构用作命名空间层次结构。例如,aContentController存储的控制器src /控制器/ ContentController.php的完全限定类名Acme \ BlogBundle \ \ ContentController控制器

所有类和文件都必须遵循欧宝娱乐app下载地址Symfony编码标准

有些类应该被视为门面,并且应该尽可能短,比如命令、助手、监听器和控制器。

连接到事件调度程序的类应该以侦听器

异常类应该存储在异常sub-namespace。

供应商

bundle不能嵌入第三方PHP库。它应该依赖于标准的Symfony自动加载。欧宝娱乐app下载地址

bundle也不应该嵌入用JavaScript、CSS或任何其他语言编写的第三方库。

测试

包应该附带一个用PHPUnit编写的测试套件,并存储在测试/目录中。测试应遵循以下原则:

  • 测试套件必须使用简单的phpunit)命令从示例应用程序运行;
  • 功能测试应该只用于测试响应输出和一些分析信息(如果您有的话);
  • 测试应该覆盖至少95%的代码库。

请注意

测试套件不能包含AllTests.php脚本,但必须依靠一个存在phpunit.xml.dist文件。

持续集成

持续测试捆绑包代码,包括它的所有提交和拉取请求,是一种称为持续集成的好实践。有一些服务为开源项目免费提供此功能,例如GitHub的行为而且特拉维斯CI

一个bundle至少应该测试:

  • 它们的依赖关系的下界(通过运行编写器更新——prefer-lowest);
  • 受支持的PHP版本;
  • 所有支持的主要Symfony版本(例如欧宝娱乐app下载地址4.倍而且5.倍如果两者都要求支持)。

因此,一个包支持PHP 7.3、7.4和8.0,以及Symfony 4.4和5。欧宝娱乐app下载地址X至少应该有这样的测试矩阵:

PHP版本 欧宝娱乐app下载地址Symfony的版本 作曲家的旗帜
7.3 4 . * ——prefer-lowest
7.4 5 . *
8.0 5 . *

提示

测试应使用欧宝娱乐app下载地址SYMFONY_DEPRECATIONS_HELPER环境变量设置为马克斯(直接)= 0.这确保包中的代码不会直接使用已弃用的特性。

最低依赖项测试可以在将此变量设置为时运行禁用= 1

需要一个特定的Symfony版本欧宝娱乐app下载地址

你可以用特价欧宝娱乐app下载地址SYMFONY_REQUIRE使用Symfony Flex来安装特定的Symfony版本:欧宝娱乐app下载地址

1 2 3 4 5 6 7 8 9
#这需要Symfony 5。欧宝娱乐app下载地址x用于所有Symfo欧宝娱乐app下载地址ny包出口欧宝娱乐app下载地址SYMFONY_REQUIRE = 5。*在CI环境中安装Sy欧宝娱乐app下载地址mfony Flexsymfony/flex的全局要求-无进度-无脚本-无插件欧宝娱乐app下载地址#安装依赖项(使用——prefer-dist和——no-progress is#推荐有更好的输出和更快的下载时间)编译器更新——prefer-dist——没有进展

谨慎

如果你想缓存你的Composer依赖项,缓存供应商/目录,因为这有副作用。而不是缓存$ HOME / .composer /缓存/文件

安装

bundle应该设置“类型”:“sym欧宝娱乐app下载地址fony-bundle”在他们的composer.json文件。用这个,欧宝娱乐app下载地址Symfony Flex将能够自动启用您的包时,它的安装。

如果你的bundle需要任何设置(例如配置,新文件,更改.gitignore,等等),然后您应该创建一个欧宝娱乐app下载地址Symfony Flex配方

欧宝体育电话

所有的类和函数都必须带有完整的PHPDoc。

还应提供广泛的文件欧宝体育电话文档/目录中。索引文件(例如文档/ index.rst文档/ index.md)是唯一的强制性文件,必须作为文档的入口点。欧宝体育电话的reStructuredText (rST)是用于呈现Symfony网站上的文档的格式。欧宝体育电话欧宝娱乐app下载地址

安装说明

为了简化第三方包的安装,请考虑在您的README.md文件。

  • 减价
  • RST
12 34 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
安装  ============确保Composer已全局安装,详见[安装一章) (https://getcomposer.org/doc/00-intro.md)的Composer文档。欧宝体育电话使用Symfony的Flex应用程序  --欧宝娱乐app下载地址--------------------------------打开一个命令控制台,进入你的项目目录并执行:控制台$ composer require  ' ' 'Flex应用程序不使用Symfony  --------欧宝娱乐app下载地址--------------------------------第一步:下载Bundle打开命令控制台,进入您的项目目录并执行以下命令来下载此包的最新稳定版本:控制台$ composer require  ' ' '第二步:启用Bundle方法中的注册包列表中添加该包,从而启用该包“配置/ bundles.php”项目文件:php // config/bundles.php return[//…<供应商> \ < bundle-name > \ < bundle-long-name >::类= >(“所有”= > true)];' ' '

上面的例子假设您正在安装包的最新稳定版本,在那里您不必提供包的版本号(例如。作曲家需要symfony/user-bundle欧宝娱乐app下载地址).如果安装说明引用了一些过去的bundle版本或一些不稳定的版本,则包括版本约束(例如:Composer require friendsof欧宝娱乐app下载地址symfony/user-bundle "~2.0@dev").

您还可以添加更多安装步骤(步骤3步骤4等),以解释其他所需的安装任务,例如注册路由或转储资产。

路由

如果包提供路由,它们必须以包别名作为前缀。例如,如果您的包名为AcmeBlogBundle,那么它的所有路由都必须以acme_blog_

模板

如果一个bundle提供模板,它们必须使用Twig。bundle不能提供主布局,除非它提供了一个完整的工作应用程序。

翻译文件

如果一个包提供消息转换,它们必须以XLIFF格式定义;域应该按照bundle名称命名(acme_blog).

一个bundle不能覆盖来自另一个bundle的现有消息。

配置

为了提供更大的灵活性,包可以使用Symfony内置机制提供可配置的设置。欧宝娱乐app下载地址

对于简单的配置设置,可以使用默认值参数Symfony配置的入口。欧宝娱乐app下载地址欧宝娱乐app下载地址Symfony参数是简单的键/值对;一个值是任何有效的PHP值。每个参数名都应该以包别名开头,尽管这只是一个最佳实践建议。参数名称的其余部分将使用句点()来分离不同的部分(例如:acme_blog.author.email).

最终用户可以在任何配置文件中提供值:

  • YAML
  • XML
  • PHP
1 2 3
#配置/ services.yaml参数:acme_blog.author.email:“fabien@example.com”

从容器中检索代码中的配置参数:

1
容器->getParameter (“acme_blog.author.email”);

虽然这种机制只需要最少的工作,但您应该考虑使用更高级的机制语义束配置使您的配置更加健壮。

版本控制

bundle的版本必须遵循语义版本标准

服务

如果包定义了服务,它们必须以包别名作为前缀,而不是像在项目服务中那样使用完全限定的类名。例如,AcmeBlogBundle服务必须以acme_blog.原因是bundle不应该依赖于服务自动装配或自动配置等特性,从而在编译应用程序服务时不增加开销。

此外,应用程序应该直接使用不打算直接使用的服务定义为私有.在公共服务方面,应该创建别名从接口/类到服务id。例如,在MonologBundle中,从Psr \ \ LoggerInterface日志日志记录器所以LoggerInterface类型提示可用于自动装配。

服务不应该使用自动装配或自动配置。相反,所有服务都应该显式地定义。

另请参阅

你可以通过阅读这篇文章了解更多关于捆绑服务加载的知识:如何在一个包内加载服务配置

作曲家的元数据

composer.json文件应至少包括以下元数据:

的名字
由供应商和短捆绑包名称组成。如果你是自己发布软件包,而不是代表某家公司,请使用你的个人名字(例如:/那blog-bundle).从捆绑包短名称中排除供应商名称,并用连字符分隔每个单词。例如:AcmeBlogBundle转换为blog-bundle和acmessocialconnectbundle转换为social-connect-bundle
描述
对捆绑包目的的简要说明。
类型
使用欧宝娱乐app下载地址symfony-bundle价值。
许可证
对象的字符串(或字符串数组)有效的许可证标识符,例如麻省理工学院
自动装载

Symfony使用此信息来加载包的类。欧宝娱乐app下载地址建议使用PSR-4自动加载标准:使用命名空间作为键,并使用包的主类的位置(相对于composer.json)作为价值。类的主类位于src /bundle的目录:

12 3 4 5 6 7 8 9 10 11 12
“自动”: {“psr-4”: {“Acme \ \ BlogBundle \ \”“src /”}},“autoload-dev”: {“psr-4”: {“Acme \ \ BlogBundle \ \测试\ \”“测试/”}}}

为了让开发者更容易找到你的bundle,请在上面注册它Packagist, Composer包的官方存储库。

资源

如果bundle引用任何资源(配置文件、翻译文件等),不要使用物理路径(例如:__DIR__ /配置/ services . xml),而是逻辑路径(例如:@AcmeBlogBundle /配置/ services . xml).

逻辑路径是必需的,因为包覆盖机制允许您覆盖任何包的任何资源/文件。看到HttpKernel组件有关将物理路径转换为逻辑路径的详细信息。

注意模板使用上面所示逻辑路径的简化版本。例如,index.html.twig模板位于模板/违约/目录的AcmeBlogBundle,被引用为@AcmeBlog /违约/ index.html.twig

此工作,包括代码示例,是根据创作共用BY-SA 3.0许可证。