Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 946 lines (703 sloc) 25.645 kB
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
1 FOSUserBundle Documentation
2 ===========================
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
3
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
4 The Symfony2 security component provides a flexible security framework that
5 allows you to load users from configuration, a database, or anywhere else
6 you can imagine. The FOSUserBundle builds on top of this to make it quick
7 and easy to store users in a database.
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
8
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
9 So, if you need to persist and fetch the users in your system to and from
10 a database, then you're in the right place.
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
11
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
12 ## Installation
ce97a24 @lsmith77 Added a warning about using default Controller and routing config files
lsmith77 authored
13
c1edb36 @lsmith77 updated warning notes on security aspects
lsmith77 authored
14
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
15 Installation is a quick (I promise) 5 step process:
c1edb36 @lsmith77 updated warning notes on security aspects
lsmith77 authored
16
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
17 1. Download FOSUserBundle
18 2. Configure the Autoloader
19 3. Enable the Bundle
20 4. Create your User class
21 5. Configure your application
ce97a24 @lsmith77 Added a warning about using default Controller and routing config files
lsmith77 authored
22
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
23 ### Step 1: Download FOSUserBundle
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
24
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
25 Ultimately, the FOSUserBundle files should be downloaded to the `vendor/bundles/FOS/UserBundle`
26 directory.
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
27
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
28 This can be done in several ways, depending on your preference. The first
29 method is the standard Symfony method for doing this
7681e45 @stof Updated the doc to use the new configuration
stof authored
30
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
31 **Using the vendors script**
32
33 Add the following lines in your `deps` file:
7681e45 @stof Updated the doc to use the new configuration
stof authored
34
affe193 @stof Updated the doc to use the ini syntax for the deps file
stof authored
35 [FOSUserBundle]
9bbaa6d @stof Updated the url of the repo
stof authored
36 git=git://github.com/FriendsOfSymfony/FOSUserBundle.git
44de64e @gimler fix deps code
gimler authored
37 target=bundles/FOS/UserBundle
f21beca @oyerli Updated the vendors script configuration, after the change in symfony…
oyerli authored
38
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
39 Now, run the vendors script to download the bundle:
f21beca @oyerli Updated the vendors script configuration, after the change in symfony…
oyerli authored
40
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
41 php bin/vendors install
7681e45 @stof Updated the doc to use the new configuration
stof authored
42
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
43 **Using submodules**
7681e45 @stof Updated the doc to use the new configuration
stof authored
44
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
45 If you prefer instead to use git submodules, the run the following:
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
46
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
47 ``` bash
48 $ git submodule add git://github.com/FriendsOfSymfony/FOSUserBundle.git vendor/bundles/FOS/UserBundle
49 $ git submodule update --init
50 ```
2d38f54 @stof Updated to follow the new bundle syntax and remove the Bundle namespace
stof authored
51
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
52 ### Step 2: Configure the Autoloader
2d38f54 @stof Updated to follow the new bundle syntax and remove the Bundle namespace
stof authored
53
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
54 Add the `FOS` namespace to your autoloader:
55
56 ``` php
57 <?php
58 // app/autoload.php
59
60 $loader->registerNamespaces(array(
61 // ...
62
63 'FOS' => __DIR__.'/../vendor/bundles',
64 ));
65 ```
66
67 ### Step3: Enable the bundle
68
69 Finally, enable the bundle in the kernel:
70
71 ``` php
72 <?php
73 // app/AppKernel.php
74
75 public function registerBundles()
76 {
77 $bundles = array(
78 // ...
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
79
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
80 new FOS\UserBundle\FOSUserBundle(),
2d38f54 @stof Updated to follow the new bundle syntax and remove the Bundle namespace
stof authored
81 );
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
82 }
83 ```
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
84
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
85 ### Step4: Create your User class
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
86
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
87 The goal of this bundle is to persist some `User` class to a database (MySql,
88 MongoDB, CouchDB, etc). Your first job, then, is to create the `User` class
89 for your application. This class can look and act however you want: add any
90 properties or methods you find useful. This is *your* `User` class.
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
91
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
92 This class has just two requirements, which allow it to take advantage of
93 all of the functionality in the FOSUserBundle:
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
94
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
95 1. It must extend one of the base `User` classes from the bundle
96 2. It must have an `id` field
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
97
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
98 In the following sections, you'll see examples of how your `User` class should
99 look, depending on how you're storing your users (Doctrine ORM, MongoDB ODM,
100 or CouchDB ODM).
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
101
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
102 Your `User` class can live inside any bundle in your application. For example,
103 if you work at "Acme" company, then you might create a bundle called `AcmeUserBundle`
104 and place your `User` class in it.
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
105
725bac1 @stof Updated the doc
stof authored
106 .. warning::
107
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
108 If you override the `__construct()` method in your `User` class, be sure
109 to call `parent::__construct()`, as the base `User` class depends on
110 this to initialize some fields.
725bac1 @stof Updated the doc
stof authored
111
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
112 **a) Doctrine ORM User class**
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
113
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
114 If you're persisting your users via the Doctrine ORM, then your `User` class
115 should live in the `Entity` namespace of your bundle and look like this to
116 start:
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
117
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
118 ``` php
119 <?php
120 // src/Acme/UserBundle/Entity/User.php
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
121
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
122 namespace Acme\UserBundle\Entity;
123 use FOS\UserBundle\Entity\User as BaseUser;
124 use Doctrine\ORM\Mapping as ORM;
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
125
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
126 /**
127 * @ORM\Entity
128 * @ORM\Table(name="fos_user")
129 */
130 class User extends BaseUser
131 {
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
132 /**
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
133 * @ORM\Id
134 * @ORM\Column(type="integer")
135 * @ORM\GeneratedValue(strategy="AUTO")
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
136 */
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
137 protected $id;
138
139 public function __construct()
be7bdbe @jmikola Remove ORM/ODM mappings for group/user id fields and update docs
jmikola authored
140 {
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
141 parent::__construct();
142 // your own logic
be7bdbe @jmikola Remove ORM/ODM mappings for group/user id fields and update docs
jmikola authored
143 }
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
144 }
145 ```
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
146
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
147 **Note**: `User` is a reserved keyword in SQL so you cannot use it as table name.
261cdbc @stof Changed the table names in the doc
stof authored
148
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
149 **b) MongoDB User class**
261cdbc @stof Changed the table names in the doc
stof authored
150
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
151 If you're persisting your users via the Doctrine MongoDB ODM, then your `User`
152 class should live in the `Document` namespace of your bundle and look like
153 this to start:
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
154
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
155 ``` php
156 <?php
157 // src/Acme/UserBundle/Document/User.php
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
158
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
159 namespace Acme\UserBundle\Document;
160 use FOS\UserBundle\Document\User as BaseUser;
161 use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoDB;
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
162
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
163 /**
164 * @MongoDB\Document
165 */
166 class User extends BaseUser
167 {
168 /** @MongoDB\Id(strategy="auto") */
169 protected $id;
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
170
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
171 public function __construct()
be7bdbe @jmikola Remove ORM/ODM mappings for group/user id fields and update docs
jmikola authored
172 {
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
173 parent::__construct();
174 // your own logic
be7bdbe @jmikola Remove ORM/ODM mappings for group/user id fields and update docs
jmikola authored
175 }
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
176 }
177 ```
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
178
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
179 **c) CouchDB User class**
8406c63 @beberlei Initial CouchDB support
beberlei authored
180
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
181 If you're persisting your users via the Doctrine CouchDB ODM, then your `User`
182 class should live in the `Document` namespace of your bundle and look like
183 this to start:
8406c63 @beberlei Initial CouchDB support
beberlei authored
184
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
185 ``` php
186 <?php
187 // src/Acme/UserBundle/Document/User.php
8406c63 @beberlei Initial CouchDB support
beberlei authored
188
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
189 namespace Acme\UserBundle\Document;
190 use FOS\UserBundle\Document\User as BaseUser;
191 use Doctrine\ODM\CouchDB\Mapping as CouchDB;
8406c63 @beberlei Initial CouchDB support
beberlei authored
192
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
193 /**
194 * @CouchDB\Document
195 */
196 class User extends BaseUser
197 {
198 /** @CouchDB\Id */
199 protected $id;
200
201 public function __construct()
8406c63 @beberlei Initial CouchDB support
beberlei authored
202 {
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
203 parent::__construct();
204 // your own logic
8406c63 @beberlei Initial CouchDB support
beberlei authored
205 }
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
206 }
207 ```
208
209 ### Step 5: Configure your project
8406c63 @beberlei Initial CouchDB support
beberlei authored
210
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
211 Now that you've activated the bundle and created your `User` class, the
212 final step is to configure to work with the bundle.
213
214 * Cover the import of the routes
215 * Cover the security.yml setup, including with the user provider
216
217 **Note**:
3005ef2 @jmikola [issue-17] Fix docs typo and revise project configuration to include …
jmikola authored
218
219 The UserBundle works with the Symfony Security Component, so make sure that is
7681e45 @stof Updated the doc to use the new configuration
stof authored
220 enabled in your kernel and in your project's configuration. A working security
221 configuration using FOSUserBundle is available at the end of the doc.
3005ef2 @jmikola [issue-17] Fix docs typo and revise project configuration to include …
jmikola authored
222
8f545bb @stof Added doc about the unsecured routes
stof authored
223 The login form and all the routes used to create a user and reset the password
38ba482 @stof Updated the doc
stof authored
224 have to be available to unauthenticated users but using the same firewall as
225 the pages you want to securize with the bundle. Assuming you import the
7681e45 @stof Updated the doc to use the new configuration
stof authored
226 registration.xml routing file with the ``/register`` prefix and resetting.xml
227 with the ``/resetting`` prefix they will be::
8f545bb @stof Added doc about the unsecured routes
stof authored
228
229 /login
7681e45 @stof Updated the doc to use the new configuration
stof authored
230 /register/
231 /register/check-email
232 /register/confirm/{token}
233 /register/confirmed
234 /resetting/request
235 /resetting/send-email
236 /resetting/check-email
237 /resetting/reset/{token}
3005ef2 @jmikola [issue-17] Fix docs typo and revise project configuration to include …
jmikola authored
238
c309cf6 @stof Updated the doc
stof authored
239 The above example assumes an ORM configuration, but the ``mappings``
240 configuration block would be the same for MongoDB ODM.
3005ef2 @jmikola [issue-17] Fix docs typo and revise project configuration to include …
jmikola authored
241
1b47e41 @weaverryan WIP - Beginning to refactor the docs
weaverryan authored
242 .. note::
243
244 You need to activate SwiftmailerBundle to be able to use the functionalities
245 using emails (confirmation of the account, resetting of the password).
246 See the `Emails` section to know how using another mailer.
247
36220ea @lsmith77 updated mininum config documentation to include provider_key
lsmith77 authored
248 Minimal configuration
249 ---------------------
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
250
36220ea @lsmith77 updated mininum config documentation to include provider_key
lsmith77 authored
251 At a minimum, your configuration must define your DB driver ("orm" or "mongodb"),
7681e45 @stof Updated the doc to use the new configuration
stof authored
252 a User class and the firewall name. The firewall name matches the key in the
253 firewall configuration that is used for users with the controllers of the
254 bundle.
36220ea @lsmith77 updated mininum config documentation to include provider_key
lsmith77 authored
255
7681e45 @stof Updated the doc to use the new configuration
stof authored
256 The firewall name needs to be configured so that the FOSUserBundle can determine
257 against which firewall the user should be authenticated after activating the
258 account for instance. This means that out of the box FOSUserBundle only supports
c309cf6 @stof Updated the doc
stof authored
259 being used for a single firewall, though with a custom Controller this
260 limitation can be circumvented.
fcc295c @lsmith77 fixed docs for provider_key
lsmith77 authored
261
994952f @stof Renamed provider_key to firewall_name to be more explicit
stof authored
262 For example for a security configuration like the following the firewall_name
c309cf6 @stof Updated the doc
stof authored
263 would have to be set to "main", as shown in the proceeding examples:
36220ea @lsmith77 updated mininum config documentation to include provider_key
lsmith77 authored
264
265 ::
266
aa98b52 @gimler fix doc security.yml instate of config.yml
gimler authored
267 # app/config/security.yml
88f1ab1 @stof Updated doc
stof authored
268 security:
36220ea @lsmith77 updated mininum config documentation to include provider_key
lsmith77 authored
269 providers:
270 fos_userbundle:
271 id: fos_user.user_manager
272
273 firewalls:
274 main:
275 form_login:
276 provider: fos_userbundle
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
277
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
278 ORM
279 ~~~
280
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
281 In YAML:
282
283 ::
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
284
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
285 # app/config/config.yml
88f1ab1 @stof Updated doc
stof authored
286 fos_user:
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
287 db_driver: orm
994952f @stof Renamed provider_key to firewall_name to be more explicit
stof authored
288 firewall_name: main
7681e45 @stof Updated the doc to use the new configuration
stof authored
289 user_class: MyProject\MyBundle\Entity\User
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
290
291 Or if you prefer XML:
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
292
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
293 ::
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
294
295 # app/config/config.xml
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
296
7681e45 @stof Updated the doc to use the new configuration
stof authored
297 <fos_user:config
298 db-driver="orm"
299 firewall-name="main"
300 user-class="MyProject\MyBundle\Entity\User"
301 />
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
302
8406c63 @beberlei Initial CouchDB support
beberlei authored
303 MongoDB
304 ~~~~~~~
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
305
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
306 In YAML:
307
308 ::
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
309
310 # app/config/config.yml
88f1ab1 @stof Updated doc
stof authored
311 fos_user:
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
312 db_driver: mongodb
994952f @stof Renamed provider_key to firewall_name to be more explicit
stof authored
313 firewall_name: main
7681e45 @stof Updated the doc to use the new configuration
stof authored
314 user_class: MyProject\MyBundle\Document\User
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
315
316 Or if you prefer XML:
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
317
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
318 ::
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
319
320 # app/config/config.xml
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
321
7681e45 @stof Updated the doc to use the new configuration
stof authored
322 <fos_user:config
323 db-driver="mongodb"
324 firewall-name="main">
325 user-class="MyProject\MyBundle\Document\User"
326 />
bdfa697 @schmittjoh refactored user extension
schmittjoh authored
327
8406c63 @beberlei Initial CouchDB support
beberlei authored
328 CouchDB
329 ~~~~~~~
330
331 In YAML:
332
333 ::
334
335 # app/config/config.yml
336 fos_user:
337 db_driver: couchdb
338 firewall_name: main
99fc053 @stof Tweaked the previous merge
stof authored
339 user_class: MyProject\MyBundle\Document\User
8406c63 @beberlei Initial CouchDB support
beberlei authored
340
341 Or if you prefer XML:
342
343 ::
344
345 # app/config/config.xml
346
c50ca58 @beberlei Fix README references to user_class with CouchDB
beberlei authored
347 <fos_user:config
348 db-driver="couchdb"
99fc053 @stof Tweaked the previous merge
stof authored
349 firewall-name="main"
350 user-class="MyProject\MyBundle\Document\User"
c50ca58 @beberlei Fix README references to user_class with CouchDB
beberlei authored
351 />
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
352
353 Add authentication routes
354 -------------------------
355
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
356 If you want ready to use login and logout pages, include the built-in
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
357 routes:
358
359 ::
360
361 # app/config/routing.yml
362 fos_user_security:
72a97d8 @stof Cosmetic tweaks of previous commit
stof authored
363 resource: "@FOSUserBundle/Resources/config/routing/security.xml"
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
364
32b78ab @dancannon Fixed routing config
dancannon authored
365 fos_user_profile:
7681e45 @stof Updated the doc to use the new configuration
stof authored
366 resource: "@FOSUserBundle/Resources/config/routing/profile.xml"
367 prefix: /profile
368
32b78ab @dancannon Fixed routing config
dancannon authored
369 fos_user_register:
7681e45 @stof Updated the doc to use the new configuration
stof authored
370 resource: "@FOSUserBundle/Resources/config/routing/registration.xml"
371 prefix: /register
372
32b78ab @dancannon Fixed routing config
dancannon authored
373 fos_user_resetting:
7681e45 @stof Updated the doc to use the new configuration
stof authored
374 resource: "@FOSUserBundle/Resources/config/routing/resetting.xml"
375 prefix: /resetting
376
32b78ab @dancannon Fixed routing config
dancannon authored
377 fos_user_change_password:
7681e45 @stof Updated the doc to use the new configuration
stof authored
378 resource: "@FOSUserBundle/Resources/config/routing/change_password.xml"
379 prefix: /change-password
4c74c05 @stof Updated the doc
stof authored
380
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
381 ::
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
382
383 # app/config/routing.xml
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
384
cb4614e @stof Updated remaining missing Bundle
stof authored
385 <import resource="@FOSUserBundle/Resources/config/routing/security.xml"/>
7681e45 @stof Updated the doc to use the new configuration
stof authored
386 <import resource="@FOSUserBundle/Resources/config/routing/profile.xml" prefix="/profile" />
387 <import resource="@FOSUserBundle/Resources/config/routing/registration.xml" prefix="/register" />
388 <import resource="@FOSUserBundle/Resources/config/routing/resetting.xml" prefix="/resetting" />
389 <import resource="@FOSUserBundle/Resources/config/routing/change_password.xml" prefix="/change-password" />
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
390
7681e45 @stof Updated the doc to use the new configuration
stof authored
391 You now can login at http://app.com/app_dev.php/login
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
392
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
393 Command line
394 ============
395
7681e45 @stof Updated the doc to use the new configuration
stof authored
396 FOSUserBundle provides command line utilities to help manage your
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
397 application users.
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
398
399 Create user
400 -----------
401
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
402 This command creates a new user::
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
403
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
404 $ php app/console fos:user:create username email password
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
405
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
406 If you don't provide the required arguments, a interactive prompt will
407 ask them to you::
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
408
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
409 $ php app/console fos:user:create
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
410
411 Promote user as a super administrator
412 -------------------------------------
413
9e3afbd @jmikola Updated documentation, fixed spelling errors and revised examples
jmikola authored
414 This command promotes a user as a super administrator::
415
416 $ php app/console fos:user:promote
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
417
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
418 User manager service
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
419 ====================
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
420
7681e45 @stof Updated the doc to use the new configuration
stof authored
421 FOSUserBundle works with both ORM and ODM. To make it possible, it wraps
422 all the operation on users in a UserManager. The user manager is a service
423 of the container.
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
424
425 If you configure the db_driver to orm, this service is an instance of
2d38f54 @stof Updated to follow the new bundle syntax and remove the Bundle namespace
stof authored
426 ``FOS\UserBundle\Entity\UserManager``.
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
427
8406c63 @beberlei Initial CouchDB support
beberlei authored
428 If you configure the db_driver to mongodb, this service is an instance of
2d38f54 @stof Updated to follow the new bundle syntax and remove the Bundle namespace
stof authored
429 ``FOS\UserBundle\Document\UserManager``.
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
430
8406c63 @beberlei Initial CouchDB support
beberlei authored
431 If you configure the db_driver to couchdb, this service is an instance of
432 ``FOS\UserBundle\CouchDocument\UserManager``.
433
434 All these classes implement ``FOS\UserBundle\Model\UserManagerInterface``.
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
435
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
436 Access the user manager service
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
437 -------------------------------
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
438
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
439 If you want to manipulate users in a way that will work as well with
2c7fc4a @stof Fixed markup
stof authored
440 ORM and ODM, use the fos_user.user_manager service::
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
441
ddad94a @stof Updated the doc to reflect the current state of the bundle
stof authored
442 $userManager = $container->get('fos_user.user_manager');
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
443
7681e45 @stof Updated the doc to use the new configuration
stof authored
444 That's the way FOSUserBundle's internal controllers are built.
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
445
8406c63 @beberlei Initial CouchDB support
beberlei authored
446 Create a new user
447 -----------------
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
448
2c7fc4a @stof Fixed markup
stof authored
449 A new instance of your User class can be created by the user manager::
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
450
90e5c05 @lsmith77 some more user repository to manager fixes
lsmith77 authored
451 $user = $userManager->createUser();
8fbf0e9 @schmittjoh namespaced renamed to FOS/UserBundle, authentication provider fixed, …
schmittjoh authored
452
453 `$user` is now an Entity or a Document, depending on the configuration.
454
2a7f3ea @stof Made the flush optionnal in the ORM and ODM implementation
stof authored
455 Updating a User object
456 ----------------------
457
5acfe93 @stof Enabled the doctrine listener by default
stof authored
458 When creating or updating a User object you need to update the encoded password
459 and the canonical fields. To make it easier, the bundle comes with a Doctrine
460 listener handling this for you behind the scene.
2a7f3ea @stof Made the flush optionnal in the ORM and ODM implementation
stof authored
461
5acfe93 @stof Enabled the doctrine listener by default
stof authored
462 If you don't want to use the Doctrine listener, you can disable it. In this case
463 you will have to call the ``updateUser`` method of the user manager each time
464 you do a change in your entity.
02af59e @stof Added Doctrine listeners to handle the password encoding and the cano…
stof authored
465
466 In YAML:
467
468 ::
469
470 # app/config/config.yml
471 fos_user:
472 db_driver: orm
473 firewall_name: main
5acfe93 @stof Enabled the doctrine listener by default
stof authored
474 use_listener: false
7681e45 @stof Updated the doc to use the new configuration
stof authored
475 user_class: MyProject\MyBundle\Entity\User
02af59e @stof Added Doctrine listeners to handle the password encoding and the cano…
stof authored
476
477 Or if you prefer XML:
478
479 ::
480
481 # app/config/config.xml
482
7681e45 @stof Updated the doc to use the new configuration
stof authored
483 <fos_user:config
484 db-driver="orm"
485 firewall-name="main"
99fc053 @stof Tweaked the previous merge
stof authored
486 use-listener="false"
7681e45 @stof Updated the doc to use the new configuration
stof authored
487 user-class="MyProject\MyBundle\Entity\User"
488 />
02af59e @stof Added Doctrine listeners to handle the password encoding and the cano…
stof authored
489
5acfe93 @stof Enabled the doctrine listener by default
stof authored
490 .. note::
491
492 The default behavior is to flush the changes when calling this method. You
493 can disable the flush when using the ORM and the MongoDB implementations by
494 passing a second argument set to ``false``.
495
c309cf6 @stof Updated the doc
stof authored
496 Using groups
497 ============
498
8406c63 @beberlei Initial CouchDB support
beberlei authored
499 The bundle allows to optionally use groups. You need to explicitly
c309cf6 @stof Updated the doc
stof authored
500 enable it in your configuration by giving the Group class which must
501 implement ``FOS\UserBundle\Model\GroupInterface``.
502
503 In YAML:
504
505 ::
506
507 # app/config/config.yml
508 fos_user:
509 db_driver: orm
994952f @stof Renamed provider_key to firewall_name to be more explicit
stof authored
510 firewall_name: main
7681e45 @stof Updated the doc to use the new configuration
stof authored
511 user_class: MyProject\MyBundle\Entity\User
c309cf6 @stof Updated the doc
stof authored
512 group:
7681e45 @stof Updated the doc to use the new configuration
stof authored
513 group_class: MyProject\MyBundle\Entity\Group
c309cf6 @stof Updated the doc
stof authored
514
515 Or if you prefer XML:
516
517 ::
518
519 # app/config/config.xml
520
7681e45 @stof Updated the doc to use the new configuration
stof authored
521 <fos_user:config
522 db-driver="orm"
99fc053 @stof Tweaked the previous merge
stof authored
523 firewall-name="main"
7681e45 @stof Updated the doc to use the new configuration
stof authored
524 user-class="MyProject\MyBundle\Entity\User"
525 >
526 <fos_user:group group-class model="MyProject\MyBundle\Entity\Group" />
c309cf6 @stof Updated the doc
stof authored
527 </fos_user:config>
528
529 The Group class
530 ---------------
531
532 The simpliest way is to extend the mapped superclass provided by the
533 bundle.
534
535 ORM
536 ~~~
537
538 ::
539
540 // src/MyProject/MyBundle/Entity/Group.php
541
ee622d8 @oyerli Added "<?php" to the User.php and Group.php examples to indicate thes…
oyerli authored
542 <?php
c309cf6 @stof Updated the doc
stof authored
543 namespace MyProject\MyBundle\Entity;
544 use FOS\UserBundle\Entity\Group as BaseGroup;
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
545 use Doctrine\ORM\Mapping as ORM;
c309cf6 @stof Updated the doc
stof authored
546
547 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
548 * @ORM\Entity
549 * @ORM\Table(name="fos_group")
c309cf6 @stof Updated the doc
stof authored
550 */
551 class Group extends BaseGroup
552 {
430ee35 @stof Added a warning about the constructor overwriting and fixed the Group…
stof authored
553 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
554 * @ORM\Id
555 * @ORM\Column(type="integer")
556 * @ORM\generatedValue(strategy="AUTO")
430ee35 @stof Added a warning about the constructor overwriting and fixed the Group…
stof authored
557 */
558 protected $id;
c309cf6 @stof Updated the doc
stof authored
559 }
560
261cdbc @stof Changed the table names in the doc
stof authored
561 .. note::
562
563 ``Group`` is also a reserved keyword in SQL so it cannot be used either.
564
8406c63 @beberlei Initial CouchDB support
beberlei authored
565 MongoDB
566 ~~~~~~~
c309cf6 @stof Updated the doc
stof authored
567
568 ::
569
570 // src/MyProject/MyBundle/Document/Group.php
571
ee622d8 @oyerli Added "<?php" to the User.php and Group.php examples to indicate thes…
oyerli authored
572 <?php
c309cf6 @stof Updated the doc
stof authored
573 namespace MyProject\MyBundle\Document;
574 use FOS\UserBundle\Document\Group as BaseGroup;
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
575 use Doctrine\ODM\MongoDB\Mapping as MongoDB;
c309cf6 @stof Updated the doc
stof authored
576
577 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
578 * @MongoDB\Document
c309cf6 @stof Updated the doc
stof authored
579 */
580 class Group extends BaseGroup
581 {
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
582 /** @MongoDB\Id(strategy="auto") */
430ee35 @stof Added a warning about the constructor overwriting and fixed the Group…
stof authored
583 protected $id;
c309cf6 @stof Updated the doc
stof authored
584 }
585
8406c63 @beberlei Initial CouchDB support
beberlei authored
586 CouchDB
587 ~~~~~~~
588
589 ::
590
99fc053 @stof Tweaked the previous merge
stof authored
591 // src/MyProject/MyBundle/Document/Group.php
8406c63 @beberlei Initial CouchDB support
beberlei authored
592
99fc053 @stof Tweaked the previous merge
stof authored
593 namespace MyProject\MyBundle\Document;
8406c63 @beberlei Initial CouchDB support
beberlei authored
594 use FOS\UserBundle\Document\Group as BaseGroup;
595 use Doctrine\ODM\CouchDB\Mapping as MongoDB;
596
597 /**
598 * @CouchDB\Document
599 */
600 class Group extends BaseGroup
601 {
602 /** @CouchDB\Id */
603 protected $id;
604 }
605
c309cf6 @stof Updated the doc
stof authored
606 Defining the relation
607 ---------------------
608
609 The next step is to map the relation in your User class.
610
611 ORM
612 ~~~
613
614 ::
615
616 // src/MyProject/MyBundle/Entity/User.php
617
ee622d8 @oyerli Added "<?php" to the User.php and Group.php examples to indicate thes…
oyerli authored
618 <?php
c309cf6 @stof Updated the doc
stof authored
619 namespace MyProject\MyBundle\Entity;
620 use FOS\UserBundle\Entity\User as BaseUser;
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
621 use Doctrine\ORM\Mapping as ORM;
c309cf6 @stof Updated the doc
stof authored
622
623 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
624 * @ORM\Entity
625 * @ORM\Table(name="fos_user")
c309cf6 @stof Updated the doc
stof authored
626 */
627 class User extends BaseUser
628 {
629 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
630 * @ORM\Id
631 * @ORM\Column(type="integer")
632 * @ORM\generatedValue(strategy="AUTO")
c309cf6 @stof Updated the doc
stof authored
633 */
634 protected $id;
635
636 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
637 * @ORM\ManyToMany(targetEntity="MyProject\MyBundle\Entity\Group")
638 * @ORM\JoinTable(name="fos_user_user_group",
639 * joinColumns={@ORM\JoinColumn(name="user_id", referencedColumnName="id")},
640 * inverseJoinColumns={@ORM\JoinColumn(name="group_id", referencedColumnName="id")}
c309cf6 @stof Updated the doc
stof authored
641 * )
642 */
643 protected $groups;
644 }
645
8406c63 @beberlei Initial CouchDB support
beberlei authored
646 MongoDB
647 ~~~~~~~
c309cf6 @stof Updated the doc
stof authored
648
649 ::
650
651 // src/MyProject/MyBundle/Document/User.php
652
ee622d8 @oyerli Added "<?php" to the User.php and Group.php examples to indicate thes…
oyerli authored
653 <?php
c309cf6 @stof Updated the doc
stof authored
654 namespace MyProject\MyBundle\Document;
655 use FOS\UserBundle\Document\User as BaseUser;
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
656 use Doctrine\ODM\MongoDB\Mapping as MongoDB;
c309cf6 @stof Updated the doc
stof authored
657
658 /**
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
659 * @MongoDB\Document
c309cf6 @stof Updated the doc
stof authored
660 */
661 class User extends BaseUser
662 {
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
663 /** @MongoDB\Id(strategy="auto") */
c309cf6 @stof Updated the doc
stof authored
664 protected $id;
665
4aabe89 @stof Updated the doc for the new annotation syntax
stof authored
666 /** @MongoDB\ReferenceMany(targetDocument="MyProject\MyBundle\Document\Group") */
c309cf6 @stof Updated the doc
stof authored
667 protected $groups;
668 }
669
8406c63 @beberlei Initial CouchDB support
beberlei authored
670 CouchDB
671 ~~~~~~~
672
673 ::
674
99fc053 @stof Tweaked the previous merge
stof authored
675 // src/MyProject/MyBundle/Document/User.php
8406c63 @beberlei Initial CouchDB support
beberlei authored
676
99fc053 @stof Tweaked the previous merge
stof authored
677 namespace MyProject\MyBundle\Document;
8406c63 @beberlei Initial CouchDB support
beberlei authored
678 use FOS\UserBundle\Document\User as BaseUser;
679 use Doctrine\ODM\CouchDB\Mapping as CouchDB;
680
681 /**
682 * @CouchDB\Document
683 */
684 class User extends BaseUser
685 {
686 /** @CouchDB\Id */
687 protected $id;
688
689 /** @CouchDB\ReferenceMany(targetDocument="MyProject\MyBundle\Document\Group") */
690 protected $groups;
691 }
692
c309cf6 @stof Updated the doc
stof authored
693 Enabling the routing for the GroupController
694 --------------------------------------------
695
696 You can also the group.xml file to use the builtin controller to manipulate the
697 groups.
698
c629b6d @stof Tweaked the doc
stof authored
699 Configuration example
700 =====================
701
702 This section provides a working configuration for the bundle and the security.
703
704 FOSUserBundle configuration
705 ---------------------------
706
707 ::
708
709 # app/config/config.yml
710 fos_user:
711 db_driver: orm
712 firewall_name: main
7681e45 @stof Updated the doc to use the new configuration
stof authored
713 user_class: MyProject\MyBundle\Entity\User
c629b6d @stof Tweaked the doc
stof authored
714
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
715 Security configuration
716 ----------------------
717
c629b6d @stof Tweaked the doc
stof authored
718 ::
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
719
720 # app/config/security.yml
721 security:
722 providers:
723 fos_userbundle:
724 id: fos_user.user_manager
725
726 firewalls:
725bac1 @stof Updated the doc
stof authored
727 # Disabling the security for the web debug toolbar, the profiler and Assetic.
728 dev:
729 pattern: ^/(_(profiler|wdt)|css|images|js)/
730 security: false
731
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
732 main:
733 pattern: .*
209d11b @riker09 Changed 'form-login' to 'form_login'
riker09 authored
734 form_login:
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
735 provider: fos_userbundle
736 login_path: /login
737 use_forward: false
738 check_path: /login_check
739 failure_path: null
740 logout: true
741 anonymous: true
742
743 access_control:
c629b6d @stof Tweaked the doc
stof authored
744 # URL of FOSUserBundle which need to be available to anonymous users
a484bba @stof Updated the doc to the new syntax for the RequestMatcher
stof authored
745 - { path: ^/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }
7681e45 @stof Updated the doc to use the new configuration
stof authored
746 - { path: ^/register, role: IS_AUTHENTICATED_ANONYMOUSLY }
747 - { path: ^/resetting, role: IS_AUTHENTICATED_ANONYMOUSLY }
c629b6d @stof Tweaked the doc
stof authored
748 # Secured part of the site
749 # This config requires being logged for the whole site and having the admin role for the admin part.
750 # Change these rules to adapt them to your needs
a484bba @stof Updated the doc to the new syntax for the RequestMatcher
stof authored
751 - { path: ^/admin/, role: ROLE_ADMIN }
752 - { path: ^/.*, role: ROLE_USER }
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
753
754 role_hierarchy:
755 ROLE_ADMIN: ROLE_USER
5a92208 @oyerli Changed ROLE_SUPERADMIN to ROLE_SUPER_ADMIN in order to be consistent…
oyerli authored
756 ROLE_SUPER_ADMIN: ROLE_ADMIN
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
757
c629b6d @stof Tweaked the doc
stof authored
758 Replacing some part by your own implementation
759 ==============================================
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
760
725bac1 @stof Updated the doc
stof authored
761 User Manager
762 ------------
763
764 You can replace the default implementation of the user manager by defining
765 a service implementing ``FOS\UserBundle\Model\UserManagerInterface`` and
766 setting its id in the configuration::
767
768 fos_user:
769 # ...
770 service:
771 user_manager: custom_user_manager_id
772
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
773 Templating
774 ----------
775
39b7693 @lsmith77 updated docs
lsmith77 authored
776 The template names are not configurable, however Symfony2 makes it possible
9b9eb2f @stof Updated for the framework change
stof authored
777 to extend a bundle by defining a template in the app/ directory.
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
778
725bac1 @stof Updated the doc
stof authored
779 For example ``vendor/bundles/FOS/UserBundle/Resources/views/Registration/register.html.twig``
780 can be replaced inside an application by putting a file with alternative content
781 in ``app/Resources/FOSUserBundle/views/Registration/register.html.twig``.
9b9eb2f @stof Updated for the framework change
stof authored
782
783 You could also create a bundle defined as child of FOSUserBundle and placing the
725bac1 @stof Updated the doc
stof authored
784 templates in it as ``src/Acme/ChildBundle/Resources/views/Registration/register.html.twig``.
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
785
38ba482 @stof Updated the doc
stof authored
786 You can use a different templating engine by configuring it but you will have to
787 create all the needed templates as only twig templates are provided.
788
7681e45 @stof Updated the doc to use the new configuration
stof authored
789 Controller
790 ----------
791
ba68da9 @stof Tweaked the doc about overwritting a controller
stof authored
792 Create a bundle defined as child of FOSUserBundle::
793
725bac1 @stof Updated the doc
stof authored
794 // src/Acme/ChildBundle/AcmeChildBundle.php
ba68da9 @stof Tweaked the doc about overwritting a controller
stof authored
795 <?php
796
725bac1 @stof Updated the doc
stof authored
797 namespace Acme\ChildBundle;
ba68da9 @stof Tweaked the doc about overwritting a controller
stof authored
798
799 use Symfony\Component\HttpKernel\Bundle\Bundle;
800
725bac1 @stof Updated the doc
stof authored
801 class AcmeChildBundle extends Bundle
ba68da9 @stof Tweaked the doc about overwritting a controller
stof authored
802 {
803 public function getParent()
804 {
805 return 'FOSUserBundle';
806 }
807 }
808
809 Then overwritting a controller is just a matter of creating a controller
725bac1 @stof Updated the doc
stof authored
810 with the same name in this bundle (e.g. ``Acme\ChildBundle\Controller\ProfileController``
ba68da9 @stof Tweaked the doc about overwritting a controller
stof authored
811 to overwrite the ProfileController provided by FOSUserBundle).
812 You can of course make your controller extend the controller of the bundle
813 if you want to change only some methods.
7681e45 @stof Updated the doc to use the new configuration
stof authored
814
9aa4a13 @lsmith77 added a section on templating and custom validators, some minor tweaks
lsmith77 authored
815 Validation
816 ----------
817
818 The ``Resources/config/validation.xml`` file contains definitions for custom
7681e45 @stof Updated the doc to use the new configuration
stof authored
819 validator rules for various classes. The rules defined by FOSUserBundle are
725bac1 @stof Updated the doc
stof authored
820 all in validation groups so you can choose not to use them.
b72a19d @stof Made the Canonicalizer configurable
stof authored
821
a0a7ff9 @stof Updated the doc
stof authored
822 Emails
823 ------
824
7681e45 @stof Updated the doc to use the new configuration
stof authored
825 The default mailer relies on Swiftmailer to send the mails of the bundle.
826 If you want to use another mailer in your project you can change it by defining
827 your own service implementing ``FOS\UserBundle\Mailer\MailerInterface`` and
828 setting its id in the configuration::
a0a7ff9 @stof Updated the doc
stof authored
829
830 fos_user:
831 # ...
832 service:
c3d79e8 @ornicar Refactor email management, add fos_user.mailer.noop implementation
ornicar authored
833 mailer: custom_mailer_id
834
835 This bundle comes with two mailer implementations.
836
837 - `fos_user.mailer.default` is the default implementation, and uses swiftmailer to send emails.
838 - `fos_user.mailer.noop` does nothing and can be used if your project does not depend on swiftmailer.
a0a7ff9 @stof Updated the doc
stof authored
839
04e72a1 @jmikola Perform username/email canonicalization in UserManager instead of User
jmikola authored
840 Canonicalization
841 ----------------
b72a19d @stof Made the Canonicalizer configurable
stof authored
842
04e72a1 @jmikola Perform username/email canonicalization in UserManager instead of User
jmikola authored
843 ``Canonicalizer`` services are used to canonicalize the username and the email
9b9eb2f @stof Updated for the framework change
stof authored
844 fields for database storage. By default, username and email fields are
845 canonicalized in the same manner using ``mb_convert_case()``. You may configure
846 your own class for each field provided it implements
847 ``FOS\UserBundle\Util\CanonicalizerInterface``.
b72a19d @stof Made the Canonicalizer configurable
stof authored
848
c629b6d @stof Tweaked the doc
stof authored
849 .. note::
6427338 @stof Added an example of a working security configuration to make it easie…
stof authored
850
b72a19d @stof Made the Canonicalizer configurable
stof authored
851 If you do not have the mbstring extension installed you will need to
852 define your own ``canonicalizer``.
725bac1 @stof Updated the doc
stof authored
853
17e41da @ornicar Add a cool feature: the username form type
ornicar authored
854 Use the username form type
855 ==========================
856
857 The bundle also provides a convenient username form type.
858 It appears as a text input, accepts usernames and convert them to a User instance.
859
860 You can enable this feature from the configuration::
861
862 # app/config/config.yml
863 fos_user:
864 use_username_form_type: true
865
866 And then use it in your forms::
867
868 class MessageFormType extends AbstractType
869 {
870 public function buildForm(FormBuilder $builder, array $options)
871 {
872 $builder->add('recipient', 'fos_user_username');
873 }
874
875
725bac1 @stof Updated the doc
stof authored
876 Configuration reference
877 =======================
878
879 All available configuration options are listed below with their default values::
880
881 # app/config/config.yml
882 fos_user:
883 db_driver: ~ # Required
884 firewall_name: ~ # Required
885 user_class: ~ # Required
886 use_listener: true
5e6d4a0 @ornicar Fix doc and error message
ornicar authored
887 use_username_form_type: false
725bac1 @stof Updated the doc
stof authored
888 from_email:
889 address: webmaster@example.com
890 sender_name: Admin
891 profile:
892 form:
893 type: fos_user_profile
894 handler: fos_user.profile.form.handler.default
895 name: fos_user_profile_form
896 validation_groups: [Profile]
897 change_password:
898 form:
899 type: fos_user_change_password
900 handler: fos_user.change_password.form.handler.default
901 name: fos_user_change_password_form
902 validation_groups: [ChangePassword]
903 registration:
904 confirmation:
905 from_email: # Use this node only if you don't want the global email address for the confirmation email
906 address: ...
907 sender_name: ...
908 enabled: false
909 template: FOSUserBundle:Registration:email.txt.twig
910 form:
911 type: fos_user_registration
912 handler: fos_user.registration.form.handler.default
913 name: fos_user_registration_form
914 validation_groups: [Registration]
915 resetting:
916 token_ttl: 86400
917 email:
918 from_email: # Use this node only if you don't want the global email address for the resetting email
919 address: ...
920 sender_name: ...
921 template: FOSUserBundle:Resetting:email.txt.twig
922 form:
923 type: fos_user_resetting
924 handler: fos_user.resetting.form.handler.default
925 name: fos_user_resetting_form
926 validation_groups: [ResetPassword]
927 service:
928 mailer: fos_user.util.mailer.default
929 email_canonicalizer: fos_user.util.email_canonicalizer.default
930 username_canonicalizer: fos_user.util.username_canonicalizer.default
931 user_manager: fos_user.user_manager.default
932 encoder:
933 algorithm: sha512
934 encode_as_base64: false
935 iterations: 1
936 template:
937 engine: twig
938 theme: FOSUserBundle::form.html.twig
939 group:
940 group_class: ~ # Required when using groups
941 form:
942 type: fos_user_group
943 handler: fos_user.group.form.handler.default
944 name: fos_user_group_form
945 validation_groups: [Registration]
Something went wrong with that request. Please try again.