Symfony2学习笔记之插件格式分析

本文讲述了symfony2的插件格式。分享给大家供大家参考，具体如下：

一个bundle类似于其它框架中的插件，但是比插件表现更好。它跟其它框架最主要的不同是在symfony2中所有东西都是bundle，包括核心框架功能和你写的所有应用程序代码。symfony2中，bundle可是一等公民。这给了你使用其它第三方开发的内容包或者分发你自己的bundle更多灵活性。你可以方便的选择哪些内容可以应用到你的程序中那些不用，来根据你的想法优化它们。

一个bundle就是一个目录，它具有很好的结构性，它能存放从类到controller和web资源等任何东西。

一个bundle仅仅是一个结构化的文件目录集合，它实现一个单一的内容。

你可以创建一个blogbundle，一个forumbundle或者一个实现用户管理的bundle（好像已经有很多此类开源的bundle了）。每个bundle目录包含跟实现内容有关的所有东西，包括php文件，模板，样式表，javascript文件，测试内容以及其它任何相关的东西。要实现的内容的各方面都保存在一个bundle中。

一个应用程序是由在appkernel类中registerbundles()方法里定义的所有bundle组成。

// app/appkernel.php
public function registerbundles()
{
  $bundles = array(
    new symfony\bundle\frameworkbundle\frameworkbundle(),
    new symfony\bundle\securitybundle\securitybundle(),
    new symfony\bundle\twigbundle\twigbundle(),
    new symfony\bundle\monologbundle\monologbundle(),
    new symfony\bundle\swiftmailerbundle\swiftmailerbundle(),
    new symfony\bundle\doctrinebundle\doctrinebundle(),
    new symfony\bundle\asseticbundle\asseticbundle(),
    new sensio\bundle\frameworkextrabundle\sensioframeworkextrabundle(),
    new jms\securityextrabundle\jmssecurityextrabundle(),
  );
  if (in_array($this->getenvironment(), array('dev', 'test'))) {
    $bundles[] = new acme\demobundle\acmedemobundle();
    $bundles[] = new symfony\bundle\webprofilerbundle\webprofilerbundle();
    $bundles[] = new sensio\bundle\distributionbundle\sensiodistributionbundle();
    $bundles[] = new sensio\bundle\generatorbundle\sensiogeneratorbundle();
  }
  return $bundles;
}

在这里你可以通过该方法来统一控制和管理你的应用程序组成。

一个bundle可以存放在任何目录下，只需要能够通过配置app/autoload.php文件中的自动加载器即可被自动加载。

创建一个bundle

symfony2标准版中已经为你准备好了一全功能的创建bundle的工具文件。你可以运行它来创建bundle的所有内容，当然你也可以

选择自己手工创建。现在我们创建一个acmetestbundle并让它能够在我们的应用程序中工作。注意，这里的acme是一个虚假的提供商名字，你完全可以替换它为你自己组织或公司的名字。

首先，创建一个src/acme/testbundle/ 目录并添加新文件acmetestbundle.php

// src/acme/testbundle/acmetestbundle.php
namespace acme\testbundle;
use symfony\component\httpkernel\bundle\bundle;
class acmetestbundle extends bundle
{
}

接下来，让它在你的应用程序可用，则需要在appkernel类中的registerbundles()方法中添加它。

// app/appkernel.php
public function registerbundles()
{
  $bundles = array(
    // ...
    // register your bundles
    new acme\testbundle\acmetestbundle(),
  );
  // ...
  return $bundles;
}

虽然现在它不能做任何事情，但是它已经成为你应用程序的一部分了。

我们同样可以使用symfony2为我们提供给命令行工具来创建：

$ php app/console generate:bundle --namespace=acme/testbundle

如果你使用上面的命令行工具，则创建的bundle会自动的注册到appkernel类中。

bundle的目录结构

看一下我们symfony2自带的demo bundle的目录结构：

bundle的目录机构简单灵活，从上面的截图中可以看到：

controller/ 包含bundle的所有controllers文件，比如hellocontroller.php 。
dependencyinjection/ 保存了特定的依赖注入扩展类，该类可能会导入服务配置，注册编译器传输或者更多其它。该目录并不是必需的。
resources/config/ 存放着配置文件，包括路由配置（比如：routing.yml)。
resources/views/ 所有的模板被按照对应controller的名字分成文件夹保存在这里。比如hello/index.html.twig 。
resources/public/ 所有可访问的web资源（图片，样式表等）和通过assets:install控制台命令拷贝或者异步链接到项目 web/ 目录的内容。
tests/ 保存bundle所有的测试

下面是symfony2 推荐的一些有关bundle的标准规则：

bundle名称：

一个bundle同时也是一个php的命名空间。命名空间必须遵守php5.3命名空间和类名的内部技术标准。开头使用提供商名，接着是分类段（可以省略），最后是命名空间的简写名字，而且该名字必须以bundle作为后缀。一个命名空间变为一个bundle只需要你在该命名空间内添加一个bundle类即可。

bundle类的命名：

