• 原文出處：StofDoctrineExtensionsBundle自帶的index.rst
• 原文作者：gediminasm.org
• 授權許可：創作共用協議
• 翻譯人員：FireHare
• 校對人員：FireHare
• 適用版本：Symfony 2
• 文章狀態：草譯階段

Provides integration for DoctrineExtensions_ for your Symfony2 Project.
為了您Symfony2項目提供對DoctrineExtensions_的整合。

Features
特點
========

This bundle allows to easily use DoctrineExtensions_ in your Symfony2
project by configuring it through a ``ListenerManager`` and the DIC.
通過配置``ListenerManager`` 和DIC，本Bundle可以在您的Symfony2項目中很方便地來使用DoctrineExtensions_。

DoctrineExtensions's features
DoctrineExtension的特點
-----------------------------

- Tree - this extension automates the tree handling process and adds
? some tree specific functions on repository.
- Tree - 本擴展可以自動化樹處理過程，并在庫中新增了一些特定的樹函數。
- Translatable - gives you a very handy solution for translating
? records into diferent languages. Easy to setup, easier to use.
- Translatable - 給你一個非常方便翻譯記錄的解決方案。易于設置，易于使用。
- Sluggable - urlizes your specified fields into single unique slug
- Sluggable - 將您指定的字段轉換成唯一的URL化短簽
- Timestampable - updates date fields on create, update and even
? property change.
- Timestampable - 在創建、更新甚至是屬性改變時更新數據字段。
- Loggable - tracks your record changes and is able to manage versions.
- Loggable - 跟蹤您記錄的變化，并可以管理版本。

All these extensions can be nested together. And most already use only
annotations without interface requirement to not to aggregate the
entity itself and has implemented proper caching for metadata.
所有這些擴展都可以被嵌套在一起，而且它們大都已經只使用沒有接口要求的注釋，而不要求聚合實體本身，同時也已經實現了適當的元數據緩沖。

See the official blog_ for more details.
更多詳情請參見官方blog_。

Warning
警告
=======

As the DoctrineExtensions library does not provide an XML driver, you
have to use either annotations or YAML for your mapping.
因為DoctrineExtensions庫并沒有提供XML驅動，所以您不得不為您的映射使用注釋或YAML。
Setting a ``DriverChain`` implementation to load only the gedmo mapping
from annotations or YAML and the standard mapping from XML would require
hacking the way the ORM is configured by DoctrineBundle so it will never
be done in the bundle.
``DriverChain``設置只能實現從注釋或YMAL中引導gedmo映射，來自XML的標準映射將要求修改通過DoctrineBundle配置ORM的方式，因此這永遠無法在Bundle中做到。

Installation
安裝
============

Add DoctrineExtensions to your vendor dir
將DoctrineExtensions添加到您的vendor目錄中
-----------------------------------------

::

??? git submodule add git://github.com/l3pp4rd/DoctrineExtensions.git vendor/gedmo-doctrine-extensions

Add DoctrineExtensionsBundle to your vendor/bundles dir
將DoctrineExtensionsBundle添加到您的vendor/bundles目錄中
---------------------------------------------------

::

??? git submodule add git://github.com/stof/StofDoctrineExtensionsBundle.git vendor/bundles/Stof/DoctrineExtensionsBundle

..譯者注::

??? 其實上述兩步可以通過在deps文件中添加下列語句來完成：

??? [gedmo-doctrine-extensions]
??????? git=git://github.com/l3pp4rd/DoctrineExtensions.git
??????? target=/gedmo-doctrine-extensions
???
??? [StofDoctrineExtensionsBundle]
??????? git=git://github.com/stof/StofDoctrineExtensionsBundle.git
??????? target=/bundles/Stof/DoctrineExtensionsBundle

Register the DoctrineExtensions and Stof namespaces
注冊DoctrineExtensions和Stof名稱空間
---------------------------------------------------

::

??? // app/autoload.php
??? $loader->registerNamespaces(array(
??????? 'Stof'? => __DIR__.'/../vendor/bundles',
??????? 'Gedmo' => __DIR__.'/../vendor/gedmo-doctrine-extensions/lib',
??????? // your other namespaces
??? ));

Add DoctrineExtensionsBundle to your application kernel
向您的應用內核中添加DoctrineExtensionsBundle
-------------------------------------------------------

::

??? // app/AppKernel.php
??? public function registerBundles()
??? {
??????? return array(
??????????? // ...
??????????? new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
??????????? // ...
??????? );
??? }

