{"payload":{"allShortcutsEnabled":false,"fileTree":{"Resources/doc":{"items":[{"name":"adding_invitation_registration.rst","path":"Resources/doc/adding_invitation_registration.rst","contentType":"file"},{"name":"canonicalizer.rst","path":"Resources/doc/canonicalizer.rst","contentType":"file"},{"name":"command_line_tools.rst","path":"Resources/doc/command_line_tools.rst","contentType":"file"},{"name":"configuration_reference.rst","path":"Resources/doc/configuration_reference.rst","contentType":"file"},{"name":"controller_events.rst","path":"Resources/doc/controller_events.rst","contentType":"file"},{"name":"custom_storage_layer.rst","path":"Resources/doc/custom_storage_layer.rst","contentType":"file"},{"name":"doctrine.rst","path":"Resources/doc/doctrine.rst","contentType":"file"},{"name":"emails.rst","path":"Resources/doc/emails.rst","contentType":"file"},{"name":"form_type.rst","path":"Resources/doc/form_type.rst","contentType":"file"},{"name":"index.rst","path":"Resources/doc/index.rst","contentType":"file"},{"name":"logging_by_username_or_email.rst","path":"Resources/doc/logging_by_username_or_email.rst","contentType":"file"},{"name":"overriding_forms.rst","path":"Resources/doc/overriding_forms.rst","contentType":"file"},{"name":"overriding_templates.rst","path":"Resources/doc/overriding_templates.rst","contentType":"file"},{"name":"overriding_validation.rst","path":"Resources/doc/overriding_validation.rst","contentType":"file"},{"name":"routing.rst","path":"Resources/doc/routing.rst","contentType":"file"},{"name":"user_manager.rst","path":"Resources/doc/user_manager.rst","contentType":"file"}],"totalCount":16},"Resources":{"items":[{"name":"config","path":"Resources/config","contentType":"directory"},{"name":"doc","path":"Resources/doc","contentType":"directory"},{"name":"translations","path":"Resources/translations","contentType":"directory"},{"name":"views","path":"Resources/views","contentType":"directory"}],"totalCount":4},"":{"items":[{"name":".github","path":".github","contentType":"directory"},{"name":"Command","path":"Command","contentType":"directory"},{"name":"Controller","path":"Controller","contentType":"directory"},{"name":"DependencyInjection","path":"DependencyInjection","contentType":"directory"},{"name":"Doctrine","path":"Doctrine","contentType":"directory"},{"name":"Event","path":"Event","contentType":"directory"},{"name":"EventListener","path":"EventListener","contentType":"directory"},{"name":"Form","path":"Form","contentType":"directory"},{"name":"Mailer","path":"Mailer","contentType":"directory"},{"name":"Model","path":"Model","contentType":"directory"},{"name":"Resources","path":"Resources","contentType":"directory"},{"name":"Security","path":"Security","contentType":"directory"},{"name":"Tests","path":"Tests","contentType":"directory"},{"name":"Util","path":"Util","contentType":"directory"},{"name":"Validator","path":"Validator","contentType":"directory"},{"name":".gitattributes","path":".gitattributes","contentType":"file"},{"name":".gitignore","path":".gitignore","contentType":"file"},{"name":".php-cs-fixer.dist.php","path":".php-cs-fixer.dist.php","contentType":"file"},{"name":"Changelog.md","path":"Changelog.md","contentType":"file"},{"name":"CompatibilityUtil.php","path":"CompatibilityUtil.php","contentType":"file"},{"name":"FOSUserBundle.php","path":"FOSUserBundle.php","contentType":"file"},{"name":"FOSUserEvents.php","path":"FOSUserEvents.php","contentType":"file"},{"name":"LICENSE","path":"LICENSE","contentType":"file"},{"name":"Makefile","path":"Makefile","contentType":"file"},{"name":"README.md","path":"README.md","contentType":"file"},{"name":"Upgrade.md","path":"Upgrade.md","contentType":"file"},{"name":"composer.json","path":"composer.json","contentType":"file"},{"name":"phpunit.xml.dist","path":"phpunit.xml.dist","contentType":"file"}],"totalCount":28}},"fileTreeProcessingTime":12.383166,"foldersToFetch":[],"repo":{"id":1193527,"defaultBranch":"master","name":"FOSUserBundle","ownerLogin":"FriendsOfSymfony","currentUserCanPush":false,"isFork":true,"isEmpty":false,"createdAt":"2010-12-23T15:50:55.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/529709?v=4","public":true,"private":false,"isOrgOwned":true},"symbolsExpanded":false,"treeExpanded":true,"refInfo":{"name":"master","listCacheKey":"v0:1688639965.0","canEdit":false,"refType":"branch","currentOid":"c70ecfd137979c4a92c6528c173fff6bcff818bd"},"path":"Resources/doc/index.rst","currentUser":null,"blob":{"rawLines":null,"stylingDirectives":null,"colorizedLines":null,"csv":null,"csvError":null,"dependabotInfo":{"showConfigurationBanner":false,"configFilePath":null,"networkDependabotPath":"/FriendsOfSymfony/FOSUserBundle/network/updates","dismissConfigurationNoticePath":"/settings/dismiss-notice/dependabot_configuration_notice","configurationNoticeDismissed":null},"displayName":"index.rst","displayUrl":"https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/index.rst?raw=true","headerInfo":{"blobSize":"14.5 KB","deleteTooltip":"You must be signed in to make or propose changes","editTooltip":"You must be signed in to make or propose changes","ghDesktopPath":"https://desktop.github.com","isGitLfs":false,"onBranch":true,"shortPath":"b10bc1d","siteNavLoginPath":"/login?return_to=https%3A%2F%2Fgithub.com%2FFriendsOfSymfony%2FFOSUserBundle%2Fblob%2Fmaster%2FResources%2Fdoc%2Findex.rst","isCSV":false,"isRichtext":true,"toc":[{"level":1,"text":"Getting Started With FOSUserBundle","anchor":"getting-started-with-fosuserbundle","htmlText":"Getting Started With FOSUserBundle"},{"level":2,"text":"Prerequisites","anchor":"prerequisites","htmlText":"Prerequisites"},{"level":3,"text":"Translations","anchor":"translations","htmlText":"Translations"},{"level":2,"text":"Installation","anchor":"installation","htmlText":"Installation"},{"level":3,"text":"Step 1: Download FOSUserBundle using composer","anchor":"step-1-download-fosuserbundle-using-composer","htmlText":"Step 1: Download FOSUserBundle using composer"},{"level":3,"text":"Step 2: Enable the bundle","anchor":"step-2-enable-the-bundle","htmlText":"Step 2: Enable the bundle"},{"level":3,"text":"Step 3: Create your User class","anchor":"step-3-create-your-user-class","htmlText":"Step 3: Create your User class"},{"level":4,"text":"a) Doctrine ORM User class","anchor":"a-doctrine-orm-user-class","htmlText":"a) Doctrine ORM User class"},{"level":4,"text":"b) MongoDB User class","anchor":"b-mongodb-user-class","htmlText":"b) MongoDB User class"},{"level":4,"text":"c) CouchDB User class","anchor":"c-couchdb-user-class","htmlText":"c) CouchDB User class"},{"level":3,"text":"Step 4: Configure your application's security.yml","anchor":"step-4-configure-your-applications-securityyml","htmlText":"Step 4: Configure your application's security.yml"},{"level":3,"text":"Step 5: Configure the FOSUserBundle","anchor":"step-5-configure-the-fosuserbundle","htmlText":"Step 5: Configure the FOSUserBundle"},{"level":3,"text":"Step 6: Import FOSUserBundle routing files","anchor":"step-6-import-fosuserbundle-routing-files","htmlText":"Step 6: Import FOSUserBundle routing files"},{"level":3,"text":"Step 7: Update your database schema","anchor":"step-7-update-your-database-schema","htmlText":"Step 7: Update your database schema"},{"level":3,"text":"Next Steps","anchor":"next-steps","htmlText":"Next Steps"}],"lineInfo":{"truncatedLoc":"462","truncatedSloc":"339"},"mode":"file"},"image":false,"isCodeownersFile":null,"isPlain":false,"isValidLegacyIssueTemplate":false,"issueTemplate":null,"discussionTemplate":null,"language":"reStructuredText","languageID":419,"large":false,"planSupportInfo":{"repoIsFork":null,"repoOwnedByCurrentUser":null,"requestFullPath":"/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/index.rst","showFreeOrgGatedFeatureMessage":null,"showPlanSupportBanner":null,"upgradeDataAttributes":null,"upgradePath":null},"publishBannersInfo":{"dismissActionNoticePath":"/settings/dismiss-notice/publish_action_from_dockerfile","releasePath":"/FriendsOfSymfony/FOSUserBundle/releases/new?marketplace=true","showPublishActionBanner":false},"rawBlobUrl":"https://github.com/FriendsOfSymfony/FOSUserBundle/raw/master/Resources/doc/index.rst","renderImageOrRaw":false,"richText":"

Getting Started With FOSUserBundle

\n

The Symfony Security component provides a flexible security framework that\nallows you to load users from configuration, a database, or anywhere else\nyou can imagine. The FOSUserBundle builds on top of this to make it quick\nand easy to store users in a database, as well as functionality for registration,\nreset password and a profile page.

\n

So, if you need to persist and fetch the users in your system to and from\na database, then you're in the right place.

\n

For a video tutorial, check out FOSUserBundle FTW by KnpUniversity.

\n\n

Prerequisites

\n

This version of the bundle requires Symfony 2.8+. If you are using an older\nSymfony version, please use the 1.3.x releases of the bundle.

\n\n

Translations

\n

If you wish to use default texts provided in this bundle, you have to make\nsure you have translator enabled in your config.

\n
# app/config/config.yml\n\nframework:\n    translator: ~
\n

For more information about translations, check Symfony documentation.

\n\n

Installation

\n

Installation is a quick (I promise!) 7 step process:

\n
    \n
  1. Download FOSUserBundle using composer
  2. \n
  3. Enable the Bundle
  4. \n
  5. Create your User class
  6. \n
  7. Configure your application's security.yml
  8. \n
  9. Configure the FOSUserBundle
  10. \n
  11. Import FOSUserBundle routing
  12. \n
  13. Update your database schema
  14. \n
\n\n

Step 1: Download FOSUserBundle using composer

\n

Require the bundle with composer:

\n
$ composer require friendsofsymfony/user-bundle \"^3.0\"
\n

Composer will install the bundle to your project's vendor/friendsofsymfony/user-bundle directory.\nIf you encounter installation errors pointing at a lack of configuration parameters, such as The child node \"db_driver\" at path \"fos_user\" must be configured, you should complete the configuration in Step 5 first and then re-run this step.

\n\n

Step 2: Enable the bundle

\n

Enable the bundle in the kernel:

\n
<?php\n// app/AppKernel.php\n\npublic function registerBundles()\n{\n    $bundles = array(\n        // ...\n        new FOS\\UserBundle\\FOSUserBundle(),\n        // ...\n    );\n}\n
\n\n

Step 3: Create your User class

\n

The goal of this bundle is to persist some User class to a database (MySql,\nMongoDB, CouchDB, etc). Your first job, then, is to create the User class\nfor your application. This class can look and act however you want: add any\nproperties or methods you find useful. This is your User class.

\n

The bundle provides base classes which are already mapped for most fields\nto make it easier to create your entity. Here is how you use it:

\n
    \n
  1. Extend the base User class (from the Model folder if you are using\nany of the doctrine variants)
  2. \n
  3. Map the id field. It must be protected as it is inherited from the parent class.
  4. \n
\n
\n

Caution!

\n

When you extend from the mapped superclass provided by the bundle, don't\nredefine the mapping for the other fields as it is provided by the bundle.

\n
\n

In the following sections, you'll see examples of how your User class should\nlook, depending on how you're storing your users (Doctrine ORM, MongoDB ODM,\nor CouchDB ODM).

\n
\n

Note

\n

The doc uses a bundle named AppBundle according to the Symfony best\npractices. However, you can of course place your user class in the bundle\nyou want.

\n
\n
\n

Caution!

\n

If you override the __construct() method in your User class, be sure\nto call parent::__construct(), as the base User class depends on\nthis to initialize some fields.

\n
\n\n

a) Doctrine ORM User class

\n

If you're persisting your users via the Doctrine ORM, then your User class\nshould live in the Entity namespace of your bundle and look like this to\nstart:

\n
.. configuration-block::\n\n    .. code-block:: php-annotations\n\n        <?php\n        // src/AppBundle/Entity/User.php\n\n        namespace AppBundle\\Entity;\n\n        use FOS\\UserBundle\\Model\\User as BaseUser;\n        use Doctrine\\ORM\\Mapping as ORM;\n\n        /**\n         * @ORM\\Entity\n         * @ORM\\Table(name=\"fos_user\")\n         */\n        class User extends BaseUser\n        {\n            /**\n             * @ORM\\Id\n             * @ORM\\Column(type=\"integer\")\n             * @ORM\\GeneratedValue(strategy=\"AUTO\")\n             */\n            protected $id;\n\n            public function __construct()\n            {\n                parent::__construct();\n                // your own logic\n            }\n        }\n\n    .. code-block:: yaml\n\n        # src/AppBundle/Resources/config/doctrine/User.orm.yml\n        AppBundle\\Entity\\User:\n            type:  entity\n            table: fos_user\n            id:\n                id:\n                    type: integer\n                    generator:\n                        strategy: AUTO\n\n    .. code-block:: xml\n\n        <?xml version=\"1.0\" encoding=\"utf-8\"?>\n        <!-- src/AppBundle/Resources/config/doctrine/User.orm.xml -->\n        <doctrine-mapping xmlns=\"http://doctrine-project.org/schemas/orm/doctrine-mapping\"\n            xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n            xsi:schemaLocation=\"http://doctrine-project.org/schemas/orm/doctrine-mapping http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd\">\n\n            <entity name=\"AppBundle\\Entity\\User\" table=\"fos_user\">\n                <id name=\"id\" type=\"integer\" column=\"id\">\n                    <generator strategy=\"AUTO\"/>\n                </id>\n            </entity>\n        </doctrine-mapping>\n\n
\n
\n

Caution!

\n

user is a reserved keyword in the SQL standard. If you need to use reserved words, surround them with backticks, e.g. @ORM\\Table(name=\"`user`\")

\n
\n\n

b) MongoDB User class

\n

If you're persisting your users via the Doctrine MongoDB ODM, then your User\nclass should live in the Document namespace of your bundle and look like\nthis to start:

\n
<?php\n// src/AppBundle/Document/User.php\n\nnamespace AppBundle\\Document;\n\nuse FOS\\UserBundle\\Model\\User as BaseUser;\nuse Doctrine\\ODM\\MongoDB\\Mapping\\Annotations as MongoDB;\n\n/**\n * @MongoDB\\Document\n */\nclass User extends BaseUser\n{\n    /**\n     * @MongoDB\\Id(strategy=\"auto\")\n     */\n    protected $id;\n\n    public function __construct()\n    {\n        parent::__construct();\n        // your own logic\n    }\n}\n
\n\n

c) CouchDB User class

\n

If you're persisting your users via the Doctrine CouchDB ODM, then your User\nclass should live in the CouchDocument namespace of your bundle and look\nlike this to start:

\n
<?php\n// src/AppBundle/CouchDocument/User.php\n\nnamespace AppBundle\\CouchDocument;\n\nuse FOS\\UserBundle\\Model\\User as BaseUser;\nuse Doctrine\\ODM\\CouchDB\\Mapping\\Annotations as CouchDB;\n\n/**\n * @CouchDB\\Document\n */\nclass User extends BaseUser\n{\n    /**\n     * @CouchDB\\Id\n     */\n    protected $id;\n\n    public function __construct()\n    {\n        parent::__construct();\n        // your own logic\n    }\n}\n
\n\n

Step 4: Configure your application's security.yml

\n

In order for Symfony's security component to use the FOSUserBundle, you must\ntell it to do so in the security.yml file. The security.yml file is where the\nbasic security configuration for your application is contained.

\n

Below is a minimal example of the configuration necessary to use the FOSUserBundle\nin your application:

\n
# app/config/security.yml\nsecurity:\n    encoders:\n        FOS\\UserBundle\\Model\\UserInterface: auto\n\n    role_hierarchy:\n        ROLE_ADMIN:       ROLE_USER\n        ROLE_SUPER_ADMIN: ROLE_ADMIN\n\n    providers:\n        fos_userbundle:\n            id: fos_user.user_provider.username\n\n    firewalls:\n        main:\n            pattern: ^/\n            user_checker: fos_user.user_checker\n            form_login:\n                provider: fos_userbundle\n                csrf_token_generator: security.csrf.token_manager\n\n            logout:       true\n            anonymous:    true\n\n    access_control:\n        - { path: ^/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }\n        - { path: ^/register, role: IS_AUTHENTICATED_ANONYMOUSLY }\n        - { path: ^/resetting, role: IS_AUTHENTICATED_ANONYMOUSLY }\n        - { path: ^/admin/, role: ROLE_ADMIN }
\n

Under the providers section, you are making the bundle's packaged user provider\nservice available via the alias fos_userbundle. The id of the bundle's user\nprovider service is fos_user.user_provider.username.

\n

Next, take a look at and examine the firewalls section. Here we have\ndeclared a firewall named main. By specifying form_login, you have\ntold the Symfony Framework that any time a request is made to this firewall\nthat leads to the user needing to authenticate himself, the user will be\nredirected to a form where he will be able to enter his credentials. It should\ncome as no surprise then that you have specified the user provider service\nwe declared earlier as the provider for the firewall to use as part of the\nauthentication process.

\n
\n

Note

\n

Although we have used the form login mechanism in this example, the FOSUserBundle\nuser provider service is compatible with many other authentication methods\nas well. Please read the Symfony Security component documentation for\nmore information on the other types of authentication methods.

\n
\n

The access_control section is where you specify the credentials necessary for\nusers trying to access specific parts of your application. The bundle requires\nthat the login form and all the routes used to create a user and reset the password\nbe available to unauthenticated users but use the same firewall as\nthe pages you want to secure with the bundle. This is why you have specified that\nany request matching the /login pattern or starting with /register or\n/resetting have been made available to anonymous users. You have also specified\nthat any request beginning with /admin will require a user to have the\nROLE_ADMIN role.

\n

For more information on configuring the security.yml file please read the Symfony\nsecurity component documentation.

\n
\n

Note

\n

Pay close attention to the name, main, that we have given to the\nfirewall which the FOSUserBundle is configured in. You will use this\nin the next step when you configure the FOSUserBundle.

\n
\n\n

Step 5: Configure the FOSUserBundle

\n

Now that you have properly configured your application's security.yml to work\nwith the FOSUserBundle, the next step is to configure the bundle to work with\nthe specific needs of your application.

\n

Add the following configuration to your config.yml file according to which type\nof datastore you are using.

\n
.. configuration-block::\n\n    .. code-block:: yaml\n\n        # app/config/config.yml\n        fos_user:\n            db_driver: orm # other valid values are 'mongodb' and 'couchdb'\n            firewall_name: main\n            user_class: AppBundle\\Entity\\User\n            from_email:\n                address: \"%mailer_user%\"\n                sender_name: \"%mailer_user%\"\n\n    .. code-block:: xml\n\n        <!-- app/config/config.xml -->\n\n        <!-- other valid 'db-driver' values are 'mongodb' and 'couchdb' -->\n        <fos_user:config\n            db-driver=\"orm\"\n            firewall-name=\"main\"\n            user-class=\"AppBundle\\Entity\\User\"\n        />\n\n
\n

Only four configuration's nodes are required to use the bundle:

\n\n
\n

Note

\n

FOSUserBundle uses a compiler pass to register mappings for the base\nUser model classes with the object manager that you configured\nit to use. (Unless specified explicitly, this is the default manager\nof your doctrine configuration.)

\n
\n\n

Step 6: Import FOSUserBundle routing files

\n

Now that you have activated and configured the bundle, all that is left to do is\nimport the FOSUserBundle routing files.

\n

By importing the routing files you will have ready made pages for things such as\nlogging in, creating users, etc.

\n
.. configuration-block::\n\n    .. code-block:: yaml\n\n        # app/config/routing.yml\n        fos_user:\n            resource: \"@FOSUserBundle/Resources/config/routing/all.xml\"\n\n    .. code-block:: xml\n\n            <!-- app/config/routing.xml -->\n            <import resource=\"@FOSUserBundle/Resources/config/routing/all.xml\"/>\n\n
\n
\n

Note

\n

In order to use the built-in email functionality (confirmation of the account,\nresetting of the password), you must activate and configure the SwiftmailerBundle.

\n
\n\n

Step 7: Update your database schema

\n

Now that the bundle is configured, the last thing you need to do is update your\ndatabase schema because you have added a new entity, the User class which you\ncreated in Step 4.

\n

For ORM run the following command.

\n
$ php bin/console doctrine:schema:update --force
\n

For MongoDB users you can run the following command to create the indexes.

\n
$ php bin/console doctrine:mongodb:schema:create --index
\n
\n

Note

\n

If you use the Symfony 2.x structure in your project, use app/console\ninstead of bin/console in the commands.

\n
\n

You now can log in at http://app.com/app_dev.php/login!

\n\n

Next Steps

\n

Now that you have completed the basic installation and configuration of the\nFOSUserBundle, you are ready to learn about more advanced features and usages\nof the bundle.

\n

The following documents are available:

\n
.. toctree::\n    :maxdepth: 1\n\n    overriding_templates\n    controller_events\n    overriding_forms\n    user_manager\n    command_line_tools\n    logging_by_username_or_email\n    form_type\n    emails\n    doctrine\n    overriding_validation\n    canonicalizer\n    custom_storage_layer\n    routing\n    configuration_reference\n    adding_invitation_registration\n\n
\n\n
","renderedFileInfo":null,"shortPath":null,"symbolsEnabled":true,"tabSize":8,"topBannersInfo":{"overridingGlobalFundingFile":false,"globalPreferredFundingPath":null,"showInvalidCitationWarning":false,"citationHelpUrl":"https://docs.github.com/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files","actionsOnboardingTip":null},"truncated":false,"viewable":true,"workflowRedirectUrl":null,"symbols":{"timed_out":false,"not_analyzed":true,"symbols":[]}},"copilotInfo":null,"copilotAccessAllowed":false,"csrf_tokens":{"/FriendsOfSymfony/FOSUserBundle/branches":{"post":"9-pvNKBYXuAj-gghFDXoPuEtkaHtTjAVYHm9YqCgUoxm9RH5Us_Z8PMhw8y0jkYVkqCPhcnSTzYbhCgVa79TYA"},"/repos/preferences":{"post":"EG-qToIkF8v2WsbYj5-jo2ZqGkC2iVp6966G8zM4Jr9GyKO2zzc9B6Sjc7F30YcG7-BTPM6cvdfE3fy3_JSOxg"}}},"title":"FOSUserBundle/Resources/doc/index.rst at master ยท FriendsOfSymfony/FOSUserBundle"}