From 59579275442df3b40858e1170315f2e1fed7aba5 Mon Sep 17 00:00:00 2001 From: Rafael Mello Date: Mon, 10 Aug 2015 09:47:35 -0300 Subject: [PATCH 01/12] Update entity.rst Added "choice_translation_domain" and "translation_domain" documentation. --- reference/forms/types/entity.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 85cff817bc9..3546ddf104c 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -16,6 +16,8 @@ objects from the database. | | - `choice_label`_ | | | - `query_builder`_ | | | - `em`_ | +| | - `choice_translation_domain`_ | +| | - `translation_domain`_ | +-------------+------------------------------------------------------------------+ | Overridden | - `choices`_ | | options | | @@ -176,6 +178,26 @@ em If specified, this entity manager will be used to load the choices instead of the ``default`` entity manager. +choice_translation_domain +~~~~~~~~~~~~~ + +.. versionadded:: 2.7 + The ``choice_translation_domain`` option was introduced in Symfony 2.7. + +**type**: ``boolean`` + +This option determines whether the translation of the data obtained will be informed domain ``translation_domain``. + +translation_domain +~~~~~~~~~~~~~ + +.. versionadded:: 2.7 + The ``translation_domain`` option was introduced in Symfony 2.7. + +**type**: ``string`` + +If specified, use translations of informed domain(e.g. ``AcmeStoreBundle`` to ``Acme\StoreBundle\Resources\translation`` files). + Overridden Options ------------------ From 3ad51119c85839ed6964fef62be9ae06e78f1705 Mon Sep 17 00:00:00 2001 From: Rafael Mello Date: Mon, 10 Aug 2015 10:04:44 -0300 Subject: [PATCH 02/12] Travis fix Fixed title underline. --- reference/forms/types/entity.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 3546ddf104c..4a2296f60ec 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -179,7 +179,7 @@ If specified, this entity manager will be used to load the choices instead of the ``default`` entity manager. choice_translation_domain -~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.7 The ``choice_translation_domain`` option was introduced in Symfony 2.7. @@ -189,7 +189,7 @@ choice_translation_domain This option determines whether the translation of the data obtained will be informed domain ``translation_domain``. translation_domain -~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.7 The ``translation_domain`` option was introduced in Symfony 2.7. From 2fa2386a103b0624dbda478f4ac1e7f96e9114f1 Mon Sep 17 00:00:00 2001 From: Rafael Mello Date: Sun, 30 Aug 2015 23:49:38 -0300 Subject: [PATCH 03/12] choice_translation_domain doc fix "choice_translation_domain" description fixed. --- reference/forms/types/entity.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 4a2296f60ec..e2180e7ec08 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -184,9 +184,9 @@ choice_translation_domain .. versionadded:: 2.7 The ``choice_translation_domain`` option was introduced in Symfony 2.7. -**type**: ``boolean`` +**type**: ``boolean`` | ``null`` | ``string`` -This option determines whether the translation of the data obtained will be informed domain ``translation_domain``. +If specified ``null`` value, corresponds to parents translation_domain or default domain (messages). If the value is ``string``, corresponds to explicit domain(e.g. ``AcmeStoreBundle``). If the value is ``true``, reuse current ``translation_domain`` and ``false`` to disabled. translation_domain ~~~~~~~~~~~~~~~~~~ From 92998d8cb7213e4eccc2b8e2a9a2da73ca4d4d2e Mon Sep 17 00:00:00 2001 From: Rafael Mello Date: Mon, 31 Aug 2015 00:00:27 -0300 Subject: [PATCH 04/12] translation_domain doc fix "translation_domain" documentation fixed. --- reference/forms/types/entity.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index e2180e7ec08..6ae4953e344 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -186,7 +186,7 @@ choice_translation_domain **type**: ``boolean`` | ``null`` | ``string`` -If specified ``null`` value, corresponds to parents translation_domain or default domain (messages). If the value is ``string``, corresponds to explicit domain(e.g. ``AcmeStoreBundle``). If the value is ``true``, reuse current ``translation_domain`` and ``false`` to disabled. +If specified ``null`` value, corresponds to parents ``translation_domain`` or default domain (messages). If the value is ``string``, corresponds to explicit domain(e.g. ``AcmeStoreBundle``). If the value is ``true``, reuse current ``translation_domain`` and ``false`` to disabled. translation_domain ~~~~~~~~~~~~~~~~~~ @@ -196,7 +196,7 @@ translation_domain **type**: ``string`` -If specified, use translations of informed domain(e.g. ``AcmeStoreBundle`` to ``Acme\StoreBundle\Resources\translation`` files). +When ``choice_translation_domain`` is ``true`` or ``null``, use translations of informed domain(e.g. ``AcmeStoreBundle`` to ``Acme\StoreBundle\Resources\translation`` files). Overridden Options From 4b92e8874057475f0a1cb7632f633928ff4a8e62 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 6 Feb 2016 16:57:08 +0100 Subject: [PATCH 05/12] Document translation_domain setting for choice fields --- reference/forms/types/choice.rst | 4 +++ reference/forms/types/entity.rst | 26 +++---------------- .../choice_type_translation_domain.rst.inc | 8 ++++++ 3 files changed, 15 insertions(+), 23 deletions(-) create mode 100644 reference/forms/types/options/choice_type_translation_domain.rst.inc diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst index 012353f1b06..6a2e7e619c5 100644 --- a/reference/forms/types/choice.rst +++ b/reference/forms/types/choice.rst @@ -17,6 +17,7 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op | | - `choice_loader`_ | | | - `choice_label`_ | | | - `choice_attr`_ | +| | - `choice_translation_domain`_ | | | - `placeholder`_ | | | - `expanded`_ | | | - `multiple`_ | @@ -41,6 +42,7 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op | | - `mapped`_ | | | - `read_only`_ | | | - `required`_ | +| | - `translation_domain`_ | +-------------+------------------------------------------------------------------------------+ | Parent type | :doc:`form ` | +-------------+------------------------------------------------------------------------------+ @@ -348,6 +350,8 @@ type: .. include:: /reference/forms/types/options/required.rst.inc +.. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc + Field Variables --------------- diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 6ae4953e344..434db25388f 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -16,8 +16,6 @@ objects from the database. | | - `choice_label`_ | | | - `query_builder`_ | | | - `em`_ | -| | - `choice_translation_domain`_ | -| | - `translation_domain`_ | +-------------+------------------------------------------------------------------+ | Overridden | - `choices`_ | | options | | @@ -26,6 +24,7 @@ objects from the database. | options | | | | - `placeholder`_ | | | - `choice_translation_domain`_ | +| | - `translation_domain`_ | | | - `expanded`_ | | | - `multiple`_ | | | - `preferred_choices`_ | @@ -178,27 +177,6 @@ em If specified, this entity manager will be used to load the choices instead of the ``default`` entity manager. -choice_translation_domain -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2.7 - The ``choice_translation_domain`` option was introduced in Symfony 2.7. - -**type**: ``boolean`` | ``null`` | ``string`` - -If specified ``null`` value, corresponds to parents ``translation_domain`` or default domain (messages). If the value is ``string``, corresponds to explicit domain(e.g. ``AcmeStoreBundle``). If the value is ``true``, reuse current ``translation_domain`` and ``false`` to disabled. - -translation_domain -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 2.7 - The ``translation_domain`` option was introduced in Symfony 2.7. - -**type**: ``string`` - -When ``choice_translation_domain`` is ``true`` or ``null``, use translations of informed domain(e.g. ``AcmeStoreBundle`` to ``Acme\StoreBundle\Resources\translation`` files). - - Overridden Options ------------------ @@ -221,6 +199,8 @@ type: .. include:: /reference/forms/types/options/choice_translation_domain.rst.inc +.. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc + .. include:: /reference/forms/types/options/expanded.rst.inc .. include:: /reference/forms/types/options/multiple.rst.inc diff --git a/reference/forms/types/options/choice_type_translation_domain.rst.inc b/reference/forms/types/options/choice_type_translation_domain.rst.inc new file mode 100644 index 00000000000..87cd76cff9a --- /dev/null +++ b/reference/forms/types/options/choice_type_translation_domain.rst.inc @@ -0,0 +1,8 @@ +translation_domain +~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``messages`` + +In case `choice_translation_domain`_ is set to ``true`` or ``null``, this +configures the exact translation domain that will be used for any labels or +options that are rendered for this field From 5dcca79ea5b2455401da35b3425e2a61be398e8c Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Tue, 9 Feb 2016 17:47:25 +0100 Subject: [PATCH 06/12] [Cookbook][Serializer] fix wording --- cookbook/serializer.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cookbook/serializer.rst b/cookbook/serializer.rst index 8b2d9b296d8..b32873b5250 100644 --- a/cookbook/serializer.rst +++ b/cookbook/serializer.rst @@ -178,7 +178,8 @@ Enabling the Metadata Cache --------------------------- .. versionadded:: 2.7 - Serializer was introduced in Symfony 2.7. + Serializer metadata and the ability to cache them were introduced in + Symfony 2.7. Metadata used by the Serializer component such as groups can be cached to enhance application performance. Any service implementing the ``Doctrine\Common\Cache\Cache`` From 5eff7fd6d0ece166fdb8ccdc7fb7f4be948e19cf Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Tue, 9 Feb 2016 17:55:28 +0100 Subject: [PATCH 07/12] remove note about memory spool handling on CLI --- book/routing.rst | 2 +- cookbook/console/index.rst | 2 +- ...sending_emails.rst => request_context.rst} | 45 +------------------ cookbook/map.rst.inc | 2 +- redirection_map | 1 + 5 files changed, 6 insertions(+), 46 deletions(-) rename cookbook/console/{sending_emails.rst => request_context.rst} (65%) diff --git a/book/routing.rst b/book/routing.rst index 56854ea337b..bfc8502a637 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -1514,7 +1514,7 @@ to ``generate()``: The host that's used when generating an absolute URL is automatically detected using the current ``Request`` object. When generating absolute URLs from outside the web context (for instance in a console command) this - doesn't work. See :doc:`/cookbook/console/sending_emails` to learn how to + doesn't work. See :doc:`/cookbook/console/request_context` to learn how to solve this problem. Summary diff --git a/cookbook/console/index.rst b/cookbook/console/index.rst index fca80484eaa..77c289f7035 100644 --- a/cookbook/console/index.rst +++ b/cookbook/console/index.rst @@ -7,5 +7,5 @@ Console console_command usage command_in_controller - sending_emails + request_context logging diff --git a/cookbook/console/sending_emails.rst b/cookbook/console/request_context.rst similarity index 65% rename from cookbook/console/sending_emails.rst rename to cookbook/console/request_context.rst index 41318938a61..a10d8b2df3c 100644 --- a/cookbook/console/sending_emails.rst +++ b/cookbook/console/request_context.rst @@ -1,9 +1,8 @@ .. index:: - single: Console; Sending emails single: Console; Generating URLs -How to Generate URLs and Send Emails from the Console -===================================================== +How to Generate URLs from the Console +===================================== Unfortunately, the command line context does not know about your VirtualHost or domain name. This means that if you generate absolute URLs within a @@ -84,43 +83,3 @@ from the ``router`` service and override its settings:: // ... your code here } } - -Using Memory Spooling ---------------------- - -.. versionadded:: 2.3 - When using Symfony 2.3+ and SwiftmailerBundle 2.3.5+, the memory spool is now - handled automatically in the CLI and the code below is not necessary anymore. - -Sending emails in a console command works the same way as described in the -:doc:`/cookbook/email/email` cookbook except if memory spooling is used. - -When using memory spooling (see the :doc:`/cookbook/email/spool` cookbook for more -information), you must be aware that because of how Symfony handles console -commands, emails are not sent automatically. You must take care of flushing -the queue yourself. Use the following code to send emails inside your -console command:: - - $message = new \Swift_Message(); - - // ... prepare the message - - $container = $this->getContainer(); - $mailer = $container->get('mailer'); - - $mailer->send($message); - - // now manually flush the queue - $spool = $mailer->getTransport()->getSpool(); - $transport = $container->get('swiftmailer.transport.real'); - - $spool->flushQueue($transport); - -Another option is to create an environment which is only used by console -commands and uses a different spooling method. - -.. note:: - - Taking care of the spooling is only needed when memory spooling is used. - If you are using file spooling (or no spooling at all), there is no need - to flush the queue manually within the command. diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 5ba5d97ff1c..d3d35eed96a 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -45,7 +45,7 @@ * :doc:`/cookbook/console/console_command` * :doc:`/cookbook/console/usage` * :doc:`/cookbook/console/command_in_controller` - * :doc:`/cookbook/console/sending_emails` + * :doc:`/cookbook/console/request_context` * :doc:`/cookbook/console/logging` * :doc:`/cookbook/controller/index` diff --git a/redirection_map b/redirection_map index a2fa6ea43a3..6e8ea5d953f 100644 --- a/redirection_map +++ b/redirection_map @@ -1,5 +1,6 @@ /book/stable_api /contributing/code/bc /book/internals /reference/events +/cookbook/console/sending_emails /cookbook/console/request_context /cookbook/deployment-tools /cookbook/deployment/tools /cookbook/doctrine/migrations /bundles/DoctrineFixturesBundle/index /cookbook/doctrine/doctrine_fixtures /bundles/DoctrineFixturesBundle/index From 121196dfd12ca968c387a0fe5caa58c7df77e5ed Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Thu, 12 Nov 2015 16:31:18 +0000 Subject: [PATCH 08/12] [2.8] Add "How to Use Multiple Guard Authenticators" cookbook documentation --- cookbook/map.rst.inc | 1 + cookbook/security/index.rst | 1 + .../multiple_guard_authenticators.rst | 172 ++++++++++++++++++ 3 files changed, 174 insertions(+) create mode 100644 cookbook/security/multiple_guard_authenticators.rst diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index d57650320c7..7f96d19c747 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -176,6 +176,7 @@ * :doc:`/cookbook/security/csrf_in_login_form` * :doc:`/cookbook/security/named_encoders` * :doc:`/cookbook/security/multiple_user_providers` + * :doc:`/cookbook/security/multiple_guard_authenticators` * :doc:`/cookbook/security/firewall_restriction` * :doc:`/cookbook/security/host_restriction` * :doc:`/cookbook/security/user_checkers` diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst index ed13a2116f9..61efff1aa23 100644 --- a/cookbook/security/index.rst +++ b/cookbook/security/index.rst @@ -22,6 +22,7 @@ Authentication (Identifying/Logging in the User) csrf_in_login_form named_encoders multiple_user_providers + multiple_guard_authenticators firewall_restriction host_restriction user_checkers diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst new file mode 100644 index 00000000000..acb1f774422 --- /dev/null +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -0,0 +1,172 @@ +How to Use Multiple Guard Authenticators +======================================== + +.. versionadded:: 2.8 + The ``Guard`` component was introduced in Symfony 2.8. + +The Guard authentication component allows you to easily use many different +authenticators at a time. + +An entry point is a service id (of one of your authenticators) whose +``start()`` method is called to start the authentication process. + +Multiple Authenticators with Shared Entry Point +----------------------------------------------- + +Sometimes you want to offer your users different authentication mechanisms like +a form login and a Facebook login while both entry points redirect the user to +the same login page. +However, in your configuration you have to explicitly say which entry point +you want to use. + +This is how your security configuration can look in action: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + # ... + firewalls: + default: + anonymous: ~ + guard: + authenticators: + - app.form_login_authenticator + - app.facebook_connect_authenticator + entry_point: app.form_login_authenticator + + .. code-block:: xml + + + + + + + + + + + app.form_login_authenticator + app.facebook_connect_authenticator + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + // ... + 'firewalls' => array( + 'default' => array( + 'anonymous' => null, + 'guard' => array( + 'entry_point' => 'app.form_login_authenticator', + 'authenticators' => array( + 'app.form_login_authenticator', + 'app.facebook_connect_authenticator' + ), + ), + ), + ), + )); + +There is one limitation with this approach - you have to use exactly one entry point. + +Multiple Authenticators with Separate Entry Points +-------------------------------------------------- + +However, there are use cases where you have authenticators that protect different +parts of your application. For example, you have a login form that protects +the secured area of your application front-end and API end points that are +protected with API tokens. As you can only configure one entry point per firewall, +the solution is to split the configuration into two separate firewalls: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + # ... + firewalls: + api: + pattern: ^/api/ + guard: + authenticators: + - app.api_token_authenticator + default: + anonymous: ~ + guard: + authenticators: + - app.form_login_authenticator + access_control: + - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY } + - { path: ^/api, roles: ROLE_API_USER } + - { path: ^/, roles: ROLE_USER } + + .. code-block:: xml + + + + + + + + + + app.api_token_authenticator + + + + + + app.form_login_authenticator + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + // ... + 'firewalls' => array( + 'api' => array( + 'pattern' => '^/api', + 'guard' => array( + 'authenticators' => array( + 'app.api_token_authenticator', + ), + ), + ), + 'default' => array( + 'anonymous' => null, + 'guard' => array( + 'authenticators' => array( + 'app.form_login_authenticator', + ), + ), + ), + ), + 'access_control' => array( + array('path' => '^/login', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY'), + array('path' => '^/api', 'role' => 'ROLE_API_USER'), + array('path' => '^/', 'role' => 'ROLE_USER'), + ), + )); From d1d4275ecf0559c40b7c563f4c0dc232562c5e30 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 25 Aug 2015 23:13:09 +0200 Subject: [PATCH 09/12] Added doc about Homestead's Symfony integration --- cookbook/map.rst.inc | 1 + cookbook/workflow/homestead.rst | 76 +++++++++++++++++++++++++++++++++ cookbook/workflow/index.rst | 1 + 3 files changed, 78 insertions(+) create mode 100644 cookbook/workflow/homestead.rst diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index d3d35eed96a..4762a2d41fa 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -245,3 +245,4 @@ * :doc:`/cookbook/workflow/new_project_git` * :doc:`/cookbook/workflow/new_project_svn` + * :doc:`/cookbook/workflow/homestead` diff --git a/cookbook/workflow/homestead.rst b/cookbook/workflow/homestead.rst new file mode 100644 index 00000000000..2f50a3305ac --- /dev/null +++ b/cookbook/workflow/homestead.rst @@ -0,0 +1,76 @@ +.. index:: Vagrant, Homestead + +Using Symfony with Homestead/Vagrant +==================================== + +In order to develop a Symfony application, you might want to use a virtual +development environment instead of the built-in server or WAMP/LAMP. Homestead_ +is an easy-to-use Vagrant_ box to get a virtual environment up and running +quickly. + +.. tip:: + + Due to the amount of filesystem operations in Symfony (e.g. updating cache + files and writing to log files), Symfony can slow down signifcantly. To + improve the speed, consider :ref:`overriding the cache and log directories ` + to a location outside the NFS share (for instance, by using + :phpfunction:`sys_get_temp_dir`). You can read `this blog post`_ for more + tips to speed up Symfony on Vagrant. + +Install Vagrant and Homestead +----------------------------- + +Before you can use Homestead, you need to install and configure Vagrant and +Homestead as explained in `the Homestead documentation`_. + +Setting Up a Symfony Application +-------------------------------- + +Imagine you've installed your Symfony application in +``~/projects/symfony_demo`` on your local system. You first need Homestead to +sync your files in this project. Execute ``homestead edit`` to edit the +Homestead configuration and configure the ``~/projects`` directory: + +.. code-block:: yaml + + # ... + folders: + - map: ~/projects + to: /home/vagrant/projects + +The ``projects/`` directory on your PC is now accessible at +``/home/vagrant/projects`` in the Homestead environment. + +After you've done this, configure the Symfony application in the Homestead +configuration: + +.. code-block:: yaml + + # ... + sites: + - map: symfony-demo.dev + to: /home/vagrant/projects/symfony_demo/web + type: symfony + +The ``type`` option tells Homestead to use the Symfony nginx configuration. + +At last, edit the hosts file on your local machine to map ``symfony-demo.dev`` +to ``192.168.10.10`` (which is the IP used by Homestead):: + + # /etc/hosts (unix) or C:\Windows\System32\drivers\etc\hosts (Windows) + 192.168.10.10 symfony-demo.dev + +Now, navigate to ``http://symfony-demo.dev`` in your web browser and enjoy +developing your Symfony application! + +.. seealso:: + + To learn more features of Homestead, including Blackfire Profiler + integration, automatic creation of MySQL databases and more, read the + `Daily Usage`_ section of the Homestead documentation. + +.. _Homestead: http://laravel.com/docs/homestead +.. _Vagrant: https://www.vagrantup.com/ +.. _the Homestead documentation: http://laravel.com/docs/homestead#installation-and-setup +.. _Daily Usage: http://laravel.com/docs/5.1/homestead#daily-usage +.. _this blog post: http://www.whitewashing.de/2013/08/19/speedup_symfony2_on_vagrant_boxes.html diff --git a/cookbook/workflow/index.rst b/cookbook/workflow/index.rst index 6b2382ae235..7da4491bbc1 100644 --- a/cookbook/workflow/index.rst +++ b/cookbook/workflow/index.rst @@ -6,3 +6,4 @@ Workflow new_project_git new_project_svn + homestead From 63c57dd8c6b7915924a3de653bff117970c8a1bc Mon Sep 17 00:00:00 2001 From: Calin Pristavu Date: Wed, 10 Feb 2016 15:39:56 +0200 Subject: [PATCH 10/12] [Security] Include guard firewall configuration sample. As per "config:dump-reference symfony" output, add the guard firewall configuration to the sample security configuration file. --- reference/configuration/security.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst index a9b25ceb5e9..c3e723cf487 100644 --- a/reference/configuration/security.rst +++ b/reference/configuration/security.rst @@ -133,6 +133,15 @@ Each part will be explained in the next section. provider: some_key_from_above http_digest: provider: some_key_from_above + guard: + # A key from the "providers" section of your security config, in case your user provider is different than the firewall + provider: ~ + + # A service id (of one of your authenticators) whose start() method should be called when an anonymous user hits a page that requires authentication + entry_point: null + + # An array of service ids for all of your "authenticators" + authenticators: [] form_login: # submit the login form here check_path: /login_check From 995bd4fcbc7cdd05a63a1fe5dc521c013624bbc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Thu, 17 Dec 2015 00:23:28 +0100 Subject: [PATCH 11/12] [DependencyInjection] Autowiring doc --- .../dependency_injection/autowiring.rst | 397 ++++++++++++++++++ components/dependency_injection/index.rst | 1 + components/map.rst.inc | 1 + 3 files changed, 399 insertions(+) create mode 100644 components/dependency_injection/autowiring.rst diff --git a/components/dependency_injection/autowiring.rst b/components/dependency_injection/autowiring.rst new file mode 100644 index 00000000000..86287d5d5a7 --- /dev/null +++ b/components/dependency_injection/autowiring.rst @@ -0,0 +1,397 @@ +.. index:: + single: DependencyInjection; Autowiring + +Defining Services Dependencies Automatically +============================================ + +Autowiring allows to register services in the container with minimal configuration. +It is useful in the field of `Rapid Application Development`_, when designing prototypes +in early stages of large projects. It makes it easy to register a service graph +and eases refactoring. + +Imagine you're building an API to publish statuses on a Twitter feed, obfuscated +with `ROT13`.. (a special case of the Caesar cipher). + +Start by creating a ROT13 transformer class:: + + // src/AppBundle/Rot13Transformer.php + namespace AppBundle; + + class Rot13Transformer + { + public function transform($value) + { + return str_rot13($value); + } + } + +And now a Twitter client using this transformer:: + + // src/AppBundle/TwitterClient.php + namespace AppBundle; + + class TwitterClient + { + private $transformer; + + public function __construct(Rot13Transformer $transformer) + { + $this->transformer = $transformer; + } + + public function tweet($user, $key, $status) + { + $transformedStatus = $this->transformer->transform($status); + + // ... connect to Twitter and send the encoded status + } + } + +The Dependency Injection Component will be able to automatically register the dependencies +of this ``TwitterClient`` class by marking the ``twitter_client`` service as autowired: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + twitter_client: + class: 'AppBundle\TwitterClient' + autowire: true + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + use Symfony\Component\DependencyInjection\Definition; + + // ... + $definition = new Definition('AppBundle\TwitterClient'); + $definition->setAutowired(true); + + $container->setDefinition('twitter_client', $definition); + +The autowiring subsystem will detect the dependencies of the ``TwitterClient`` +class by parsing its constructor. For instance it will find here an instance of +a ``Rot13Transformer`` as dependency. If an existing service definition (and only +one – see below) is of the required type, this service will be injected. If it's +not the case (like in this example), the subsystem is smart enough to automatically +register a private service for the ``Rot13Transformer`` class and set it as first +argument of the ``twitter_client`` service. Again, it can work only if there is one +class of the given type. If there are several classes of the same type, you must +use an explicit service definition or register a default implementation. + +As you can see, the autowiring feature drastically reduces the amount of configuration +required to define a service. No more arguments section! It also makes it easy +to change the dependencies of the ``TwitterClient`` class: just add or remove typehinted +arguments in the constructor and you are done. There is no need anymore to search +and edit related service definitions. + +Here is a typical controller using the ``twitter_client`` service:: + + // src/AppBundle/Controller/DefaultController.php + namespace AppBundle\Controller; + + use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; + use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method; + use Symfony\Bundle\FrameworkBundle\Controller\Controller; + use Symfony\Component\HttpFoundation\Request; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Exception\BadRequestHttpException; + + class DefaultController extends Controller + { + /** + * @Route("/tweet") + * @Method("POST") + */ + public function tweetAction(Request $request) + { + $user = $request->request->get('user'); + $key = $request->request->get('key'); + $status = $request->request->get('status'); + + if (!$user || !$key || !$status) { + throw new BadRequestHttpException(); + } + + $this->get('twitter_client')->tweet($user, $key, $status); + + return new Response('OK'); + } + } + +You can give a try to the API with ``curl``:: + + curl -d "user=kevin&key=ABCD&status=Hello" http://localhost:8000/tweet + +It should return ``OK``. + +Working with Interfaces +----------------------- + +You might also find yourself using abstractions instead of implementations (especially +in grown applications) as it allows to easily replace some dependencies without +modifying the class depending of them. + +To follow this best practice, constructor arguments must be typehinted with interfaces +and not concrete classes. It allows to replace easily the current implementation +if necessary. It also allows to use other transformers. + +Let's introduce a ``TransformerInterface``:: + + // src/AppBundle/TransformerInterface.php + namespace AppBundle; + + interface TransformerInterface + { + public function transform($value); + } + +Then edit ``Rot13Transformer`` to make it implementing the new interface:: + + // ... + + class Rot13Transformer implements TransformerInterface + + // ... + + +And update ``TwitterClient`` to depend of this new interface:: + + class TwitterClient + { + // ... + + public function __construct(TransformerInterface $transformer) + { + // ... + } + + // ... + } + +Finally the service definition must be updated because, obviously, the autowiring +subsystem isn't able to find itself the interface implementation to register:: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + rot13_transformer: + class: 'AppBundle\Rot13Transformer' + + twitter_client: + class: 'AppBundle\TwitterClient' + autowire: true + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + use Symfony\Component\DependencyInjection\Definition; + + // ... + $definition1 = new Definition('AppBundle\Rot13Transformer'); + $container->setDefinition('rot13_transformer', $definition1); + + $definition2 = new Definition('AppBundle\TwitterClient'); + $definition2->setAutowired(true); + $container->setDefinition('twitter_client', $definition2); + +The autowiring subsystem detects that the ``rot13_transformer`` service implements +the ``TransformerInterface`` and injects it automatically. Even when using +interfaces (and you should), building the service graph and refactoring the project +is easier than with standard definitions. + +Dealing with Multiple Implementations of the Same Type +------------------------------------------------------ + +Last but not least, the autowiring feature allows to specify the default implementation +of a given type. Let's introduce a new implementation of the ``TransformerInterface`` +returning the result of the ROT13 transformation uppercased:: + + // src/AppBundle/UppercaseRot13Transformer.php + namespace AppBundle; + + class UppercaseTransformer implements TransformerInterface + { + private $transformer; + + public function __construct(TransformerInterface $transformer) + { + $this->transformer = $transformer; + } + + public function transform($value) + { + return strtoupper($this->transformer->transform($value)); + } + } + +This class is intended to decorate the any transformer and return its value uppercased. + +We can now refactor the controller to add another endpoint leveraging this new +transformer:: + + // src/AppBundle/Controller/DefaultController.php + namespace AppBundle\Controller; + + use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; + use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method; + use Symfony\Bundle\FrameworkBundle\Controller\Controller; + use Symfony\Component\HttpFoundation\Request; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Exception\BadRequestHttpException; + + class DefaultController extends Controller + { + /** + * @Route("/tweet") + * @Method("POST") + */ + public function tweetAction(Request $request) + { + return $this->tweet($request, 'twitter_client'); + } + + /** + * @Route("/tweet-uppercase") + * @Method("POST") + */ + public function tweetUppercaseAction(Request $request) + { + return $this->tweet($request, 'uppercase_twitter_client'); + } + + private function tweet(Request $request, $service) + { + $user = $request->request->get('user'); + $key = $request->request->get('key'); + $status = $request->request->get('status'); + + if (!$user || !$key || !$status) { + throw new BadRequestHttpException(); + } + + $this->get($service)->tweet($user, $key, $status); + + return new Response('OK'); + } + } + +The last step is to update service definitions to register this new implementation +and a Twitter client using it:: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + rot13_transformer: + class: 'AppBundle\Rot13Transformer' + autowiring_types: 'AppBundle\TransformerInterface' + + twitter_client: + class: 'AppBundle\TwitterClient' + autowire: true + + uppercase_rot13_transformer: + class: 'AppBundle\UppercaseRot13Transformer' + autowire: true + + uppercase_twitter_client: + class: 'AppBundle\TwitterClient' + arguments: [ '@uppercase_rot13_transformer' ] + + .. code-block:: xml + + + + + + + + AppBundle\TransformerInterface + + + + + + + + + + .. code-block:: php + + use Symfony\Component\DependencyInjection\Reference; + use Symfony\Component\DependencyInjection\Definition; + + // ... + $definition1 = new Definition('AppBundle\Rot13Transformer'); + $definition1->setAutowiringTypes(array('AppBundle\TransformerInterface')); + $container->setDefinition('rot13_transformer', $definition1); + + $definition2 = new Definition('AppBundle\TwitterClient'); + $definition2->setAutowired(true); + $container->setDefinition('twitter_client', $definition2); + + $definition3 = new Definition('AppBundle\UppercaseRot13Transformer'); + $definition3->setAutowired(true); + $container->setDefinition('uppercase_rot13_transformer', $definition3); + + $definition4 = new Definition('AppBundle\TwitterClient'); + $definition4->addArgument(new Reference('uppercase_rot13_transformer')); + $container->setDefinition('uppercase_twitter_client', $definition4); + +It deserves some explanations. We now have 2 services implementing the ``TransformerInterface``. +The autowiring subsystem cannot guess which one to use, this leads to errors +like:: + + [Symfony\Component\DependencyInjection\Exception\RuntimeException] + Unable to autowire argument of type "AppBundle\TransformerInterface" for the service "twitter_client". + +Fortunately, the ``autowiring_types`` key is here to specify which implementation +to use by default. This key can take a list of types if necessary (using a YAML +array). + +Thanks to this setting, the ``rot13_transformer`` service is automatically injected +as an argument of the ``uppercase_rot13_transformer`` and ``twitter_client`` services. For +the ``uppercase_twitter_client``, we use a standard service definition to inject +the specific ``uppercase_rot13_transformer`` service. + +As for other RAD features such as the FrameworkBundle controller or annotations, +keep in mind to not use autowiring in public bundles nor in large projects with +complex maintenance needs. + +.. _Rapid Application Development: https://en.wikipedia.org/wiki/Rapid_application_development +.. _ROT13: https://en.wikipedia.org/wiki/ROT13 diff --git a/components/dependency_injection/index.rst b/components/dependency_injection/index.rst index 313f29af3f4..bc6ec0daf73 100644 --- a/components/dependency_injection/index.rst +++ b/components/dependency_injection/index.rst @@ -8,6 +8,7 @@ DependencyInjection types parameters definitions + autowiring synthetic_services compilation tags diff --git a/components/map.rst.inc b/components/map.rst.inc index dfead75f62c..64f2b8c70f2 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -46,6 +46,7 @@ * :doc:`/components/dependency_injection/types` * :doc:`/components/dependency_injection/parameters` * :doc:`/components/dependency_injection/definitions` + * :doc:`/components/dependency_injection/autowiring` * :doc:`/components/dependency_injection/synthetic_services` * :doc:`/components/dependency_injection/compilation` * :doc:`/components/dependency_injection/tags` From d1e3024e12d0cf339241d288460b2557c51b9a50 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Wed, 10 Feb 2016 19:45:51 +0100 Subject: [PATCH 12/12] [#6032] some tweaks for the autowiring feature --- .../dependency_injection/autowiring.rst | 48 +++++++++++-------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/components/dependency_injection/autowiring.rst b/components/dependency_injection/autowiring.rst index 86287d5d5a7..46196cc846d 100644 --- a/components/dependency_injection/autowiring.rst +++ b/components/dependency_injection/autowiring.rst @@ -4,13 +4,17 @@ Defining Services Dependencies Automatically ============================================ +.. versionadded:: 2.8 + Support for autowiring services was introduced in Symfony 2.8. + Autowiring allows to register services in the container with minimal configuration. -It is useful in the field of `Rapid Application Development`_, when designing prototypes -in early stages of large projects. It makes it easy to register a service graph -and eases refactoring. +It automatically resolves the service dependencies based on the constructor's +typehint which is useful in the field of `Rapid Application Development`_, +when designing prototypes in early stages of large projects. It makes it easy +to register a service graph and eases refactoring. -Imagine you're building an API to publish statuses on a Twitter feed, obfuscated -with `ROT13`.. (a special case of the Caesar cipher). +Imagine you're building an API to publish statuses on a Twitter feed, which +has to be obfuscated with ``ROT13`` (a special case of the Caesar cipher). Start by creating a ROT13 transformer class:: @@ -47,8 +51,9 @@ And now a Twitter client using this transformer:: } } -The Dependency Injection Component will be able to automatically register the dependencies -of this ``TwitterClient`` class by marking the ``twitter_client`` service as autowired: +The DependencyInjection component will be able to automatically register +the dependencies of this ``TwitterClient`` class when the ``twitter_client`` +service is marked as autowired: .. configuration-block:: @@ -133,9 +138,11 @@ Here is a typical controller using the ``twitter_client`` service:: } } -You can give a try to the API with ``curl``:: +You can give the API a try using ``curl``: + +.. code-block:: bash - curl -d "user=kevin&key=ABCD&status=Hello" http://localhost:8000/tweet + $ curl -d "user=kevin&key=ABCD&status=Hello" http://localhost:8000/tweet It should return ``OK``. @@ -316,20 +323,20 @@ and a Twitter client using it:: # app/config/services.yml services: rot13_transformer: - class: 'AppBundle\Rot13Transformer' - autowiring_types: 'AppBundle\TransformerInterface' + class: AppBundle\Rot13Transformer + autowiring_types: AppBundle\TransformerInterface twitter_client: - class: 'AppBundle\TwitterClient' + class: AppBundle\TwitterClient autowire: true uppercase_rot13_transformer: - class: 'AppBundle\UppercaseRot13Transformer' + class: AppBundle\UppercaseRot13Transformer autowire: true uppercase_twitter_client: - class: 'AppBundle\TwitterClient' - arguments: [ '@uppercase_rot13_transformer' ] + class: AppBundle\TwitterClient + arguments: ['@uppercase_rot13_transformer'] .. code-block:: xml @@ -373,16 +380,17 @@ and a Twitter client using it:: $definition4->addArgument(new Reference('uppercase_rot13_transformer')); $container->setDefinition('uppercase_twitter_client', $definition4); -It deserves some explanations. We now have 2 services implementing the ``TransformerInterface``. -The autowiring subsystem cannot guess which one to use, this leads to errors -like:: +This deserves some explanations. You now have two services implementing the +``TransformerInterface``. The autowiring subsystem cannot guess which one +to use which leads to errors like this: + +.. code-block:: text [Symfony\Component\DependencyInjection\Exception\RuntimeException] Unable to autowire argument of type "AppBundle\TransformerInterface" for the service "twitter_client". Fortunately, the ``autowiring_types`` key is here to specify which implementation -to use by default. This key can take a list of types if necessary (using a YAML -array). +to use by default. This key can take a list of types if necessary. Thanks to this setting, the ``rot13_transformer`` service is automatically injected as an argument of the ``uppercase_rot13_transformer`` and ``twitter_client`` services. For