Add DoctrineExtensionsBundle to your mapping
向您的映射文件中添加DoctrineExtensionsBundle
--------------------------------------------

.. note::
.. 注意::

??? This is not needed if you use the auto_mapping setting.
??? 如果您使用auto_mapping設置的話，將不需要

See the official documentation_ for details.
詳情請查看官方documentation_。

for ORM::

??? # app/config.yml
??? doctrine:
??????? orm:
??????????? mappings:
??????????????? StofDoctrineExtensionsBundle: ~
??????????????? # ... your others bundle

or for MongoDB ODM::

??? # app/config.yml
??? doctrine_mongodb:
??????? document_managers:
??????????? default:
??????????????? mappings:
??????????????????? StofDoctrineExtensionsBundle: ~
??????????????????? # ... your others bundle

.. note::
.. 注意::


??? The mapping is only needed when using the ``Translatable`` or the
??? ``Loggable`` behaviors. If you don't use any of them, you can disable
??? it to avoid creating the tables even when using auto_mapping
??? 僅在使用 ``Translatable`` 或 ``Loggable`` 功能時才需要mapping。如果您不用這些功能的話，您可以禁用它以避免在使用auto_mapping時創建數據表。

::

??????? doctrine:
??????????? orm:
??????????????? auto_mapping: true
??????????????? mappings:
??????????????????? StofDoctrineExtensionsBundle: false

Configure the bundle
配置Bundle
====================

You have to activate the extensions for each entity manager for which
you want to enable the extensions. The id is the id of the DBAL
connection when using the ORM behaviors. It is the id of the document
manager when using mongoDB.
為了您要啟用的擴展，您必須為每個實體管理器激活該擴展。當使用ORM方式時id是DBAL連接的id。而在使用mongoDB時id是文檔管理器的id。

This bundle needs a default locale used if the translation does not
exists in the asked language. If you don't provide it explicitly, it
will default to ``en``.
當要求的語言翻譯不存在時，本Bundle將默認使用本地翻譯文件。如果您沒有明確提供時，默認是``en``。

in YAML::

??? # app/config.yml
??? stof_doctrine_extensions:
??????? default_locale: en_US
??????? orm:
??????????? default: ~
??????? mongodb:
??????????? default: ~

or in XML::

??? <!-- app/config.xml -->
??? <container xmlns:stof_doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
??????? <stof_doctrine_extensions:config default-locale="en_US">
??????????? <stof_doctrine_extensions:orm>
??????????????? <stof_doctrine_extensions:entity-manager id="default" />
??????????? </stof_doctrine_extensions:orm>
??????????? <stof_doctrine_extensions:mongodb>
??????????????? <stof_doctrine_extensions:document-manager id="default" />
??????????? </stof_doctrine_extensions:mongodb>
??????? </stof_doctrine_extensions:config>
??? </container>

Activate the extensions you want
激活您想要的擴展
================================

By default the bundle does not attach any listener.
缺省狀況下，Bundle不附加任何監聽器。
For each of your entity manager, declare the extensions you want to enable::
對于您的每個實體管理器，聲明您想要啟用的擴展::

??? # app/config.yml
??? stof_doctrine_extensions:
??????? default_locale: en_US
??????? orm:
??????????? default:
??????????????? tree: true
??????????????? timestampable: false # not needed: listeners are not enabled by default
??????????? other:
??????????????? timestampable: true

or in XML::

??? <!-- app/config.xml -->
??? <container xmlns:doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
??????? <stof_doctrine_extensions:config default-locale="en_US">
??????????? <stof_doctrine_extensions:orm>
??????????????? <stof_doctrine_extensions:entity-manager
??????????????????? id="default"
??????????????????? tree="true"
??????????????????? timestampable="false"
??????????????? />
??????????????? <stof_doctrine_extensions:entity-manager
??????????????????? id="other"
??????????????????? timestampable="true"
??????????????? />
??????????? </stof_doctrine_extensions:orm>
??????? </stof_doctrine_extensions:config>
??? </container>

Same is available for MongoDB using ``document-manager`` in the XML
files instead of ``entity-manager``.
同樣，對于MongoDB，可以在XML文件中使用``document-manager``來代替``entity-manager``

.. caution::
.. 小心::

??? If you configure the listeners of an entity manager in several
??? config file the last one will be used. So you have to list all the
??? listeners you want to detach.
??? 如果您在幾個配置文件中配置了一個實體管理器的監聽器，那么最后一個將被使用。因此您需要列出所有您想要分享的監聽器。

Use the DoctrineExtensions library
使用DoctrineExtensions庫
==================================

