Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 335 lines (252 sloc) 11.823 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
5f5f5af @tobiassjosten Fixed minor typos
tobiassjosten authored
6 This bundle allows to easily use DoctrineExtensions_ in your Symfony2
70d12ec @stof Moved the documentation and the license to follow best practices
authored
7 project by configuring it through a ``ListenerManager`` and the DIC.
8
9 DoctrineExtensions's features
10 -----------------------------
11
0f52706 @dbu index.rst fix typo in list
dbu authored
12 - **Tree** - this extension automates the tree handling process and adds some tree specific functions on repository. (**closure**, **nestedset** or **materialized path**)
fba9b25 @dbu update feature list from DoctrineExtensions
dbu authored
13 - **Translatable** - gives you a very handy solution for translating records into diferent languages. Easy to setup, easier to use.
14 - **Sluggable** - urlizes your specified fields into single unique slug
15 - **Timestampable** - updates date fields on create, update and even property change.
945a119 @dbu adding support for the blameable extension (PR on gedmo repository pe…
dbu authored
16 - **Blameable** - updates string or assocation fields on create, update and even property change with a user name resp. reference.
fba9b25 @dbu update feature list from DoctrineExtensions
dbu authored
17 - **Loggable** - helps tracking changes and history of objects, also supports version managment.
18 - **Sortable** - makes any document or entity sortable
19 - **Translator** - explicit way to handle translations
20 - **Softdeleteable** - allows to implicitly remove records
21 - **Uploadable** - provides file upload handling in entity fields
28ae9ca @evertharmeling Updated doc
evertharmeling authored
22 - **Reference Integrity** - provides reference integrity for MongoDB, supports 'nullify' and 'restrict'
70d12ec @stof Moved the documentation and the license to follow best practices
authored
23
b33f313 @stof Added a message about XML mapping in the doc
authored
24 All these extensions can be nested together. And most already use only
70d12ec @stof Moved the documentation and the license to follow best practices
authored
25 annotations without interface requirement to not to aggregate the
26 entity itself and has implemented proper caching for metadata.
27
7239997 @BraisGabin Changed the DoctrineExtesions' official documentation's uri.
BraisGabin authored
28 See the official documentation_ for more details.
70d12ec @stof Moved the documentation and the license to follow best practices
authored
29
30 Installation
31 ============
32
a902f98 @jrobeson update install instructions for symfony 2.1
jrobeson authored
33 Add stof/doctrine-extensions-bundle to composer.json
eec7641 @weaverryan Adding the bin/vendor method for installation
weaverryan authored
34 -----------------------------
35
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
36 .. code-block:: json
70d12ec @stof Moved the documentation and the license to follow best practices
authored
37
1b45fb8 @KingCrunch Updated to match Symfony2.1
KingCrunch authored
38 "require": {
39 "php": ">=5.3.2",
a902f98 @jrobeson update install instructions for symfony 2.1
jrobeson authored
40 "symfony/symfony": "~2.1",
1013290 @adrienbrault Fix typo in doc index
adrienbrault authored
41 "_comment": "your other packages",
1b45fb8 @KingCrunch Updated to match Symfony2.1
KingCrunch authored
42
a902f98 @jrobeson update install instructions for symfony 2.1
jrobeson authored
43 "stof/doctrine-extensions-bundle": "~1.1@dev",
1b45fb8 @KingCrunch Updated to match Symfony2.1
KingCrunch authored
44 }
70d12ec @stof Moved the documentation and the license to follow best practices
authored
45
46 Add DoctrineExtensionsBundle to your application kernel
47 -------------------------------------------------------
48
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
49 .. code-block:: php
70d12ec @stof Moved the documentation and the license to follow best practices
authored
50
51 // app/AppKernel.php
52 public function registerBundles()
53 {
54 return array(
55 // ...
10dc7f8 @stof Updated to the new bundle syntax
authored
56 new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
70d12ec @stof Moved the documentation and the license to follow best practices
authored
57 // ...
58 );
59 }
60
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
61 Add the extensions to your mapping
62 ----------------------------------
70d12ec @stof Moved the documentation and the license to follow best practices
authored
63
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
64 Some of the extensions uses their own entities to do their work. You need
65 to register their mapping in Doctrine when you want to use them.
b33f313 @stof Added a message about XML mapping in the doc
authored
66
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
67 .. code-block:: yaml
70d12ec @stof Moved the documentation and the license to follow best practices
authored
68
06f42bf @mdpatrick Missing a subdirectory in doc comment
mdpatrick authored
69 # app/config/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
70 doctrine:
71 orm:
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
72 entity_managers:
73 default:
74 mappings:
75 gedmo_translatable:
76 type: annotation
77 prefix: Gedmo\Translatable\Entity
ecc1048 @KingCrunch Took me some time to find the issue, after I upgraded to Symfony2.1 :)
KingCrunch authored
78 dir: "%kernel.root_dir%/../vendor/gedmo/doctrine-extensions/lib/Gedmo/Translatable/Entity"
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
79 alias: GedmoTranslatable # this one is optional and will default to the name set for the mapping
36356b1 @stof Added the is_bundle flag explicitly
authored
80 is_bundle: false
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
81 gedmo_translator:
82 type: annotation
83 prefix: Gedmo\Translator\Entity
ecc1048 @KingCrunch Took me some time to find the issue, after I upgraded to Symfony2.1 :)
KingCrunch authored
84 dir: "%kernel.root_dir%/../vendor/gedmo/doctrine-extensions/lib/Gedmo/Translator/Entity"
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
85 alias: GedmoTranslator # this one is optional and will default to the name set for the mapping
36356b1 @stof Added the is_bundle flag explicitly
authored
86 is_bundle: false
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
87 gedmo_loggable:
88 type: annotation
89 prefix: Gedmo\Loggable\Entity
ecc1048 @KingCrunch Took me some time to find the issue, after I upgraded to Symfony2.1 :)
KingCrunch authored
90 dir: "%kernel.root_dir%/../vendor/gedmo/doctrine-extensions/lib/Gedmo/Loggable/Entity"
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
91 alias: GedmoLoggable # this one is optional and will default to the name set for the mapping
36356b1 @stof Added the is_bundle flag explicitly
authored
92 is_bundle: false
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
93 gedmo_tree:
94 type: annotation
95 prefix: Gedmo\Tree\Entity
ecc1048 @KingCrunch Took me some time to find the issue, after I upgraded to Symfony2.1 :)
KingCrunch authored
96 dir: "%kernel.root_dir%/../vendor/gedmo/doctrine-extensions/lib/Gedmo/Tree/Entity"
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
97 alias: GedmoTree # this one is optional and will default to the name set for the mapping
36356b1 @stof Added the is_bundle flag explicitly
authored
98 is_bundle: false
70d12ec @stof Moved the documentation and the license to follow best practices
authored
99
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
100 .. note::
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
101
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
102 If you are using the short syntax for the ORM configuration, the `mappings`
103 key is directly under `orm:`
352ba3a @stof Added the Translatable and Timestampable behaviors for mongodb
authored
104
b33f313 @stof Added a message about XML mapping in the doc
authored
105 .. note::
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
106
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
107 If you are using several entity managers, take care to register the entities
108 for the right ones.
dededab @stof Added a note about disabling the mapping of the bundle when using aut…
authored
109
a549c48 @stof [BC Break] Removed the entities from the bundle
authored
110 .. note::
111
112 The mapping for MongoDB is similar. The ODM documents are in the `Document`
113 subnamespace of each extension instead of `Entity`.
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
114
5a6d63d @igorw add some docs for softdeleteable usage
igorw authored
115 Enable the softdeleteable filter
116 --------------------------------
117
118 If you want to use the SoftDeleteable behavior, you have to enable the
119 doctrine filter.
120
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
121 .. code-block:: yaml
5a6d63d @igorw add some docs for softdeleteable usage
igorw authored
122
123 # app/config/config.yml
124 doctrine:
125 orm:
126 entity_managers:
127 default:
128 filters:
129 softdeleteable:
130 class: Gedmo\SoftDeleteable\Filter\SoftDeleteableFilter
131 enabled: true
132
133 .. note::
134
439c0ce @igorw fix mention of mappings => filters in doc
igorw authored
135 If you are using the short syntax for the ORM configuration, the `filters`
5a6d63d @igorw add some docs for softdeleteable usage
igorw authored
136 key is directly under `orm:`
137
138 .. note::
139
439c0ce @igorw fix mention of mappings => filters in doc
igorw authored
140 If you are using several entity managers, take care to register the filter
5a6d63d @igorw add some docs for softdeleteable usage
igorw authored
141 for the right ones.
142
143 To disable the behaviour, e.g. for admin users who may see deleted items,
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
144 disable the filter. Here is an example:
145
146 .. code-block:: php
5a6d63d @igorw add some docs for softdeleteable usage
igorw authored
147
148 $filters = $em->getFilters();
149 $filters->disable('softdeleteable');
150
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
151 Using Uploadable extension
152 --------------------------
153
154 If you want to use the Uploadable extension, first read the documentation in DoctrineExtensions. Once everything is
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
155 ready, use the form component as usual. Then, after you verify the form is valid, do the following:
156
157 .. code-block:: php
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
158
159 $document = new Document();
160 $form = $this->createFormBuilder($document)
161 ->add('name')
162 ->add('myFile')
163 ->getForm()
164 ;
165
166 if ($this->getRequest()->getMethod() === 'POST') {
77f4dcf @Green-Cat Updates Uploadable example for symfony 2.4
Green-Cat authored
167 $form->bind($this->getRequest());
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
168
169 if ($form->isValid()) {
77f4dcf @Green-Cat Updates Uploadable example for symfony 2.4
Green-Cat authored
170 $em = $this->getDoctrine()->getManager();
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
171
172 $em->persist($document);
173
174 $uploadableManager = $this->get('stof_doctrine_extensions.uploadable.manager');
175
176 // Here, "getMyFile" returns the "UploadedFile" instance that the form bound in your $myFile property
177 $uploadableManager->markEntityToUpload($document, $document->getMyFile());
178
179 $em->flush();
180
181 $this->redirect($this->generateUrl(...));
182 }
183 }
184
185 return array('form' => $form->createView());
186
187 And that's it. The Uploadable extension handles the rest of the stuff. Remember to read its documentation!
188
70d12ec @stof Moved the documentation and the license to follow best practices
authored
189 Configure the bundle
190 ====================
191
192 You have to activate the extensions for each entity manager for which
36d3ccf @bobthecow Made listeners lazy-loaded
bobthecow authored
193 you want to enable the extensions. The id is the id of the DBAL
194 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…
authored
195 manager when using mongoDB.
196
197 This bundle needs a default locale used if the translation does not
198 exists in the asked language. If you don't provide it explicitly, it
199 will default to ``en``.
70d12ec @stof Moved the documentation and the license to follow best practices
authored
200
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
201 in YAML:
202
203 .. code-block:: yaml
70d12ec @stof Moved the documentation and the license to follow best practices
authored
204
df33197 @greg0ire Replaced occurences of app/config. with app/config/config.
greg0ire authored
205 # app/config/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
206 stof_doctrine_extensions:
aca5094 @stof Added a config option for the default locale as the default locale of…
authored
207 default_locale: en_US
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
208
209 # Only used if you activated the Uploadable extension
210 uploadable:
211 # Default file path: This is one of the three ways you can configure the path for the Uploadable extension
212 default_file_path: %kernel.root_dir%/../web/uploads
1094d04 @comfortablynumb [Uploadable] Added docs for the "default_file_info_class" option.
comfortablynumb authored
213
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
214 # Mime type guesser class: Optional. By default, we provide an adapter for the one present in the HttpFoundation component of Symfony
1094d04 @comfortablynumb [Uploadable] Added docs for the "default_file_info_class" option.
comfortablynumb authored
215 mime_type_guesser_class: Stof\DoctrineExtensionsBundle\Uploadable\MimeTypeGuesserAdapter
216
217 # Default file info class implementing FileInfoInterface: Optional. By default we provide a class which is prepared to receive an UploadedFile instance.
218 default_file_info_class: Stof\DoctrineExtensionsBundle\Uploadable\UploadedFileInfo
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
219 orm:
220 default: ~
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
221 mongodb:
222 default: ~
70d12ec @stof Moved the documentation and the license to follow best practices
authored
223
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
224 or in XML:
225
226 .. code-block:: xml
70d12ec @stof Moved the documentation and the license to follow best practices
authored
227
df33197 @greg0ire Replaced occurences of app/config. with app/config/config.
greg0ire authored
228 <!-- app/config/config.xml -->
f4cd642 @stof Updated xml namespaces
authored
229 <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…
authored
230 <stof_doctrine_extensions:config default-locale="en_US">
2faa4fd @stof Refactored the bundle to be able to to add the ODM version
authored
231 <stof_doctrine_extensions:orm>
232 <stof_doctrine_extensions:entity-manager id="default" />
233 </stof_doctrine_extensions:orm>
873069e @stof Added MongoDB ODM support (only sluggable is available for now)
authored
234 <stof_doctrine_extensions:mongodb>
235 <stof_doctrine_extensions:document-manager id="default" />
236 </stof_doctrine_extensions:mongodb>
10dc7f8 @stof Updated to the new bundle syntax
authored
237 </stof_doctrine_extensions:config>
70d12ec @stof Moved the documentation and the license to follow best practices
authored
238 </container>
239
4eb85cb @ornicar Load no extension by default. BC break, see bellow:
ornicar authored
240 Activate the extensions you want
241 ================================
242
243 By default the bundle does not attach any listener.
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
244 For each of your entity manager, declare the extensions you want to enable:
245
246 .. code-block:: yaml
4eb85cb @ornicar Load no extension by default. BC break, see bellow:
ornicar authored
247
df33197 @greg0ire Replaced occurences of app/config. with app/config/config.
greg0ire authored
248 # app/config/config.yml
4eb85cb @ornicar Load no extension by default. BC break, see bellow:
ornicar authored
249 stof_doctrine_extensions:
250 default_locale: en_US
251 orm:
252 default:
253 tree: true
254 timestampable: false # not needed: listeners are not enabled by default
255 other:
256 timestampable: true
257
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
258 or in XML:
259
260 .. code-block:: xml
4eb85cb @ornicar Load no extension by default. BC break, see bellow:
ornicar authored
261
df33197 @greg0ire Replaced occurences of app/config. with app/config/config.
greg0ire authored
262 <!-- app/config/config.xml -->
4eb85cb @ornicar Load no extension by default. BC break, see bellow:
ornicar authored
263 <container xmlns:doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
264 <stof_doctrine_extensions:config default-locale="en_US">
265 <stof_doctrine_extensions:orm>
266 <stof_doctrine_extensions:entity-manager
267 id="default"
268 tree="true"
269 timestampable="false"
270 />
271 <stof_doctrine_extensions:entity-manager
272 id="other"
273 timestampable="true"
274 />
275 </stof_doctrine_extensions:orm>
276 </stof_doctrine_extensions:config>
277 </container>
278
279 Same is available for MongoDB using ``document-manager`` in the XML
280 files instead of ``entity-manager``.
281
282 .. caution::
283
284 If you configure the listeners of an entity manager in several
285 config file the last one will be used. So you have to list all the
286 listeners you want to detach.
287
70d12ec @stof Moved the documentation and the license to follow best practices
authored
288 Use the DoctrineExtensions library
289 ==================================
290
7239997 @BraisGabin Changed the DoctrineExtesions' official documentation's uri.
BraisGabin authored
291 All explanations about this library are available on the official documentation_.
70d12ec @stof Moved the documentation and the license to follow best practices
authored
292
293 Advanced use
294 ============
295
873dd5d @stof Added the possibility to override the listeners
authored
296 Overriding the listeners
297 ------------------------
298
36d3ccf @bobthecow Made listeners lazy-loaded
bobthecow authored
299 You can change the listeners used by extending the Gedmo listeners (or
300 the listeners of the bundle for translations) and giving the class name
301 in the configuration.
873dd5d @stof Added the possibility to override the listeners
authored
302
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
303 in YAML:
304
305 .. code-block:: yaml
873dd5d @stof Added the possibility to override the listeners
authored
306
df33197 @greg0ire Replaced occurences of app/config. with app/config/config.
greg0ire authored
307 # app/config/config.yml
6fd574b @stof Updated to match the latest Symfony changes
authored
308 stof_doctrine_extensions:
873dd5d @stof Added the possibility to override the listeners
authored
309 class:
5bfb2fe @mgrinko Update index.rst
mgrinko authored
310 tree: MyBundle\TreeListener
ca2460e @stof Updated the listeners for the new way
authored
311 timestampable: MyBundle\TimestampableListener
945a119 @dbu adding support for the blameable extension (PR on gedmo repository pe…
dbu authored
312 blameable: ~
ca2460e @stof Updated the listeners for the new way
authored
313 sluggable: ~
314 translatable: ~
315 loggable: ~
d03b4c3 @igorw add support for SoftDeleteable
igorw authored
316 softdeleteable: ~
e570261 @comfortablynumb Added support for the Uploadable extension.
comfortablynumb authored
317 uploadable: ~
873dd5d @stof Added the possibility to override the listeners
authored
318
187ed07 @mhor Syntax highlighting on index.rst
mhor authored
319 or in XML:
320
321 .. code-block:: xml
873dd5d @stof Added the possibility to override the listeners
authored
322
df33197 @greg0ire Replaced occurences of app/config. with app/config/config.
greg0ire authored
323 <!-- app/config/config.xml -->
f4cd642 @stof Updated xml namespaces
authored
324 <container xmlns:doctrine_extensions="http://symfony.com/schema/dic/stof_doctrine_extensions">
873dd5d @stof Added the possibility to override the listeners
authored
325 <stof_doctrine_extensions:config>
ca2460e @stof Updated the listeners for the new way
authored
326 <stof_doctrine_extensions:class
327 tree="MyBundle\TreeListener"
328 timestampable="MyBundle\TimestampableListener"
329 />
873dd5d @stof Added the possibility to override the listeners
authored
330 </stof_doctrine_extensions:config>
331 </container>
332
8d723ae @aitboudad [DoctrineExtensions] updated links.
aitboudad authored
333 .. _DoctrineExtensions: https://github.com/Atlantic18/DoctrineExtensions
334 .. _documentation: https://github.com/Atlantic18/DoctrineExtensions/tree/master/doc/
Something went wrong with that request. Please try again.