Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 275 lines (210 sloc) 8.686 kb
70d12ec @stof Moved the documentation and the license to follow best practices
authored
1 Provides integration for DoctrineExtensions_ for your Symfony2 Project.
2
3 Features
4 ========
5
6 This bundle allows to easyly use DoctrineExtensions_ in your Symfony2
7 project by configuring it through a ``ListenerManager`` and the DIC.
8
9 DoctrineExtensions's features
10 -----------------------------
11
12 - Tree - this extension automates the tree handling process and adds
13 some tree specific functions on repository.
14 - Translatable - gives you a very handy solution for translating
15 records into diferent languages. Easy to setup, easier to use.
16 - Sluggable - urlizes your specified fields into single unique slug
17 - Timestampable - updates date fields on create, update and even
18 property change.
ed63a10 @julesbou added Loggable for ORM and ODM (ORM not tested)
julesbou authored
19 - Loggable - tracks your record changes and is able to manage versions.
70d12ec @stof Moved the documentation and the license to follow best practices
authored
20
21 All these extensions can be nested together. And most allready use only
22 annotations without interface requirement to not to aggregate the
23 entity itself and has implemented proper caching for metadata.
24
25 See the official blog_ for more details.
26
27 Installation
28 ============
29
30 Add DoctrineExtensions to your vendor dir
31 -----------------------------------------
32
33 ::
34
9af392b @stof Changed the vendor folder in the doc to avoid using the generic doctrine...
authored
35 git submodule add git://github.com/l3pp4rd/DoctrineExtensions.git vendor/gedmo-doctrine-extensions
70d12ec @stof Moved the documentation and the license to follow best practices
authored
36
10dc7f8 @stof Updated to the new bundle syntax
authored
37 Add DoctrineExtensionsBundle to your src/Bundle dir
38 ---------------------------------------------------
70d12ec @stof Moved the documentation and the license to follow best practices
authored
39
40 ::
41
98d1663 @Herzult Update documentation
Herzult authored
42 git submodule add git://github.com/stof/DoctrineExtensionsBundle.git vendor/bundles/Stof/DoctrineExtensionsBundle
70d12ec @stof Moved the documentation and the license to follow best practices
authored
43
10dc7f8 @stof Updated to the new bundle syntax
authored
44 Register the DoctrineExtensions and Stof namespaces
70d12ec @stof Moved the documentation and the license to follow best practices
authored
45 ---------------------------------------------------
46
47 ::
48
df3bf42 @stof Fixed doc
authored
49 // app/autoload.php
10dc7f8 @stof Updated to the new bundle syntax
authored
50 $loader->registerNamespaces(array(
98d1663 @Herzult Update documentation
Herzult authored
51 'Stof' => __DIR__.'/../vendor/bundles',
9af392b @stof Changed the vendor folder in the doc to avoid using the generic doctrine...
authored
52 'Gedmo' => __DIR__.'/../vendor/gedmo-doctrine-extensions/lib',
10dc7f8 @stof Updated to the new bundle syntax
authored
53 // your other namespaces
54 ));
70d12ec @stof Moved the documentation and the license to follow best practices
authored
55
56 Add DoctrineExtensionsBundle to your application kernel
57 -------------------------------------------------------
58
59 ::
60
61 // app/AppKernel.php
62 public function registerBundles()
63 {
64 return array(
65 // ...
10dc7f8 @stof Updated to the new bundle syntax
authored
66 new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
70d12ec @stof Moved the documentation and the license to follow best practices
authored
67 // ...
68 );
69 }
70
71 Add DoctrineExtensionsBundle to your mapping
72 --------------------------------------------
73
74 See the official documentation_ for details.
75
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
76 for ORM::
70d12ec @stof Moved the documentation and the license to follow best practices
authored
77
78 # app/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
79 doctrine:
80 orm:
81 mappings:
82 StofDoctrineExtensionsBundle: ~
83 # ... your others bundle
70d12ec @stof Moved the documentation and the license to follow best practices
authored
84
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
85 or for MongoDB ODM::
86
87 # app/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
88 doctrine_mongo_db:
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
89 mappings:
90 StofDoctrineExtensionsBundle: ~
91 # ... your others bundle
92
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
93 .. Note::
94
95 This is only necessary if you want to use the Translatable behavior.
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
96
70d12ec @stof Moved the documentation and the license to follow best practices
authored
97 Configure the bundle
98 ====================
99
100 You have to activate the extensions for each entity manager for which
36d3ccf @bobthecow Made listeners lazy-loaded
bobthecow authored
101 you want to enable the extensions. The id is the id of the DBAL
102 connection when using the ORM behaviors. It is the id of the document
aca5094 @stof Added a config option for the default locale as the default locale of th...
authored
103 manager when using mongoDB.
104
105 This bundle needs a default locale used if the translation does not
106 exists in the asked language. If you don't provide it explicitly, it
107 will default to ``en``.
70d12ec @stof Moved the documentation and the license to follow best practices
authored
108
109 in YAML::
110
111 # app/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
112 stof_doctrine_extensions:
aca5094 @stof Added a config option for the default locale as the default locale of th...
authored
113 default_locale: en_US
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
114 orm:
115 default: ~
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
116 mongodb:
117 default: ~
70d12ec @stof Moved the documentation and the license to follow best practices
authored
118
119 or in XML::
120
121 <!-- app/config.xml -->
f4cd642 @stof Updated xml namespaces
authored
122 <container xmlns:stof_doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
aca5094 @stof Added a config option for the default locale as the default locale of th...
authored
123 <stof_doctrine_extensions:config default-locale="en_US">
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
124 <stof_doctrine_extensions:orm>
125 <stof_doctrine_extensions:entity-manager id="default" />
126 </stof_doctrine_extensions:orm>
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
127 <stof_doctrine_extensions:mongodb>
128 <stof_doctrine_extensions:document-manager id="default" />
129 </stof_doctrine_extensions:mongodb>
10dc7f8 @stof Updated to the new bundle syntax
authored
130 </stof_doctrine_extensions:config>
70d12ec @stof Moved the documentation and the license to follow best practices
authored
131 </container>
132
133 Use the DoctrineExtensions library
134 ==================================
135
136 All explanations about this library are available on the official blog_
137
138 The default entity for translations is
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
139 ``Stof\DoctrineExtensionsBundle\Entity\Translation``. The default
140 document is ``Stof\DoctrineExtensionsBundle\Document\Translation``.
70d12ec @stof Moved the documentation and the license to follow best practices
authored
141
142 Creating your own translation entity
143 ------------------------------------
144
145 When you have a great number of entries for an entity you should create
146 a dedicated translation entity to have good performances. The only
147 difference when using it with Symfony2 is the mapped-superclass to use.
148
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
149 The simpliest way to do it is to copy the default translation entity
150 and just change the namespace and the class name.
151
152 Here is an example for the ORM::
70d12ec @stof Moved the documentation and the license to follow best practices
authored
153
154 // src/Application/MyBundle/Entity/MyTranslationEntity.php
155
156 namespace Application\MyBundle\Entity;
157
10dc7f8 @stof Updated to the new bundle syntax
authored
158 use Stof\DoctrineExtensionsBundle\Entity\AbstractTranslation
70d12ec @stof Moved the documentation and the license to follow best practices
authored
159
160 /**
161 * Application\MyBundle\Entity\MyTranslationEntity
162 *
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
163 * @orm:Entity(repositoryClass="Gedmo\Translatable\Entity\Repository\TranslationRepository")
164 * @orm:Table(
165 * name="ext_translations",
166 * indexes={@orm:index(name="translations_lookup_idx", columns={
df3bf42 @stof Fixed doc
authored
167 * "locale", "object_class", "foreign_key"
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
168 * })},
169 * uniqueConstraints={@orm:UniqueConstraint(name="lookup_unique_idx", columns={
df3bf42 @stof Fixed doc
authored
170 * "locale", "object_class", "foreign_key", "field"
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
171 * })}
172 * )
70d12ec @stof Moved the documentation and the license to follow best practices
authored
173 */
174 class TranslationEntity extends AbstractTranslation
175 {
176 }
177
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
178 Same is doable for the ODM.
179
70d12ec @stof Moved the documentation and the license to follow best practices
authored
180 You can also create your own repositoryClass by extending
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
181 ``Gedmo\Translatable\Entity\Repository\TranslationRepository`` or
182 ``Gedmo\Translatable\Document\Repository\TranslationRepository``
70d12ec @stof Moved the documentation and the license to follow best practices
authored
183
184 Advanced use
185 ============
186
187 Advanced configuration
188 ----------------------
189
190 By default the bundle attachs all 4 listeners to the entity managers
191 listed in the configuration. You can change this behavior by disabling
192 some of them explicitely.
193
194 in YAML::
195
196 # app/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
197 stof_doctrine_extensions:
aca5094 @stof Added a config option for the default locale as the default locale of th...
authored
198 default_locale: en_US
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
199 orm:
200 default:
201 tree: false
202 timestampable: true # not needed: listeners are enabled by default
203 other:
204 timestampable: false
70d12ec @stof Moved the documentation and the license to follow best practices
authored
205
206 or in XML::
207
208 <!-- app/config.xml -->
f4cd642 @stof Updated xml namespaces
authored
209 <container xmlns:doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
aca5094 @stof Added a config option for the default locale as the default locale of th...
authored
210 <stof_doctrine_extensions:config default-locale="en_US">
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
211 <stof_doctrine_extensions:orm>
212 <stof_doctrine_extensions:entity-manager
213 id="default"
214 tree="false"
215 timestampable="true"
216 />
217 <stof_doctrine_extensions:entity-manager
218 id="other"
219 timestampable="false"
220 />
221 </stof_doctrine_extensions:orm>
10dc7f8 @stof Updated to the new bundle syntax
authored
222 </stof_doctrine_extensions:config>
70d12ec @stof Moved the documentation and the license to follow best practices
authored
223 </container>
224
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
225 Same is available for MongoDB using ``document-manager`` in the XML
226 files instead of ``entity-manager``.
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
227
2894304 @stof Updated the doc
authored
228 .. Caution::
229
230 If you configure the listeners of an entity manager in several
231 config file the last one will be used. So you have to list all the
232 listeners you want to detach.
233
873dd5d @stof Added the possibility to override the listeners
authored
234 Overriding the listeners
235 ------------------------
236
36d3ccf @bobthecow Made listeners lazy-loaded
bobthecow authored
237 You can change the listeners used by extending the Gedmo listeners (or
238 the listeners of the bundle for translations) and giving the class name
239 in the configuration.
873dd5d @stof Added the possibility to override the listeners
authored
240
241 in YAML::
242
243 # app/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
244 stof_doctrine_extensions:
873dd5d @stof Added the possibility to override the listeners
authored
245 class:
246 orm:
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
247 tree: MyBundle\TreeListener
248 timestampable: MyBundle\TimestampableListener
249 sluggable: ~
250 translatable: ~
ed63a10 @julesbou added Loggable for ORM and ODM (ORM not tested)
julesbou authored
251 loggable: ~
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
252 mongodb:
253 sluggable: MyBundle\SluggableListener
873dd5d @stof Added the possibility to override the listeners
authored
254
255 or in XML::
256
257 <!-- app/config.xml -->
f4cd642 @stof Updated xml namespaces
authored
258 <container xmlns:doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
873dd5d @stof Added the possibility to override the listeners
authored
259 <stof_doctrine_extensions:config>
260 <stof_doctrine_extensions:class>
261 <stof_doctrine_extensions:orm
262 tree="MyBundle\TreeListener"
263 timestampable="MyBundle\TimestampableListener"
264 />
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
265 <stof_doctrine_extensions:mongodb
266 sluggable="MyBundle\SluggableListener"
267 />
873dd5d @stof Added the possibility to override the listeners
authored
268 </stof_doctrine_extensions:class>
269 </stof_doctrine_extensions:config>
270 </container>
271
70d12ec @stof Moved the documentation and the license to follow best practices
authored
272 .. _DoctrineExtensions: http://github.com/l3pp4rd/DoctrineExtensions
273 .. _blog: http://gediminasm.org/articles
274 .. _documentation: http://docs.symfony-reloaded.org/master/guides/doctrine/orm/overview.html
Something went wrong with that request. Please try again.