All explanations about this library are available on the official blog_
關于該庫的所有說明都可以在官方blog_中找到

As bundle uses the new annotation implementation (as all Symfony2 code)
the annotations are a bit different.
因為Bundle使用了新的注釋實現（正如所有Symfony2代碼一樣），所以注釋有些許不同。

Instead of::
替代::
??? /**
???? * @gedmo:Tree
???? */

use::
使用::

??? use Gedmo\Mapping\Annotation as Gedmo;
??? /**
???? * @Gedmo\Tree
???? */

This applies for all annotations of the library.
這被應用于庫中的所有注釋。

The default entity for translations is
``Stof\DoctrineExtensionsBundle\Entity\Translation``. The default
document is ``Stof\DoctrineExtensionsBundle\Document\Translation``.
缺省的翻譯實體是``Stof\DoctrineExtensionsBundle\Entity\Translation``。缺省的翻譯文檔中 ``Stof\DoctrineExtensionsBundle\Document\Translation``。

Creating your own translation entity
創建您的翻譯實體
------------------------------------

When you have a great number of entries for an entity you should create
a dedicated translation entity to have good performances. The only
difference when using it with Symfony2 is the mapped-superclass to use.
當您的實體中有大量的條目時，您需要創建一個專門的翻譯實體以獲得良好的性能。唯一的區別在于，在Symfony2中是通過映射超類來使用它。

The simplest way to do it is to copy the default translation entity
and just change the namespace and the class name.
最簡單的方法是復制缺省翻譯實體，并改變其空間名和類名。

Here is an example for the ORM::
這里有一個ORM的例子::

??? // src/Application/MyBundle/Entity/MyTranslationEntity.php

??? namespace Application\MyBundle\Entity;

??? use Stof\DoctrineExtensionsBundle\Entity\AbstractTranslation;
??? use Doctrine\ORM\Mapping as ORM;

??? /**
???? * Application\MyBundle\Entity\MyTranslationEntity
???? *
???? * @ORM\Entity(repositoryClass="Gedmo\Translatable\Entity\Repository\TranslationRepository")
???? * @ORM\Table(
???? *???????? name="ext_translations",
???? *???????? indexes={@ORM\index(name="translations_lookup_idx", columns={
???? *???????????? "locale", "object_class", "foreign_key"
???? *???????? })},
???? *???????? uniqueConstraints={@ORM\UniqueConstraint(name="lookup_unique_idx", columns={
???? *???????????? "locale", "object_class", "foreign_key", "field"
???? *???????? })}
???? * )
???? */
??? class TranslationEntity extends AbstractTranslation
??? {
??? }

Same is doable for the ODM.
這同樣也可以用于ODM。

You can also create your own repositoryClass by extending
``Gedmo\Translatable\Entity\Repository\TranslationRepository`` or
``Gedmo\Translatable\Document\Repository\TranslationRepository``
您也可以通過擴展``Gedmo\Translatable\Entity\Repository\TranslationRepository`` 或``Gedmo\Translatable\Document\Repository\TranslationRepository``來創建您自己的repositoryClass。

Advanced use
高級用法
============

Overriding the listeners
覆寫監聽器
------------------------

You can change the listeners used by extending the Gedmo listeners (or
the listeners of the bundle for translations) and giving the class name
in the configuration.
您可以通過擴展Gedmo監聽器（或Bundle中翻譯相關的監聽器）并在配置中給定類名來改變監聽器。

in YAML::

??? # app/config.yml
??? stof_doctrine_extensions:
??????? class:
??????????? tree:?????????? MyBundle\TreeListener
??????????? timestampable:? MyBundle\TimestampableListener
??????????? sluggable:????? ~
??????????? translatable:?? ~
??????????? loggable:?????? ~

or in XML::

??? <!-- app/config.xml -->
??? <container xmlns:doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
??????? <stof_doctrine_extensions:config>
??????????? <stof_doctrine_extensions:class
??????????????? tree="MyBundle\TreeListener"
??????????????? timestampable="MyBundle\TimestampableListener"
??????????? />
??????? </stof_doctrine_extensions:config>
??? </container>

.. _DoctrineExtensions: http://github.com/l3pp4rd/DoctrineExtensions
.. _blog:?????????????? http://gediminasm.org/articles
.. _documentation:????? http://symfony.com/doc/current/reference/configuration/doctrine.html#configuration-overview
?

轉載于:https://blog.51cto.com/firehare/678735

總結

以上是生活随笔為你收集整理的Symfony2插件StofDoctrineExtensionsBundle的使用说明的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。