仅适用数字，字母和下划线
使用驼峰式命名
使用描述性简洁的名字(不超过两个单词）
使用供应商名称做前缀(可选的分类命名空间）

添加bundle作为名称后缀

比如：

namespace => bundle 类名称

acme\bundle\blogbundle => acmeblogbundle
acme\bundle\social\blogbundle =>acmesocialblogbundle
acme\blogbundle => acmeblogbundle

定义bundle类时的getname()方法应该返回类名称。

每个bundle都有一个别名，它是小写字符简写版的bundle名，使用下划线分割。比如 acme_hello 的bundle原名是acmehellobundle, acme_social_blog 则是acme\social\blogbundle的实例。

别名在一个bundle中必须是唯一的。

bundle的目录结构：hellobundle的基础目录结构

xxx/...
  hellobundle/
    hellobundle.php
    controller/
    resources/
      meta/
        license
      config/
      doc/
        index.rst
      translations/
      views/
      public/
    tests/

上面的xxx/... 映射到该bundle的命名空间。其中下面的文件是必备的：

hellobundle.php;

resources/meta/license: 全文的许可代码;
resources/doc/index.rst: bundle说明的根目录文件。

使用类的子文件夹的深度应该保持到最小（2级是极限）。如果更多级可以定义为非静态，不过很少使用。bundle的目录是只读的。如果你需要修改临时文件，把它们保存到主应用程序的cache/ 或者 log/ 目录下。

需要强调的类和文件

类型 vs 目录

commands                            vs         command/
controllers                             vs        controller/
service container extensions   vs        /dependencyinjection/
event listeners                      vs         eventlistener/
configuration                         vs         resources/config
web resources                      vs         resources/public
translation files                      vs         resources/translations/
templates                              vs         resources/views
unit and functional test          vs         tests/

类：

bundle的目录结构是被用来当作命名空间层级的。比如hellocontroller类保存在 bundle/hellobundle/controller/hellocontroller.php文件中。

所以类的完全限定名是 bundle\hellobundle\controller\hellocontroller 。 一些类被看作是装饰，应该越短越好，比如commands,helpers, listeners 和controllers等，一般都会被当作后缀。

跟事件分发器有关的类应该用后缀listener标识。

异常类应该保存到一个exception子命名空间中。

关于提供商

一个bundle不应该被嵌入第三方的php类库，它应该依靠symfony2标准来自动加载它们。

一个bundle不应该被嵌入第三方的javascript，css或者其它语言写的任何类库。

关于测试

一个bundle应该有一个使用phpunit的测试单元并把它存储在tests/ 目录下。

测试应该遵循以下原则：

测试套件必须能够被一个简单的phpunit 命令从一个简单的应用程序中执行。

功能测试应该只备用来测试回复输出和一些监控信息。

测试代码覆盖应该至少在95%以上的基本代码。

一个测试套件可以不包含alltests.php脚本，但必须依靠外部的phpunit.xml.dist文件。

文档说明

所有的类必须带有phpdoc。

controllers

最好的情况下，controller应该在一个可以部署到其它地方的bundle中，那么它不能继承controller基类。而是通过实现containerawareinterface接口或者继承containeraware来取代继承controller。

routing

如果bundle提供路由，他们必须使用bundle的别名为前缀，比如一个acmeblogbundle实例，所有的路由名必须是acme_blog_ 开头。

templates

如果bundle提供模板，它必须使用twig。 bundle不必低通一个主布局文件，如果你的bundle是一个完整的应用程序除外。

翻译文件

如果bundle提供信息翻译，它必须是被定义成xliff格式，区域名必须被命名在bundle名字之后，如bundle.hello

配置

为了提供更大的灵活性，一个bundle可以使用symfony2的内建机制提供配置设置。对于简单的设置，依赖于默认的symfony2的parameters配置入口。 symfony2参数都是简单的 key/value 对。值可以是任意的合法的php值。 每个参数名应该以讹bundle的别名开始，这只是一个最佳的建议。参数名其余部分用点号(.)分割，比如 acme_hello.email.from

让最终用户可以在配置文件中直接提供值信息。

yaml格式：

# app/config/config.yml
parameters:
    acme_hello.email.from: [e-mail]

xml格式：

<!-- app/config/config.xml -->
<parameters>
   <parameter key="acme_hello.email.from">[e-mail]</parameter>
</parameters>

php代码格式：

// app/config/config.php
$container->setparameter('acme_hello.email.from', '[e-mail]');

ini格式：

[parameters]
acme_hello.email.from = [e-mail]

这样就可以在代码中从容器获取这些配置信息了：

$container->getparameter('acme_hello.email.from');

如果你定义服务，我们也推荐你使用bundle的别名作为前缀。

总结思考：

以上是关于symfony2中最主要的插件格式bundle的大体情况，在整个symfony2为基础开发的应用程序中，几乎全部都是有bundle组成。symfony2本身的核心组件都是frameworkbundle。在symfony2交流社区中，已经有了大量的开发者贡献了他们的bundle，我们可以直接拿来集成到我们自己的应用程序中使用。上面所说的大部分规则，都是应用于你开发贡献bundle时应该遵循的统一规则，以方便其它用户使用。

带有第三方贡献的bundle的symfony2开发包：

如果你不打算把你的bundle贡献出来，那么完全可以不用按照这里说的大部分规则进行开发。

希望本文所述对大家基于symfony框架的php程序设计有所帮助。