Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 297 lines (221 sloc) 8.777 kb
70d12ec Christophe Coevoet 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.
19
20 All these extensions can be nested together. And most allready use only
21 annotations without interface requirement to not to aggregate the
22 entity itself and has implemented proper caching for metadata.
23
24 See the official blog_ for more details.
25
26 Installation
27 ============
28
29 Add DoctrineExtensions to your vendor dir
30 -----------------------------------------
31
32 ::
33
34 git submodule add git://github.com/l3pp4rd/DoctrineExtensions.git src/vendor/doctrine-extensions
35
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
36 Add DoctrineExtensionsBundle to your src/Bundle dir
37 ---------------------------------------------------
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
38
39 ::
40
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
41 git submodule add git://github.com/stof/DoctrineExtensionsBundle.git src/Stof/DoctrineExtensionsBundle
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
42
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
43 Register the DoctrineExtensions and Stof namespaces
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
44 ---------------------------------------------------
45
46 ::
47
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
48 // src/autoload.php
49 $loader->registerNamespaces(array(
50 'Stof' => __DIR__,
51 'Gedmo' => $vendorDir.'/doctrine-extensions/lib',
52 // your other namespaces
53 ));
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
54
55 Add DoctrineExtensionsBundle to your application kernel
56 -------------------------------------------------------
57
58 ::
59
60 // app/AppKernel.php
61 public function registerBundles()
62 {
63 return array(
64 // ...
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
65 new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
66 // ...
67 );
68 }
69
70 Add DoctrineExtensionsBundle to your mapping
71 --------------------------------------------
72
73 See the official documentation_ for details.
74
75 ::
76
77 # app/config.yml
78 doctrine.orm:
79 mappings:
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
80 StofDoctrineExtensionsBundle: ~
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
81 # ... your others bundle
82
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
83 .. Note::
84
85 This is only necessary if you want to use the Translatable behavior.
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
86
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
87 Configure the bundle
88 ====================
89
90 Register the default locale
91 ---------------------------
92
93 This bundle uses the session default_locale as the default locale used
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
94 if the translation does not exists in the asked language. So you have
95 to define it in the configuration file (Symfony2 define it to ``en`` by
96 default).
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
97
98 in YAML::
99
100 # app/config.yml
101 app.config:
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
102 session:
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
103 default_locale: en_US
104
105 or in XML::
106
107 <!-- app/config.xml -->
108 <container>
109 <app:config>
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
110 <app:session default-locale="en_US">
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
111 </app:config>
112 </container>
113
114 Activate the bundle
115 -------------------
116
117 You have to activate the extensions for each entity manager for which
118 you want to enable the extensions. The id is the one used in the ORM
119 configuration.
120
121 in YAML::
122
123 # app/config.yml
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
124 stof_doctrine_extensions.config:
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
125 orm:
126 default: ~
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
127 mongodb:
128 default: ~
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
129
130 or in XML::
131
132 <!-- app/config.xml -->
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
133 <container xmlns:stof_doctrine_extensions="http://www.symfony-project.org/schema/dic/stof_doctrine_extensions">
134 <stof_doctrine_extensions:config>
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
135 <stof_doctrine_extensions:orm>
136 <stof_doctrine_extensions:entity-manager id="default" />
137 </stof_doctrine_extensions:orm>
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
138 <stof_doctrine_extensions:mongodb>
139 <stof_doctrine_extensions:document-manager id="default" />
140 </stof_doctrine_extensions:mongodb>
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
141 </stof_doctrine_extensions:config>
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
142 </container>
143
144 .. Caution::
145
146 This uses the core.request event to register the listeners so you
147 have to enable the extensions manually in your commands as you have
148 no request. See the `Advanced use` paragraph for the explanations.
149
150 Use the DoctrineExtensions library
151 ==================================
152
153 All explanations about this library are available on the official blog_
154
155 The default entity for translations is
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
156 ``Stof\DoctrineExtensionsBundle\Entity\TranslationEntity``
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
157
158 Creating your own translation entity
159 ------------------------------------
160
161 When you have a great number of entries for an entity you should create
162 a dedicated translation entity to have good performances. The only
163 difference when using it with Symfony2 is the mapped-superclass to use.
164
165 ::
166
167 // src/Application/MyBundle/Entity/MyTranslationEntity.php
168
169 namespace Application\MyBundle\Entity;
170
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
171 use Stof\DoctrineExtensionsBundle\Entity\AbstractTranslation
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
172
173 /**
174 * Application\MyBundle\Entity\MyTranslationEntity
175 *
176 * @orm:Entity(repositoryClass="Gedmo\Translatable\Repository\TranslationRepository")
177 * @orm:Table(name="my_translation", indexes={
178 * @orm:index(name="lookup_idx", columns={"locale", "entity", "foreign_key", "field"})
179 * })
180 */
181 class TranslationEntity extends AbstractTranslation
182 {
183 }
184
185 You can also create your own repositoryClass by extending
186 ``Gedmo\Translatable\Repository\TranslationRepository``
187
188 Advanced use
189 ============
190
191 Advanced configuration
192 ----------------------
193
194 By default the bundle attachs all 4 listeners to the entity managers
195 listed in the configuration. You can change this behavior by disabling
196 some of them explicitely.
197
198 in YAML::
199
200 # app/config.yml
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
201 stof_doctrine_extensions.config:
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
202 orm:
203 default:
204 tree: false
205 timestampable: true # not needed: listeners are enabled by default
206 other:
207 timestampable: false
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
208
209 or in XML::
210
211 <!-- app/config.xml -->
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
212 <container xmlns:doctrine_extensions="http://www.symfony-project.org/schema/dic/stof_doctrine_extensions">
213 <stof_doctrine_extensions:config>
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
214 <stof_doctrine_extensions:orm>
215 <stof_doctrine_extensions:entity-manager
216 id="default"
217 tree="false"
218 timestampable="true"
219 />
220 <stof_doctrine_extensions:entity-manager
221 id="other"
222 timestampable="false"
223 />
224 </stof_doctrine_extensions:orm>
10dc7f8 Christophe Coevoet Updated to the new bundle syntax
authored
225 </stof_doctrine_extensions:config>
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
226 </container>
227
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
228 Same is available for MongoDB.
229
873dd5d Christophe Coevoet Added the possibility to override the listeners
authored
230 Overriding the listeners
231 ------------------------
232
233 You can change the listeners used by extending the Gedmo listeners and
234 giving the class name in the configuration.
235
236 in YAML::
237
238 # app/config.yml
239 stof_doctrine_extensions.config:
240 class:
241 orm:
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
242 tree: MyBundle\TreeListener
243 timestampable: MyBundle\TimestampableListener
244 sluggable: ~
245 translatable: ~
246 mongodb:
247 sluggable: MyBundle\SluggableListener
873dd5d Christophe Coevoet Added the possibility to override the listeners
authored
248
249 or in XML::
250
251 <!-- app/config.xml -->
252 <container xmlns:doctrine_extensions="http://www.symfony-project.org/schema/dic/stof_doctrine_extensions">
253 <stof_doctrine_extensions:config>
254 <stof_doctrine_extensions:class>
255 <stof_doctrine_extensions:orm
256 tree="MyBundle\TreeListener"
257 timestampable="MyBundle\TimestampableListener"
258 />
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
259 <stof_doctrine_extensions:mongodb
260 sluggable="MyBundle\SluggableListener"
261 />
873dd5d Christophe Coevoet Added the possibility to override the listeners
authored
262 </stof_doctrine_extensions:class>
263 </stof_doctrine_extensions:config>
264 </container>
265
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
266 Attaching and Removing listeners manually
267 -----------------------------------------
268
269 You can manage the listener with the ``ListenerManager``::
270
2faa4fd Christophe Coevoet Refactored the bundle to be able to to add the ODM version
authored
271 $lm = $container->get('stof_doctrine_extensions.orm.listener_manager');
873069e Christophe Coevoet Added MongoDB ODM support (only sluggable is available for now)
authored
272 $lm = $container->get('stof_doctrine_extensions.odm.mongodb.listener_manager');
70d12ec Christophe Coevoet Moved the documentation and the license to follow best practices
authored
273
274 The ``ListenerManager`` provides method to attach and remove each
275 listener.
276
277 ::
278
279 $lm->addTreeListener($em);
280 $lm->addSluggableListener($em);
281 $lm->addTimestampableListener($em);
282 $lm->addTranslationListener($em);
283
284 $lm->removeTreeListener($em)
285 $lm->removeSluggableListener($em)
286 $lm->removeTimestampableListener($em)
287 $lm->removeTranslationListener($em)
288
289 You can also attach or detach all the listeners::
290
291 $lm->addAllListeners($em);
292 $lm->removeAllListeners($em);
293
294 .. _DoctrineExtensions: http://github.com/l3pp4rd/DoctrineExtensions
295 .. _blog: http://gediminasm.org/articles
296 .. _documentation: http://docs.symfony-reloaded.org/master/guides/doctrine/orm/overview.html
Something went wrong with that request. Please try again.