Symfony2 學習筆記之外掛格式

huidaoli發表於2014-08-06


一個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: fabien@example.com

XML格式:

<!-- app/config/config.xml -->
<parameters>
      <parameter key="acme_hello.email.from">fabien@example.com</parameter>
</parameters>

PHP程式碼格式:

// app/config/config.php
$container->setParameter('acme_hello.email.from', 'fabien@example.com');

INI格式:

[parameters]
acme_hello.email.from = fabien@example.com

這樣就可以在程式碼中從容器獲取這些配置資訊了:

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

如果你定義服務,我們也推薦你使用bundle的別名作為字首。

 

總結思考

以上是關於Symfony2中最主要的外掛格式bundle的大體情況,在整個Symfony2為基礎開發的應用程式中,幾乎全部都是有bundle組成。Symfony2本身的核心元件都是FrameworkBundle。在Symfony2交流社群中,已經有了大量的開發者貢獻了他們的bundle,我們可以直接拿來整合到我們自己的應用程式中使用。上面所說的大部分規則,都是應用於你開發貢獻bundle時應該遵循的統一規則,以方便其它使用者使用。

     帶有第三方貢獻的bundle的Symfony2開發包:

     

     如果你不打算把你的bundle貢獻出來,那麼完全可以不用按照這裡說的大部分規則進行開發。

相關文章