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
本文转自 firehare 51CTO博客，原文链接：http://blog.51cto.com/firehare/678735，如需转载请自行联系原作者
