扩展包标准

编辑此页

或许与许多其他社区扩展包不同，每个独立的 CMF 扩展包都是一个更大的项目 CMF 的一部分。因此，除了建议的扩展包最佳实践之外，稳定的扩展包还应遵守一套核心标准和目标。

所有 CMF 扩展包必须满足以下列表中列出的要求，才能被归类为稳定版本

本文档的其余部分将详细解释上述各项要求。

通用扩展包标准

类文件命名

复合类名应将主题放在首位

错误示例 正确示例
FoobarMenuNode MenuNodeFoobar
AllFeaturesSimpleBlock SimpleBlockAllFeatures

配置文件命名

服务配置文件应复制命名空间的结构，直到所需的抽象级别。命名空间的每个元素也可以被压缩（例如，event-listener => event）。

可以添加后缀以允许同一配置文件的不同变体。

示例

  • event-imagine-phpcr.xml 和 event-imagine-orm.xml 对于命名空间为 [BundleName]\EventListener\ImagineCacheInvalidatorSubscriber 的事件订阅器
  • doctrine-phpcr.xml 对于 [BundleName]\Doctrine\Phpcr 中的所有类
    命名空间。
  • admin-imagine.xml 对于 [BundleName]\Admin\Imagine 命名空间中的类。

接口命名

用于提供 getter 的接口必须以“ReadInterface”为后缀。

用于提供 setter 的接口必须以“WriteInterface”为后缀。

“Read/Write”接口，它同时提供 getter 和 setter，不得有额外的后缀，并且如果“Read”或“Write”接口存在，则必须扩展它们。

如果“Read”和“Write”接口都不存在或只存在其中一个，则“Read/Write”接口必须包含满足“Read/Write”约定所需的方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?php

interface FoobarInterface extends FoobarReadInterface, FoobarWriteInterface
{
}

// or

interface FoobarInterface extends FoobarReadInterface
{
    public function setFoobar($foobar);
}

// or

interface FoobarInterface
{
    public function getFoobar();

    public function setFoobar($foobar);
}

依赖注入容器配置

请参考 Symfony 文档中的服务命名约定。

元数据：README、CHANGELOG 等

扩展包必须包含以下元文件

1
2
3
4
./README.md
./CHANGELOG.md
./CONTRIBUTING.md
./Resources/meta/LICENSE

请参阅以下模板

持久化

所有 CMF 扩展包

  • 必须支持 PHPCR-ODM 进行持久化；
  • 可以支持其他持久化层，如 Doctrine ORM；
  • 必须遵循以下结构，以支持未来或当前的其他持久化系统
  • 除了 /Model 中的模型外，还必须创建特定于实现的模型（即使它们是空的）。请参阅下面的 Blog.php 和 Post.php。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
./Model
     ./Blog.php
     ./Post.php
./Doctrine
    ./Phpcr
        ./Blog.php
        ./Post.php
        ./PostRepository.php
        ./PostListener.php
    ./Orm
./Resources/
    ./config
        ./doctrine-phpcr
            ./Blog.phpcr.xml

有关更多信息，请参阅 Symfony Cookbook 的“映射模型类”章节。

基础和标准实现

CMF 提供了各种功能，这些功能在某些类的基本用例之外添加了功能。这些功能的示例包括多语言和发布工作流支持，但潜在的功能列表是无限的。

除了使用户仅使用他们需要的功能外，扩展包还应提供即用型和完全集成的实现。

为了方便这一点，在适用时，应该有两种实现，即基础实现和标准实现。

  • 基础实现：此类应以 Base 为后缀，例如 MenuNodeBase，并且它必须是一个具有使其工作所需的绝对最少逻辑的实现，它不应有外部依赖项；
  • 标准实现：此类没有额外的prefix/suffix，例如 MenuNode。此实现必须实现标准 CMF 功能集。此类可以有外部依赖项。

然后，用户可以扩展基础实现，添加他们想要的任何功能，并将标准实现作为参考。

标准 CMF 功能

CMF 扩展包必须（在适用时）实现以下功能

  • PublishWorkflow；
  • 可翻译支持。

配置、文件和格式

核心配置文件必须是 XML 格式，这包括

  • 路由配置；
  • 服务定义；
  • Doctrine 映射；
  • 翻译（XLIFF 格式）。

在其他情况下，如果可以选择，则 XML 应该优先于其他配置格式。

扩展包必须遵守以下目录和文件名模式（如果适用）

1
2
3
4
5
6
7
8
9
./Resources/
    ./config/
        ./schema/
            ./bundlename-1.0.xsd
        ./routing
            ./my_service.xml
        ./admin.xml                # all sonata-admin stuff
        ./validation.xml           # all validation
        ./my-related-services.xml  # semantically named file for specific services

扩展包必须定义一个 Configuration 类

1
2
3
./DependencyInjection
    ./Configuration.php
    ./MyBundleExtension.php

扩展包应为其配置提供 XML 模式，由 Configuration::getXsdValidationBasePath 提供。

扩展包必须使用自己的 XML 命名空间，XML 命名空间为 http://cmf.symfony.com/schema/dic/bundle_name，其中 bundle_name 是扩展包的 DI 别名。

扩展包必须支持配置类中的 XML。

测试组件集成

所有扩展包都必须实现CMF Testing 组件。

本作品，包括代码示例，均根据Creative Commons BY-SA 3.0 许可协议获得许可。
目录
    版本