From 421aa41611175fb43cf3fbd473dbce8287ee5c17 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Thu, 9 Oct 2014 20:51:12 +1300 Subject: [PATCH 001/103] ref #4272 Documentation for the new PropertyNormalizer introduced in symfony/symfony#9708 --- components/serializer.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/components/serializer.rst b/components/serializer.rst index 0d26457d0aa..e88c065d964 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -238,6 +238,30 @@ When serializing, you can set a callback to format a specific object property:: $serializer->serialize($person, 'json'); // Output: {"name":"cordoval", "age": 34, "createdAt": "2014-03-22T09:43:12-0500"} +Normalizers +----------- + +There are several types of normalizers available:: + +* The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` + +This normalizer reads the content of the class by calling the "getters" (public +methods starting with "get"). It will denormalize data by calling the constructor +and the "setters" (public methods starting with "set"). + +Objects are serialized to a map of property names (method name stripped of the "get" +prefix and converted to lower case) to property values. + +* The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` + +.. versionadded:: 2.6 + The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` + class was introduced in Symfony 2.6. + +This normalizer directly reads and writes public properties as well as +**private and protected** properties. Objects are serialized to a map of +property names to property values. + Handling Circular References ---------------------------- From 4815c4afa09fa5214e1dec462eb9e811c8f6f779 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Sun, 19 Oct 2014 10:35:30 +1300 Subject: [PATCH 002/103] Introduction about normalizers --- components/serializer.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/components/serializer.rst b/components/serializer.rst index e88c065d964..55de8434c7f 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -50,6 +50,8 @@ which Encoders and Normalizer are going to be available:: $serializer = new Serializer($normalizers, $encoders); +There are several normalizers available, e.g. the :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` or the :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`. To read more about them, refer to the "Normalizers" section in this page. All the examples shown below use the GetSetMethodNormalizer. + Serializing an Object --------------------- From 6868a1999a5849acf9e4a5e7174936f6d6288ed7 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Thu, 9 Oct 2014 22:53:53 +1300 Subject: [PATCH 003/103] Updated the rendering of the list --- components/serializer.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index 55de8434c7f..a7684342adc 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -247,22 +247,22 @@ There are several types of normalizers available:: * The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` -This normalizer reads the content of the class by calling the "getters" (public -methods starting with "get"). It will denormalize data by calling the constructor -and the "setters" (public methods starting with "set"). + This normalizer reads the content of the class by calling the "getters" (public + methods starting with "get"). It will denormalize data by calling the constructor + and the "setters" (public methods starting with "set"). -Objects are serialized to a map of property names (method name stripped of the "get" -prefix and converted to lower case) to property values. + Objects are serialized to a map of property names (method name stripped of the "get" + prefix and converted to lower case) to property values. * The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` -.. versionadded:: 2.6 - The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` - class was introduced in Symfony 2.6. + .. versionadded:: 2.6 + The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` + class was introduced in Symfony 2.6. -This normalizer directly reads and writes public properties as well as -**private and protected** properties. Objects are serialized to a map of -property names to property values. + This normalizer directly reads and writes public properties as well as + **private and protected** properties. Objects are serialized to a map of + property names to property values. Handling Circular References ---------------------------- From 629c8acb43a35a2bdb5bc9a9fb6ad0c4a61fad59 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Sun, 2 Nov 2014 00:03:09 +1300 Subject: [PATCH 004/103] =?UTF-8?q?Added=20line=20returns=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/serializer.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/components/serializer.rst b/components/serializer.rst index a7684342adc..03ac95ed5ef 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -50,7 +50,11 @@ which Encoders and Normalizer are going to be available:: $serializer = new Serializer($normalizers, $encoders); -There are several normalizers available, e.g. the :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` or the :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`. To read more about them, refer to the "Normalizers" section in this page. All the examples shown below use the GetSetMethodNormalizer. +There are several normalizers available, e.g. the +:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` or the +:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`. +To read more about them, refer to the "Normalizers" section in this page. +All the examples shown below use the GetSetMethodNormalizer. Serializing an Object --------------------- From fa95eb0e65ef88c8572e4bf12acdc2e184966b3a Mon Sep 17 00:00:00 2001 From: Bocharsky Victor Date: Wed, 4 Feb 2015 12:18:14 +0200 Subject: [PATCH 005/103] Add excluded_ajax_paths new parameter in v2.6 Based on post [New in Symfony 2.6: AJAX requests in the web debug toolbar](http://symfony.com/blog/new-in-symfony-2-6-ajax-requests-in-the-web-debug-toolbar) --- reference/configuration/web_profiler.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/reference/configuration/web_profiler.rst b/reference/configuration/web_profiler.rst index 50ad25c9043..700732c7afa 100644 --- a/reference/configuration/web_profiler.rst +++ b/reference/configuration/web_profiler.rst @@ -23,10 +23,14 @@ Full default Configuration # gives you the opportunity to look at the collected data before following the redirect intercept_redirects: false + # Exclude AJAX requests in the web debug toolbar for specified paths + excluded_ajax_paths: ^/bundles|^/_wdt + .. code-block:: xml From 1b5fcf0a524f433abc7651ab7243a23ec9bfddcd Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Feb 2015 17:20:59 +0100 Subject: [PATCH 006/103] Reworded the explanation about optional command options --- components/console/introduction.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index a57068990fa..8b678518008 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -296,9 +296,12 @@ declare a one-letter shortcut that you can call with a single dash like .. tip:: - It is also possible to make an option *optionally* accept a value (so that - ``--yell``, ``--yell=loud`` or ``--yell loud`` work). Options can also be configured to - accept an array of values. + It may look that it's possible to make an option *optionally* accept a value + (so that ``--yell`` or ``--yell=loud`` work). However, if you call a command + with an option without a value, you'll retrieve ``null`` as the option's value + which is the same when you omit the option. In practice, this means that a + command cannot distinguish between passing an option without a value and not + passing that very same option. For example, add a new option to the command that can be used to specify how many times in a row the message should be printed:: From 44f4da082ce71527c1acbcce46b9ec779c07d87d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Feb 2015 17:55:41 +0100 Subject: [PATCH 007/103] Added a note about the Symfony versions affected by ICU problems --- components/intl.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/components/intl.rst b/components/intl.rst index 90ac1808f13..bcecb379196 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -62,6 +62,11 @@ code:: .. sidebar:: ICU and Deployment Problems + .. note:: + + These deployment problems only affect to the following Symfony versions: + 2.3.0 to 2.3.20 versions, any 2.4.x version and 2.5.0 to 2.5.5 versions. + The intl extension internally uses the `ICU library`_ to obtain localization data such as number formats in different languages, country names and more. To make this data accessible to userland PHP libraries, Symfony ships a copy From 8c0de1bc10e13276dc504cf63bf5592176d76f0e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Feb 2015 18:04:05 +0100 Subject: [PATCH 008/103] Minow grammar fix --- components/intl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/intl.rst b/components/intl.rst index bcecb379196..eb10a717e9a 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -64,7 +64,7 @@ code:: .. note:: - These deployment problems only affect to the following Symfony versions: + These deployment problems only affect the following Symfony versions: 2.3.0 to 2.3.20 versions, any 2.4.x version and 2.5.0 to 2.5.5 versions. The intl extension internally uses the `ICU library`_ to obtain localization From 4422c101a278e1cbe00e2cf5286f9fd3fde253af Mon Sep 17 00:00:00 2001 From: rs Date: Wed, 18 Feb 2015 21:29:10 +0100 Subject: [PATCH 009/103] tip for mapping definition If you follow the link from the security documentation (http://symfony.com/doc/current/book/security.html#loading-users-from-the-database), it's easy to miss the necessary mapping definition for the repository. --- cookbook/security/entity_provider.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst index 98df1da6a69..3b545389b6a 100644 --- a/cookbook/security/entity_provider.rst +++ b/cookbook/security/entity_provider.rst @@ -583,6 +583,11 @@ The code below shows the implementation of the } } +.. tip:: + + Don't forget to + :ref: `add the repository class to the mapping definition of your entity `. + To finish the implementation, the configuration of the security layer must be changed to tell Symfony to use the new custom entity provider instead of the generic Doctrine entity provider. It's trivial to achieve by removing the From c5b8926a0d3921e6fd3f83e1813bd13104970555 Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Wed, 18 Feb 2015 23:32:19 +0100 Subject: [PATCH 010/103] #4032 improved comments about em option --- cookbook/form/data_transformers.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst index 072d02a1aa8..adc5596ec51 100644 --- a/cookbook/form/data_transformers.rst +++ b/cookbook/form/data_transformers.rst @@ -122,7 +122,9 @@ by calling ``addModelTransformer`` (or ``addViewTransformer`` - see { // ... - // this assumes that the entity manager was passed in as an option + // the "em" is an option that you pass when creating your form. Check out + // the 3rd argument to createForm in the next code block to see how this + // is passed to the form (also see setDefaultOptions). $entityManager = $options['em']; $transformer = new IssueToNumberTransformer($entityManager); From f64b5b5c5e3fb060d2a042a68f457ed86a1107ea Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 10:40:52 +0100 Subject: [PATCH 011/103] Added an example about how to get the impersonating user object --- cookbook/security/impersonating_user.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index 8966357a198..14b4af6c59c 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -86,6 +86,23 @@ to show a link to exit impersonation: +In some cases you may need to get the object that represents the impersonating +user rather than the impersonated user. Use the following snippet to iterate +over user's roles until you get the ``SwitchUserRole`` related to the +impersonating user:: + + use Symfony\Component\Security\Core\Role\SwitchUserRole; + + $securityContext = $this->get('security.context'); + + if ($securityContext->isGranted('ROLE_PREVIOUS_ADMIN')) { + foreach ($securityContext->getToken()->getRoles() as $role) { + if ($role instanceof SwitchUserRole) { + $impersonatingUser = $role->getSource()->getUser(); + } + } + } + Of course, this feature needs to be made available to a small group of users. By default, access is restricted to users having the ``ROLE_ALLOWED_TO_SWITCH`` role. The name of this role can be modified via the ``role`` setting. For From 470f7130ab4aae5fed193b517aab55d7094a868a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 11:15:13 +0100 Subject: [PATCH 012/103] Added a note about the server_version DBAL option --- cookbook/doctrine/dbal.rst | 5 +++++ reference/configuration/doctrine.rst | 24 +++++++++++++++++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/cookbook/doctrine/dbal.rst b/cookbook/doctrine/dbal.rst index 39cb0eabeaf..006c99371ef 100644 --- a/cookbook/doctrine/dbal.rst +++ b/cookbook/doctrine/dbal.rst @@ -35,6 +35,7 @@ To get started, configure the database connection parameters: user: root password: null charset: UTF8 + server_version: 5.6 .. code-block:: xml @@ -45,6 +46,8 @@ To get started, configure the database connection parameters: dbname="Symfony" user="root" password="null" + charset="UTF8" + server-version="5.6" driver="pdo_mysql" /> @@ -58,6 +61,8 @@ To get started, configure the database connection parameters: 'dbname' => 'Symfony', 'user' => 'root', 'password' => null, + 'charset' => 'UTF8', + 'server_version' => '5.6', ), )); diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index d11044e632a..0ca3c03cf64 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -60,6 +60,9 @@ Full Default Configuration driver: pdo_mysql platform_service: ~ + # the version of your database engine + server_version: ~ + # when true, queries are logged to a "doctrine" monolog channel logging: "%kernel.debug%" profiling: "%kernel.debug%" @@ -102,6 +105,9 @@ Full Default Configuration # True to use a pooled server with the oci8 driver pooled: ~ + # the version of your database engine + server_version: ~ + # Configuring MultipleActiveResultSets for the pdo_sqlsrv driver MultipleActiveResultSets: ~ @@ -202,6 +208,7 @@ Full Default Configuration charset="UTF8" logging="%kernel.debug%" platform-service="MyOwnDatabasePlatformService" + server-version="5.6" > bar string @@ -393,6 +400,7 @@ The following block shows all possible configuration keys: charset: UTF8 logging: "%kernel.debug%" platform_service: MyOwnDatabasePlatformService + server_version: 5.6 mapping_types: enum: string types: @@ -428,7 +436,8 @@ The following block shows all possible configuration keys: wrapper-class="MyDoctrineDbalConnectionWrapper" charset="UTF8" logging="%kernel.debug%" - platform-service="MyOwnDatabasePlatformService"> + platform-service="MyOwnDatabasePlatformService" + server-version="5.6"> bar string @@ -437,6 +446,17 @@ The following block shows all possible configuration keys: +.. note:: + + The ``server_version`` option was added in Doctrine DBAL 2.5, which is used + by DoctrineBundle 1.3 version. The value of this option should match your + database server version (use ``postgres -V`` or ``psql -V`` command to find + your PostgreSQL version and ``mysql -V`` to get your MySQL version). + + If you don't define this option and you don't have created your database yet, + you may get ``PDOException`` errors because Doctrine will try to guess the + database server version automatically and none is available. + If you want to configure multiple connections in YAML, put them under the ``connections`` key and give them a unique name: @@ -451,11 +471,13 @@ If you want to configure multiple connections in YAML, put them under the user: root password: null host: localhost + server_version: 5.6 customer: dbname: customer user: root password: null host: localhost + server_version: 5.7 The ``database_connection`` service always refers to the *default* connection, which is the first one defined or the one configured via the From 27ca37297b28fdcec171906b30bdceba2f7a7ae6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 11:38:06 +0100 Subject: [PATCH 013/103] Added a note about the class option of the services defined via factories --- components/dependency_injection/factories.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/components/dependency_injection/factories.rst b/components/dependency_injection/factories.rst index 6727bc838a5..8acbe0c0444 100644 --- a/components/dependency_injection/factories.rst +++ b/components/dependency_injection/factories.rst @@ -68,6 +68,13 @@ class: $container->setDefinition('newsletter_manager', $definition); +.. note:: + + When creating a service through a factory, the value chosen for the ``class`` + option has no actual effect since the final class only depends on the object + returned by the factory. However, the configured class may be used by compiler + passes and therefore should be set to a sensible value. + When you specify the class to use for the factory (via ``factory_class``) the method will be called statically. If the factory itself should be instantiated and the resulting object's method called, configure the factory itself as a service. From 477da91e1ff9f5f54bbf504f60f61f26eddc6cd0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 11:58:11 +0100 Subject: [PATCH 014/103] Minor rewording --- components/dependency_injection/factories.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/components/dependency_injection/factories.rst b/components/dependency_injection/factories.rst index 8acbe0c0444..ae0693361e9 100644 --- a/components/dependency_injection/factories.rst +++ b/components/dependency_injection/factories.rst @@ -71,9 +71,10 @@ class: .. note:: When creating a service through a factory, the value chosen for the ``class`` - option has no actual effect since the final class only depends on the object - returned by the factory. However, the configured class may be used by compiler - passes and therefore should be set to a sensible value. + option has no effect on the resulting service, since the actual class name + only depends on the object returned by the factory. However, the configured + class may be used by compiler passes and therefore should be set to a + sensible value. When you specify the class to use for the factory (via ``factory_class``) the method will be called statically. If the factory itself should be instantiated From e7c9605584624592a2e3cc839e8defbe227763be Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 11:59:12 +0100 Subject: [PATCH 015/103] Adding a break statement to improve the sample code --- cookbook/security/impersonating_user.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index 14b4af6c59c..b790f58384f 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -99,6 +99,7 @@ impersonating user:: foreach ($securityContext->getToken()->getRoles() as $role) { if ($role instanceof SwitchUserRole) { $impersonatingUser = $role->getSource()->getUser(); + break; } } } From 81b6a0eb36b4a766b053de7611af7bf02c353abc Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 13:30:45 +0100 Subject: [PATCH 016/103] Added a commented config useful when you use symlinks --- .../configuration/web_server_configuration.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst index f246e24ee26..59528aa83c6 100644 --- a/cookbook/configuration/web_server_configuration.rst +++ b/cookbook/configuration/web_server_configuration.rst @@ -48,6 +48,12 @@ are: Allow from All + # uncomment the following lines if you install assets as symlinks + # or run into problems when compiling LESS/Sass/CoffeScript assets + # + # Option FollowSymlinks + # + ErrorLog /var/log/apache2/project_error.log CustomLog /var/log/apache2/project_access.log combined @@ -151,6 +157,12 @@ directive to pass requests for PHP files to PHP FPM: Require all granted + # uncomment the following lines if you install assets as symlinks + # or run into problems when compiling LESS/Sass/CoffeScript assets + # + # Option FollowSymlinks + # + ErrorLog /var/log/apache2/project_error.log CustomLog /var/log/apache2/project_access.log combined @@ -181,6 +193,12 @@ should look something like this: Allow from all + # uncomment the following lines if you install assets as symlinks + # or run into problems when compiling LESS/Sass/CoffeScript assets + # + # Option FollowSymlinks + # + ErrorLog /var/log/apache2/project_error.log CustomLog /var/log/apache2/project_access.log combined From 2bd8cf3afc0f9386a22b4404b1cb7a3331fd55ad Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 16:23:31 +0100 Subject: [PATCH 017/103] Added a note about data transformers not being applied with inherit_data option set --- cookbook/form/data_transformers.rst | 5 +++++ reference/forms/types/options/inherit_data.rst.inc | 6 ++++++ 2 files changed, 11 insertions(+) diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst index 072d02a1aa8..6ae8b205a3a 100644 --- a/cookbook/form/data_transformers.rst +++ b/cookbook/form/data_transformers.rst @@ -17,6 +17,11 @@ You could try to do this in your controller, but it's not the best solution. It would be better if this issue were automatically converted to an Issue object. This is where Data Transformers come into play. +.. caution:: + + When a field has the :doc:`inherit_data ` + option set, Data Transformers won't be applied to that field. + Creating the Transformer ------------------------ diff --git a/reference/forms/types/options/inherit_data.rst.inc b/reference/forms/types/options/inherit_data.rst.inc index 9f5f1510ca8..3025e018660 100644 --- a/reference/forms/types/options/inherit_data.rst.inc +++ b/reference/forms/types/options/inherit_data.rst.inc @@ -10,3 +10,9 @@ inherit_data This option determines if the form will inherit data from its parent form. This can be useful if you have a set of fields that are duplicated across multiple forms. See :doc:`/cookbook/form/inherit_data_option`. + +.. caution:: + + When a field has the ``inherit_data`` option set, it uses the data of the + parent form as is. This means that :doc:`Data Transformers ` + won't be applied to that field. From 3e9033623de83ec8c80ee74fef6e7016b74d9198 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 17:05:23 +0100 Subject: [PATCH 018/103] Fixed an internal link --- cookbook/form/data_transformers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst index 6ae8b205a3a..c726ca13086 100644 --- a/cookbook/form/data_transformers.rst +++ b/cookbook/form/data_transformers.rst @@ -19,7 +19,7 @@ This is where Data Transformers come into play. .. caution:: - When a field has the :doc:`inherit_data ` + When a field has the :doc:`inherit_data ` option set, Data Transformers won't be applied to that field. Creating the Transformer From 90956cc58dce85a77c01751b0db5edaa0ebb88da Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 17:44:03 +0100 Subject: [PATCH 019/103] Minor rewording --- components/dependency_injection/factories.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/dependency_injection/factories.rst b/components/dependency_injection/factories.rst index ae0693361e9..5cf955128d0 100644 --- a/components/dependency_injection/factories.rst +++ b/components/dependency_injection/factories.rst @@ -70,7 +70,7 @@ class: .. note:: - When creating a service through a factory, the value chosen for the ``class`` + When using a factory to create services, the value chosen for the ``class`` option has no effect on the resulting service, since the actual class name only depends on the object returned by the factory. However, the configured class may be used by compiler passes and therefore should be set to a From 25513220021d58c1b028cac8bb5e4c5e7b16e6df Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 20:14:58 +0100 Subject: [PATCH 020/103] Rewording --- components/dependency_injection/factories.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/dependency_injection/factories.rst b/components/dependency_injection/factories.rst index 5cf955128d0..7a22ba17da2 100644 --- a/components/dependency_injection/factories.rst +++ b/components/dependency_injection/factories.rst @@ -71,9 +71,9 @@ class: .. note:: When using a factory to create services, the value chosen for the ``class`` - option has no effect on the resulting service, since the actual class name - only depends on the object returned by the factory. However, the configured - class may be used by compiler passes and therefore should be set to a + option has no effect on the resulting service. The actual class name only + depends on the object that is returned by the factory. However, the configured + class name may be used by compiler passes and therefore should be set to a sensible value. When you specify the class to use for the factory (via ``factory_class``) From ca21fb6fdfc5b5d74d743198316fb5ca87bcdfd7 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 20:16:30 +0100 Subject: [PATCH 021/103] Removed a wrong link to a included file --- cookbook/form/data_transformers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst index c726ca13086..38da9e249ea 100644 --- a/cookbook/form/data_transformers.rst +++ b/cookbook/form/data_transformers.rst @@ -19,8 +19,8 @@ This is where Data Transformers come into play. .. caution:: - When a field has the :doc:`inherit_data ` - option set, Data Transformers won't be applied to that field. + When a form field has the ``inherit_data`` option set, Data Transformers + won't be applied to that field. Creating the Transformer ------------------------ From bab2a29b5b4930321e6d8a2d020e4f35165feddd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Pelletier?= Date: Sat, 25 Oct 2014 14:12:44 +0200 Subject: [PATCH 022/103] add a note about apc for php recent versions apc is not required for php5.5+, I suggest to mention it to avoid people trying to install it on recent php versions --- book/performance.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/performance.rst b/book/performance.rst index e3f296484ad..e4eef7debbd 100644 --- a/book/performance.rst +++ b/book/performance.rst @@ -18,8 +18,9 @@ Use a Byte Code Cache (e.g. APC) One of the best (and easiest) things that you should do to improve your performance is to use a "byte code cache". The idea of a byte code cache is to remove the need to constantly recompile the PHP source code. There are a number of -`byte code caches`_ available, some of which are open source. The most widely -used byte code cache is probably `APC`_ +`byte code caches`_ available, some of which are open source. If you are using +PHP 5.5 or more, the byte code cache is built-in into PHP runtime. For older versions, +the most widely used byte code cache is probably `APC`_ Using a byte code cache really has no downside, and Symfony has been architected to perform really well in this type of environment. From 221597a48634b907bb97bec18dcaa9afcf90875b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 08:46:13 +0100 Subject: [PATCH 023/103] Reworded the explanation about "optional options" --- components/console/introduction.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 8b678518008..905b6478594 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -296,12 +296,11 @@ declare a one-letter shortcut that you can call with a single dash like .. tip:: - It may look that it's possible to make an option *optionally* accept a value - (so that ``--yell`` or ``--yell=loud`` work). However, if you call a command - with an option without a value, you'll retrieve ``null`` as the option's value - which is the same when you omit the option. In practice, this means that a - command cannot distinguish between passing an option without a value and not - passing that very same option. + There is nothing forbidding you to create a command with an *optional option*, + which is an input option set to ``InputOption::OPTIONAL`` mode. You will just + not be able to distinguish when the flag for that option was used without a + value (``command --yell``) or when it was not used at all (``command``). + In both cases the value retrieved for the option will be the same ``null``. For example, add a new option to the command that can be used to specify how many times in a row the message should be printed:: From 3b96301ca026ccb94814a20fb3b178278a7704f5 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Thu, 19 Feb 2015 23:54:59 +0100 Subject: [PATCH 024/103] Applied comments --- components/serializer.rst | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index 03ac95ed5ef..3acac73a647 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -51,10 +51,10 @@ which Encoders and Normalizer are going to be available:: $serializer = new Serializer($normalizers, $encoders); There are several normalizers available, e.g. the -:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` or the -:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`. -To read more about them, refer to the "Normalizers" section in this page. -All the examples shown below use the GetSetMethodNormalizer. +:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` or +the :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`. +To read more about them, refer to the `Normalizers`_ section of this page. All +the examples shown below use the ``GetSetMethodNormalizer``. Serializing an Object --------------------- @@ -247,26 +247,24 @@ When serializing, you can set a callback to format a specific object property:: Normalizers ----------- -There are several types of normalizers available:: +There are several types of normalizers available: -* The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` +:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` + This normalizer reads the content of the class by calling the "getters" + (public methods starting with "get"). It will denormalize data by calling + the constructor and the "setters" (public methods starting with "set"). - This normalizer reads the content of the class by calling the "getters" (public - methods starting with "get"). It will denormalize data by calling the constructor - and the "setters" (public methods starting with "set"). + Objects are serialized to a map of property names (method name stripped of + the "get" prefix and converted to lower case) to property values. - Objects are serialized to a map of property names (method name stripped of the "get" - prefix and converted to lower case) to property values. +:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` + This normalizer directly reads and writes public properties as well as + **private and protected** properties. Objects are normalized to a map of + property names to property values. -* The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` - - .. versionadded:: 2.6 - The :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` - class was introduced in Symfony 2.6. - - This normalizer directly reads and writes public properties as well as - **private and protected** properties. Objects are serialized to a map of - property names to property values. +.. versionadded:: 2.6 The + :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` + class was introduced in Symfony 2.6. Handling Circular References ---------------------------- From 95d09e97b2eaf415da72b6a80458e2e96831b0d1 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 20 Feb 2015 00:16:48 +0100 Subject: [PATCH 025/103] Minor rewording --- book/performance.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/book/performance.rst b/book/performance.rst index e4eef7debbd..e3496b42476 100644 --- a/book/performance.rst +++ b/book/performance.rst @@ -18,9 +18,9 @@ Use a Byte Code Cache (e.g. APC) One of the best (and easiest) things that you should do to improve your performance is to use a "byte code cache". The idea of a byte code cache is to remove the need to constantly recompile the PHP source code. There are a number of -`byte code caches`_ available, some of which are open source. If you are using -PHP 5.5 or more, the byte code cache is built-in into PHP runtime. For older versions, -the most widely used byte code cache is probably `APC`_ +`byte code caches`_ available, some of which are open source. As of PHP 5.5, +PHP comes with `OPcache`_ built-in. For older versions, the most widely used +byte code cache is probably `APC`_ Using a byte code cache really has no downside, and Symfony has been architected to perform really well in this type of environment. @@ -140,6 +140,7 @@ feature is disabled in the byte code cache (e.g. ``apc.stat=0`` in APC), there is no longer a reason to use a bootstrap file. .. _`byte code caches`: http://en.wikipedia.org/wiki/List_of_PHP_accelerators +.. _`OPcache`: http://php.net/manual/en/book.opcache.php .. _`APC`: http://php.net/manual/en/book.apc.php .. _`autoload.php`: https://github.com/symfony/symfony-standard/blob/master/app/autoload.php .. _`bootstrap file`: https://github.com/sensio/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php From 89029cd3a27b19982a391861b7cf04285efd18fd Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 11:56:02 +0100 Subject: [PATCH 026/103] Reworded again the note about "optional options" --- components/console/introduction.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 905b6478594..15cc4e695dc 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -296,11 +296,11 @@ declare a one-letter shortcut that you can call with a single dash like .. tip:: - There is nothing forbidding you to create a command with an *optional option*, - which is an input option set to ``InputOption::OPTIONAL`` mode. You will just - not be able to distinguish when the flag for that option was used without a - value (``command --yell``) or when it was not used at all (``command``). - In both cases the value retrieved for the option will be the same ``null``. + There is nothing forbidding you to create a command with an option that + optionally accepts a value. However, there is no way you can distinguish + when the option was used without a value (``command --yell``) or when it + wasn't used at all (``command``). In both cases, the value retrieved for + the option will be ``null``. For example, add a new option to the command that can be used to specify how many times in a row the message should be printed:: From 38dcfc87e58d5866e69bcf9a38f1e2336aef5829 Mon Sep 17 00:00:00 2001 From: rs Date: Fri, 20 Feb 2015 12:06:26 +0100 Subject: [PATCH 027/103] fixed intendation and shortened the link --- cookbook/security/entity_provider.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst index 3b545389b6a..b6ce0cfc676 100644 --- a/cookbook/security/entity_provider.rst +++ b/cookbook/security/entity_provider.rst @@ -585,8 +585,8 @@ The code below shows the implementation of the .. tip:: - Don't forget to - :ref: `add the repository class to the mapping definition of your entity `. + Don't forget to add the repository class to the mapping definition of + :ref: ` your entity `. To finish the implementation, the configuration of the security layer must be changed to tell Symfony to use the new custom entity provider instead of the From 7ae3a281a102e0152e5f404b52fa12be4d9ae55e Mon Sep 17 00:00:00 2001 From: rs Date: Fri, 20 Feb 2015 12:13:30 +0100 Subject: [PATCH 028/103] improved link --- cookbook/security/entity_provider.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst index b6ce0cfc676..125f8d6a184 100644 --- a/cookbook/security/entity_provider.rst +++ b/cookbook/security/entity_provider.rst @@ -585,8 +585,8 @@ The code below shows the implementation of the .. tip:: - Don't forget to add the repository class to the mapping definition of - :ref: ` your entity `. + Don't forget to add the repository class to the + :ref: `mapping definition of your entity `. To finish the implementation, the configuration of the security layer must be changed to tell Symfony to use the new custom entity provider instead of the From c75455f92a4a3c783c96dc3ce6cc148afc62f029 Mon Sep 17 00:00:00 2001 From: guangle Date: Thu, 4 Dec 2014 09:52:46 +0100 Subject: [PATCH 029/103] Update routing.rst add route name "blog_show" in first example --- book/routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/routing.rst b/book/routing.rst index 10d15be0df1..b5cc3da9715 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -45,7 +45,7 @@ The route is simple: class BlogController extends Controller { /** - * @Route("/blog/{slug}") + * @Route("/blog/{slug}", name="blog_show") */ public function showAction($slug) { From 59624f66aa5aaecd0a2bed06070ce6d083aa4d9e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 12:23:29 +0100 Subject: [PATCH 030/103] Reworded the note about Windows console and output coloring --- components/console/introduction.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index a57068990fa..1557854e7ca 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -20,15 +20,6 @@ You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/console`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/Console). -.. note:: - - Windows does not support ANSI colors by default so the Console component detects and - disables colors where Windows does not have support. However, if Windows is not - configured with an ANSI driver and your console commands invoke other scripts which - emit ANSI color sequences, they will be shown as raw escape characters. - - To enable ANSI color support for Windows, please install `ANSICON`_. - Creating a basic Command ------------------------ @@ -124,6 +115,14 @@ This prints:: Coloring the Output ~~~~~~~~~~~~~~~~~~~ +.. note:: + + By default, Windows command console doesn't support output coloring. The + Console component disables output coloring for Windows systems, but if your + commands invoke other scripts which emit color sequences, they will be + wrongly displayed as raw escape characters. Install the free `ANSICON`_ + application to add coloring support to your Windows command console. + Whenever you output text, you can surround the text with tags to color its output. For example:: From 71f30a27d1ba1b42a082ced08fded04fbf2c9ef3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 14:19:43 +0100 Subject: [PATCH 031/103] Minor rewording --- components/console/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 1557854e7ca..50eb7534d2e 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -117,7 +117,7 @@ Coloring the Output .. note:: - By default, Windows command console doesn't support output coloring. The + By default, the Windows command console doesn't support output coloring. The Console component disables output coloring for Windows systems, but if your commands invoke other scripts which emit color sequences, they will be wrongly displayed as raw escape characters. Install the free `ANSICON`_ From ec85112e51fecb7881a5e13c125ac33a29fc9d3e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 15:37:22 +0100 Subject: [PATCH 032/103] Suggested ConEmu in addition to ANSICON to solve the Windows coloring limitation --- components/console/introduction.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 50eb7534d2e..6dd5dba52eb 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -120,8 +120,8 @@ Coloring the Output By default, the Windows command console doesn't support output coloring. The Console component disables output coloring for Windows systems, but if your commands invoke other scripts which emit color sequences, they will be - wrongly displayed as raw escape characters. Install the free `ANSICON`_ - application to add coloring support to your Windows command console. + wrongly displayed as raw escape characters. Install the `ConEmu`_ or `ANSICON`_ + free applications to add coloring support to your Windows command console. Whenever you output text, you can surround the text with tags to color its output. For example:: @@ -503,4 +503,5 @@ Learn More! * :doc:`/components/console/console_arguments` .. _Packagist: https://packagist.org/packages/symfony/console +.. _ConEmu: https://code.google.com/p/conemu-maximus5/ .. _ANSICON: https://github.com/adoxa/ansicon/releases From 8e82db44668287e39dafa5709ac6c34b5a528b36 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Fri, 20 Feb 2015 16:30:38 +0100 Subject: [PATCH 033/103] adding table for controller as a service --- cookbook/controller/service.rst | 55 +++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/cookbook/controller/service.rst b/cookbook/controller/service.rst index 1ce43de4911..efcfdd33c11 100644 --- a/cookbook/controller/service.rst +++ b/cookbook/controller/service.rst @@ -21,8 +21,10 @@ this works fine, controllers can also be specified as services. looking at the constructor arguments, it's easy to see what types of things this controller may or may not do. And because each dependency needs to be injected manually, it's more obvious (i.e. if you have many constructor - arguments) when your controller has become too big, and may need to be - split into multiple controllers. + arguments) when your controller is becoming too big. The recommendation from + the :doc:`best practices ` is also valid for + controllers defined as services: Avoid putting your business logic into the + controllers. Instead, inject services that do the bulk of the work. So, even if you don't specify your controllers as services, you'll likely see this done in some open-source Symfony bundles. It's also important @@ -232,6 +234,55 @@ inject *only* the exact service(s) that you need directly into the controller. are valid, exactly how you want to organize your reusable code is up to you. +Base Controller Methods and their Service Replacements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This table explains how to replace the convenience methods of the base +controller. + ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| Method | Service | PHP Code | ++=============================+======================+=================================================================+ +| ``createForm`` | ``form.factory`` | ``$formFactory->create($type, $data, $options)`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``createFormBuilder`` | ``form.factory`` | ``$formFactory->createBuilder('form', $data, $options)`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``createNotFoundException`` | \- | ``throw new NotFoundHttpException($message, $previous);`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``forward`` | ``http_kernel`` | ``$httpKernel->forward($controller, $path, $query)`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``generateUrl`` | ``router`` | ``$router->generate($route, $params, $absolute)`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``getDoctrine`` | ``doctrine`` | *Simply inject doctrine instead of fetching from the container* | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``getUser`` | ``security.context`` | $user = null; | +| | | $token = $securityContext->getToken(); | +| | | if (null !== $token && is_object($token->getUser())) { | +| | | $user = $token->getUser(); | +| | | } | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``isGranted`` | ``security.context`` | ``$authorizationChecker->isGranted($attributes, $object);`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``redirect`` | \- | ``return new RedirectResponse($url, $status);`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``render`` | ``templating`` | ``$templating->renderResponse($view, $parameters, $response)`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``renderViev`` | ``templating`` | ``$templating->render($view, $parameters)`` | ++-----------------------------+----------------------+-----------------------------------------------------------------+ +| ``stream`` | ``templating`` | $templating = $this->templating; | +| | | $callback = function () use ($templating, $view, $parameters) { | +| | | $templating->stream($view, $parameters); | +| | | } | +| | | return new StreamedResponse($callback); | ++-----------------------------+----------------------+-----------------------------------------------------------------+ + +.. tip:: + + ``getRequest`` has been deprecated. Instead, have an argument to your + controller action method called ``Request $request``. The order of the + parameters is not important, but the typehint must be provided. + + .. _`Controller class source code`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php .. _`base Controller class`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php .. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/routing.html From f804af90524342219f55494c88822be8223d9709 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 21 Feb 2015 10:29:31 +0100 Subject: [PATCH 034/103] Reread Form Login article --- cookbook/security/form_login_setup.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/cookbook/security/form_login_setup.rst b/cookbook/security/form_login_setup.rst index 011ab6f6894..cfed1d88679 100644 --- a/cookbook/security/form_login_setup.rst +++ b/cookbook/security/form_login_setup.rst @@ -76,20 +76,15 @@ First, enable form login under your firewall: Now, when the security system initiates the authentication process, it will redirect the user to the login form ``/login``. Implementing this login form visually is your job. First, create a new ``SecurityController`` inside a -bundle with an empty ``loginAction``:: +bundle:: // src/AppBundle/Controller/SecurityController.php namespace AppBundle\Controller; - use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; use Symfony\Bundle\FrameworkBundle\Controller\Controller; class SecurityController extends Controller { - public function loginAction(Request $request) - { - // todo... - } } Next, create two routes: one for each of the paths your configured earlier @@ -100,7 +95,9 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``): .. code-block:: php-annotations // src/AppBundle/Controller/SecurityController.php + // ... + use Symfony\Component\HttpFoundation\Request; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; class SecurityController extends Controller @@ -110,7 +107,6 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``): */ public function loginAction(Request $request) { - // todo ... } /** @@ -118,6 +114,8 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``): */ public function loginCheckAction() { + // this controller will not be executed, + // as the route is handled by the Security system } } @@ -129,6 +127,8 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``): defaults: { _controller: AppBundle:Security:login } login_check: path: /login_check + # no controller is bound to this route + # as it's handled by the Security system .. code-block:: xml @@ -144,6 +144,8 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``): + .. code-block:: php @@ -157,6 +159,8 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``): '_controller' => 'AppBundle:Security:login', ))); $collection->add('login_check', new Route('/login_check', array())); + // no controller is bound to this route + // as it's handled by the Security system return $collection; @@ -164,20 +168,18 @@ Great! Next, add the logic to ``loginAction`` that will display the login form:: // src/AppBundle/Controller/SecurityController.php - // ... - // ADD THIS use STATEMENT above your class + // ... use Symfony\Component\Security\Core\SecurityContextInterface; + // ... public function loginAction(Request $request) { $session = $request->getSession(); // get the login error if there is one if ($request->attributes->has(SecurityContextInterface::AUTHENTICATION_ERROR)) { - $error = $request->attributes->get( - SecurityContextInterface::AUTHENTICATION_ERROR - ); + $error = $request->attributes->get(SecurityContextInterface::AUTHENTICATION_ERROR); } elseif (null !== $session && $session->has(SecurityContextInterface::AUTHENTICATION_ERROR)) { $error = $session->get(SecurityContextInterface::AUTHENTICATION_ERROR); $session->remove(SecurityContextInterface::AUTHENTICATION_ERROR); From 77342fa097fcb4324d216c236447624b6d0a9341 Mon Sep 17 00:00:00 2001 From: "M.Wiesner" Date: Sat, 13 Dec 2014 17:27:36 +0100 Subject: [PATCH 035/103] Update the_controller.rst Corrected error in the sample code. --- quick_tour/the_controller.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst index 114b2e587b3..36d38c131f3 100644 --- a/quick_tour/the_controller.rst +++ b/quick_tour/the_controller.rst @@ -205,8 +205,8 @@ different controller using the ``forward()`` method:: public function indexAction() { return $this->forward('AppBundle:Blog:index', array( - 'name' => $name - ); + 'name' => 'Fabien' + )); } } From 17c9257c6f9c97035c9d6c50bc5ee2ca9d5b65d3 Mon Sep 17 00:00:00 2001 From: "M.Wiesner" Date: Sat, 13 Dec 2014 21:09:56 +0100 Subject: [PATCH 036/103] Update the_controller.rst --- quick_tour/the_controller.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst index 36d38c131f3..a581ff2b45f 100644 --- a/quick_tour/the_controller.rst +++ b/quick_tour/the_controller.rst @@ -205,7 +205,7 @@ different controller using the ``forward()`` method:: public function indexAction() { return $this->forward('AppBundle:Blog:index', array( - 'name' => 'Fabien' + 'name' => 'Fabien', )); } } From dbc25a6fb5d2c870958b462b7a998512049ba44b Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 21 Feb 2015 10:33:35 +0100 Subject: [PATCH 037/103] Removed forwarding section from the quick tour --- quick_tour/the_controller.rst | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst index a581ff2b45f..bc90f0af99b 100644 --- a/quick_tour/the_controller.rst +++ b/quick_tour/the_controller.rst @@ -172,8 +172,10 @@ The ``hello`` action will now match URLs like ``/hello/fabien.xml`` or like ``/hello/fabien.js``, because the value of the ``_format`` variable doesn't meet its requirements. -Redirecting and Forwarding --------------------------- +.. _redirecting-and-forwarding: + +Redirecting +----------- If you want to redirect the user to another page, use the ``redirectToRoute()`` method:: @@ -193,23 +195,6 @@ method:: The ``redirectToRoute()`` method takes as arguments the route name and an optional array of parameters and redirects the user to the URL generated with those arguments. -You can also internally forward the action to another action of the same or -different controller using the ``forward()`` method:: - - // src/AppBundle/Controller/DefaultController.php - class DefaultController extends Controller - { - /** - * @Route("/", name="homepage") - */ - public function indexAction() - { - return $this->forward('AppBundle:Blog:index', array( - 'name' => 'Fabien', - )); - } - } - Displaying Error Pages ---------------------- From daff2713d0c08579b9f5353bfb25b563f4e1a479 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 24 Feb 2015 17:38:31 +0100 Subject: [PATCH 038/103] Minor improvement in the node types explanation --- components/config/definition.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index b4b0dcd5c19..21d28fdf91a 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -95,13 +95,13 @@ Node Type ~~~~~~~~~ It is possible to validate the type of a provided value by using the appropriate -node definition. Node type are available for: +node definition. Node types are available for: -* scalar +* scalar (generic type that includes booleans, strings, integers, floats and ``null``) * boolean * integer (new in 2.2) * float (new in 2.2) -* enum (new in 2.1) +* enum (new in 2.1) (similar to array, but it only allows a finite set of values) * array * variable (no validation) From c774b8a81772b7bffb7b1025cf154ac6fda5d879 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 24 Feb 2015 17:58:02 +0100 Subject: [PATCH 039/103] Improved a bit the information about dumping config --- components/config/definition.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index 21d28fdf91a..8ad3763142e 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -294,7 +294,8 @@ All options can be documented using the :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::info` method. -The info will be printed as a comment when dumping the configuration tree. +The info will be printed as a comment when dumping the configuration tree with +the ``config:dump`` command. Optional Sections ----------------- From 96c423a4008662e1323e4ba851d5200aae145164 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 24 Feb 2015 18:34:21 +0100 Subject: [PATCH 040/103] Moved the admonition about the INI loader to the loaders section --- components/config/introduction.rst | 7 ------- components/config/resources.rst | 7 +++++++ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/components/config/introduction.rst b/components/config/introduction.rst index 11dae2e1d78..b4d075c3b58 100644 --- a/components/config/introduction.rst +++ b/components/config/introduction.rst @@ -9,13 +9,6 @@ The Config Component combine, autofill and validate configuration values of any kind, whatever their source may be (YAML, XML, INI files, or for instance a database). -.. caution:: - - The ``IniFileLoader`` parses the file contents using the - :phpfunction:`parse_ini_file` function, therefore, you can only set - parameters to string values. To set parameters to other data types - (e.g. boolean, integer, etc), the other loaders are recommended. - Installation ------------ diff --git a/components/config/resources.rst b/components/config/resources.rst index a1d46565803..1a5fba23c2b 100644 --- a/components/config/resources.rst +++ b/components/config/resources.rst @@ -4,6 +4,13 @@ Loading Resources ================= +.. caution:: + + The ``IniFileLoader`` parses the file contents using the + :phpfunction:`parse_ini_file` function. Therefore, you can only set + parameters to string values. To set parameters to other data types + (e.g. boolean, integer, etc), the other loaders are recommended. + Locating Resources ------------------ From 3bcb18653796fced2bdaa62aa7eb21b7d2e0a7b7 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Fri, 8 Aug 2014 16:33:04 +0200 Subject: [PATCH 041/103] Added shortcut methods for controllers --- book/controller.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index e79af5c803c..875446a242c 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -459,6 +459,10 @@ perform a 301 (permanent) redirect, modify the second argument:: return new RedirectResponse($this->generateUrl('homepage')); + You can also directly use ``redirectToRoute()`` and give it directly the route name like : + + return $this->redirectToRoute('homepage'); + .. index:: single: Controller; Rendering templates @@ -638,8 +642,13 @@ After processing the request, the controller sets a ``notice`` flash message in the session and then redirects. The name (``notice``) isn't significant - it's just something you invent and reference next. -In the template of the next page (or even better, in your base layout template), -the following code will render the ``notice`` message: +.. tip:: + + You can use the ``addFlash()`` method as a shortcut to + ``$this->get('session')->getFlashBag()->add()``. + +In the template of the next action, the following code could be used to render +the ``notice`` message: .. configuration-block:: From 4611ce9742b445ee8ad9d4e86f2f08947e1bba95 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Fri, 8 Aug 2014 17:12:43 +0200 Subject: [PATCH 042/103] Minor format improvements --- book/controller.rst | 12 +++++++----- book/security.rst | 21 +++++++++++++++++++-- 2 files changed, 26 insertions(+), 7 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index 875446a242c..5adfa4502c0 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -459,7 +459,10 @@ perform a 301 (permanent) redirect, modify the second argument:: return new RedirectResponse($this->generateUrl('homepage')); - You can also directly use ``redirectToRoute()`` and give it directly the route name like : +.. versionadded:: 2.6 + You can also directly use + :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::redirectToRoute`` + and give it directly the route name like : return $this->redirectToRoute('homepage'); @@ -642,10 +645,9 @@ After processing the request, the controller sets a ``notice`` flash message in the session and then redirects. The name (``notice``) isn't significant - it's just something you invent and reference next. -.. tip:: - - You can use the ``addFlash()`` method as a shortcut to - ``$this->get('session')->getFlashBag()->add()``. +.. versionadded:: 2.6 + You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::addFlash`` + method as a shortcut to ``$this->get('session')->getFlashBag()->add(...)``. In the template of the next action, the following code could be used to render the ``notice`` message: diff --git a/book/security.rst b/book/security.rst index cb383cfa7d9..23070a4e726 100644 --- a/book/security.rst +++ b/book/security.rst @@ -804,6 +804,17 @@ the ``^``) would match ``/admin/foo`` but would also match URLs like ``/foo/admi .. _`book-security-securing-controller`: + +Securing other Services +~~~~~~~~~~~~~~~~~~~~~~~ + +In fact, anything in Symfony can be protected using a strategy similar to +the one seen in the previous section. For example, suppose you have a service +(i.e. a PHP class) whose job is to send emails from one user to another. +You can restrict use of this class - no matter where it's being used from - +to users that have a specific role. +>>>>>>> Minor format improvements + Securing Controllers and other Code ................................... @@ -813,8 +824,8 @@ You can easily deny access from inside a controller:: public function helloAction($name) { - if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) { - throw $this->createAccessDeniedException(); + if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) { + throw $this->createAccessDeniedException('Unable to access this page!'); } // ... @@ -831,6 +842,12 @@ The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAcc method creates a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException` object, which ultimately triggers a 403 HTTP response inside Symfony. +.. versionadded:: 2.6 + You can use directly `$this->isGranted($role)` instead of + `$this->get('security.context')->isGranted($role)` to check if + a role is granted and `denyAccessUnlessGranted` to throw an exception + if the access is not granted (like in the example above). + That's it! If the user isn't logged in yet, they will be asked to login (e.g. redirected to the login page). If they *are* logged in, they'll be shown the 403 access denied page (which you can :ref:`customize `). From 7ae62e82227b7b524607a5450ea33b72a73d5124 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Fri, 8 Aug 2014 17:15:55 +0200 Subject: [PATCH 043/103] Minor improvements --- book/controller.rst | 4 ++-- book/security.rst | 15 +++++++++++---- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index 5adfa4502c0..0bff6722fdd 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -461,7 +461,7 @@ perform a 301 (permanent) redirect, modify the second argument:: .. versionadded:: 2.6 You can also directly use - :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::redirectToRoute`` + :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::redirectToRoute` and give it directly the route name like : return $this->redirectToRoute('homepage'); @@ -646,7 +646,7 @@ in the session and then redirects. The name (``notice``) isn't significant - it's just something you invent and reference next. .. versionadded:: 2.6 - You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::addFlash`` + You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::addFlash` method as a shortcut to ``$this->get('session')->getFlashBag()->add(...)``. In the template of the next action, the following code could be used to render diff --git a/book/security.rst b/book/security.rst index 23070a4e726..8ac043aea51 100644 --- a/book/security.rst +++ b/book/security.rst @@ -802,9 +802,6 @@ the ``^``) would match ``/admin/foo`` but would also match URLs like ``/foo/admi To learn about all of this, see :doc:`/cookbook/security/access_control`. -.. _`book-security-securing-controller`: - - Securing other Services ~~~~~~~~~~~~~~~~~~~~~~~ @@ -813,11 +810,15 @@ the one seen in the previous section. For example, suppose you have a service (i.e. a PHP class) whose job is to send emails from one user to another. You can restrict use of this class - no matter where it's being used from - to users that have a specific role. ->>>>>>> Minor format improvements + +.. _`book-security-securing-controller`: Securing Controllers and other Code ................................... +Securing a Controller +~~~~~~~~~~~~~~~~~~~~~ + You can easily deny access from inside a controller:: // ... @@ -835,6 +836,12 @@ You can easily deny access from inside a controller:: The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service. +.. versionadded:: 2.6 + You can use directly :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::isGranted` + instead of `$this->get('security.context')->isGranted($role)` to check if + a role is granted and :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::denyAccessUnlessGranted` + to throw an exception if the access is not granted (like in the example above). + .. versionadded:: 2.5 The ``createAccessDeniedException`` method was introduced in Symfony 2.5. From 643c458a039e28b3d0bec8d3c76cd5a7784eed80 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Tue, 30 Sep 2014 09:18:55 +0200 Subject: [PATCH 044/103] redirect changed to redirectToRoute --- book/controller.rst | 25 ++++++------------------- book/doctrine.rst | 2 +- book/forms.rst | 6 +++--- book/propel.rst | 2 +- book/validation.rst | 2 +- components/form/introduction.rst | 2 +- cookbook/doctrine/file_uploads.rst | 6 +++--- cookbook/doctrine/registration_form.rst | 2 +- cookbook/form/direct_submit.rst | 6 +++--- cookbook/form/form_collections.rst | 2 +- 10 files changed, 21 insertions(+), 34 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index 0bff6722fdd..be705aad29a 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -429,43 +429,30 @@ A great way to see the core functionality in action is to look in the Redirecting ~~~~~~~~~~~ -If you want to redirect the user to another page, use the -:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect` -method:: +If you want to redirect the user to another page, use the ``redirectToRoute()`` method:: public function indexAction() { - return $this->redirect($this->generateUrl('homepage')); + return $this->redirectToRoute('homepage'); } -The ``generateUrl()`` method is just a helper function that generates the URL -for a given route. For more information, see the :doc:`Routing ` -chapter. - -By default, the ``redirect()`` method performs a 302 (temporary) redirect. To +By default, the ``redirectToRoute()`` method performs a 302 (temporary) redirect. To perform a 301 (permanent) redirect, modify the second argument:: public function indexAction() { - return $this->redirect($this->generateUrl('homepage'), 301); + return $this->redirectToRoute('homepage', 301); } .. tip:: - The ``redirect()`` method is simply a shortcut that creates a ``Response`` + The ``redirectToRoute()`` method is simply a shortcut that creates a ``Response`` object that specializes in redirecting the user. It's equivalent to:: use Symfony\Component\HttpFoundation\RedirectResponse; return new RedirectResponse($this->generateUrl('homepage')); -.. versionadded:: 2.6 - You can also directly use - :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::redirectToRoute` - and give it directly the route name like : - - return $this->redirectToRoute('homepage'); - .. index:: single: Controller; Rendering templates @@ -635,7 +622,7 @@ For example, imagine you're processing a form submit:: 'Your changes were saved!' ); - return $this->redirect($this->generateUrl(...)); + return $this->redirectToRoute(...); } return $this->render(...); diff --git a/book/doctrine.rst b/book/doctrine.rst index e60ab0118fe..989e6df93eb 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -667,7 +667,7 @@ you have a route that maps a product id to an update action in a controller:: $product->setName('New product name!'); $em->flush(); - return $this->redirect($this->generateUrl('homepage')); + return $this->redirectToRoute('homepage'); } Updating an object involves just three steps: diff --git a/book/forms.rst b/book/forms.rst index 7bdfd2d991c..4eba6a4f60e 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -234,7 +234,7 @@ controller:: if ($form->isValid()) { // perform some action, such as saving the task to the database - return $this->redirect($this->generateUrl('task_success')); + return $this->redirectToRoute('task_success'); } // ... @@ -319,7 +319,7 @@ querying if the "Save and add" button was clicked:: ? 'task_new' : 'task_success'; - return $this->redirect($this->generateUrl($nextAction)); + return $this->redirectToRoute($nextAction); } .. index:: @@ -1233,7 +1233,7 @@ it after a form submission can be done when the form is valid:: $em->persist($task); $em->flush(); - return $this->redirect($this->generateUrl('task_success')); + return $this->redirectToRoute('task_success'); } If, for some reason, you don't have access to your original ``$task`` object, diff --git a/book/propel.rst b/book/propel.rst index 9ff589afb04..483fbfdaedb 100644 --- a/book/propel.rst +++ b/book/propel.rst @@ -234,7 +234,7 @@ have a route that maps a product id to an update action in a controller:: $product->setName('New product name!'); $product->save(); - return $this->redirect($this->generateUrl('homepage')); + return $this->redirectToRoute('homepage'); } Updating an object involves just three steps: diff --git a/book/validation.rst b/book/validation.rst index a7a6a3c1d75..fd4264d7a1d 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -231,7 +231,7 @@ workflow looks like the following from inside a controller:: if ($form->isValid()) { // the validation passed, do something with the $author object - return $this->redirect($this->generateUrl(...)); + return $this->redirectToRoute(...); } return $this->render('BlogBundle:Author:form.html.twig', array( diff --git a/components/form/introduction.rst b/components/form/introduction.rst index 7321a1029a1..2e4a6e891f9 100644 --- a/components/form/introduction.rst +++ b/components/form/introduction.rst @@ -587,7 +587,7 @@ method: // ... perform some action, such as saving the data to the database - return $this->redirect($this->generateUrl('task_success')); + return $this->redirectToRoute('task_success'); } // ... diff --git a/cookbook/doctrine/file_uploads.rst b/cookbook/doctrine/file_uploads.rst index ab52ae4c940..21910b7d2d2 100644 --- a/cookbook/doctrine/file_uploads.rst +++ b/cookbook/doctrine/file_uploads.rst @@ -244,7 +244,7 @@ The following controller shows you how to handle the entire process:: $em->persist($document); $em->flush(); - return $this->redirect($this->generateUrl(...)); + return $this->redirectToRoute(...); } return array('form' => $form->createView()); @@ -267,7 +267,7 @@ in a moment to handle the file upload:: $em->persist($document); $em->flush(); - return $this->redirect(...); + return $this->redirectToRoute(...); } The ``upload()`` method will take advantage of the :class:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile` @@ -432,7 +432,7 @@ call to ``$document->upload()`` should be removed from the controller:: $em->persist($document); $em->flush(); - return $this->redirect(...); + return $this->redirectToRoute(...); } .. note:: diff --git a/cookbook/doctrine/registration_form.rst b/cookbook/doctrine/registration_form.rst index 4e4abbb5a05..b6849791212 100644 --- a/cookbook/doctrine/registration_form.rst +++ b/cookbook/doctrine/registration_form.rst @@ -287,7 +287,7 @@ the validation and saves the data into the database:: $em->persist($registration->getUser()); $em->flush(); - return $this->redirect(...); + return $this->redirectToRoute(...); } return $this->render( diff --git a/cookbook/form/direct_submit.rst b/cookbook/form/direct_submit.rst index 221f7f534d8..7166210319b 100644 --- a/cookbook/form/direct_submit.rst +++ b/cookbook/form/direct_submit.rst @@ -25,7 +25,7 @@ submissions:: if ($form->isValid()) { // perform some action... - return $this->redirect($this->generateUrl('task_success')); + return $this->redirectToRoute('task_success'); } return $this->render('AcmeTaskBundle:Default:new.html.twig', array( @@ -66,7 +66,7 @@ method, pass the submitted data directly to if ($form->isValid()) { // perform some action... - return $this->redirect($this->generateUrl('task_success')); + return $this->redirectToRoute('task_success'); } } @@ -111,7 +111,7 @@ a convenient shortcut to the previous example:: if ($form->isValid()) { // perform some action... - return $this->redirect($this->generateUrl('task_success')); + return $this->redirectToRoute('task_success'); } } diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 638a1dc2f49..32ccbc263f6 100644 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -717,7 +717,7 @@ the relationship between the removed ``Tag`` and ``Task`` object. $em->flush(); // redirect back to some edit page - return $this->redirect($this->generateUrl('task_edit', array('id' => $id))); + return $this->redirectToRoute('task_edit', array('id' => $id)); } // render some form template From 46e2505edbea59a80ae843477419738f07fb3119 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Tue, 30 Sep 2014 09:23:45 +0200 Subject: [PATCH 045/103] Changed to addFlash where it is possible (ie in controllers) --- book/controller.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index be705aad29a..746e9f6c5ec 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -617,7 +617,7 @@ For example, imagine you're processing a form submit:: if ($form->isValid()) { // do some sort of processing - $request->getSession()->getFlashBag()->add( + $this->addFlash( 'notice', 'Your changes were saved!' ); @@ -632,10 +632,6 @@ After processing the request, the controller sets a ``notice`` flash message in the session and then redirects. The name (``notice``) isn't significant - it's just something you invent and reference next. -.. versionadded:: 2.6 - You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::addFlash` - method as a shortcut to ``$this->get('session')->getFlashBag()->add(...)``. - In the template of the next action, the following code could be used to render the ``notice`` message: From 7f9bc8cdb7ff42443affe5029536285e58a8d2c3 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Tue, 30 Sep 2014 09:29:53 +0200 Subject: [PATCH 046/103] And now the same for isGranted where it is possible --- book/security.rst | 21 +++++---------------- cookbook/security/remember_me.rst | 10 +--------- cookbook/security/securing_services.rst | 8 +------- 3 files changed, 7 insertions(+), 32 deletions(-) diff --git a/book/security.rst b/book/security.rst index 8ac043aea51..c945cb19299 100644 --- a/book/security.rst +++ b/book/security.rst @@ -816,32 +816,17 @@ to users that have a specific role. Securing Controllers and other Code ................................... -Securing a Controller -~~~~~~~~~~~~~~~~~~~~~ - You can easily deny access from inside a controller:: // ... public function helloAction($name) { - if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) { - throw $this->createAccessDeniedException('Unable to access this page!'); - } + $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!'); // ... } -.. versionadded:: 2.6 - The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior - to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service. - -.. versionadded:: 2.6 - You can use directly :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::isGranted` - instead of `$this->get('security.context')->isGranted($role)` to check if - a role is granted and :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::denyAccessUnlessGranted` - to throw an exception if the access is not granted (like in the example above). - .. versionadded:: 2.5 The ``createAccessDeniedException`` method was introduced in Symfony 2.5. @@ -872,6 +857,10 @@ using annotations:: */ public function helloAction($name) { + $this->denyAccessUnlessGranted(new Expression( + '"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())' + )); + // ... } diff --git a/cookbook/security/remember_me.rst b/cookbook/security/remember_me.rst index 4a302a16c49..93987552e68 100644 --- a/cookbook/security/remember_me.rst +++ b/cookbook/security/remember_me.rst @@ -162,19 +162,11 @@ In the following example, the action is only allowed if the user has the public function editAction() { - if (false === $this->get('security.authorization_checker')->isGranted( - 'IS_AUTHENTICATED_FULLY' - )) { - throw new AccessDeniedException(); - } + $this->denyAccessUnlessGranted('IS_AUTHENTICATED_FULLY'); // ... } -.. versionadded:: 2.6 - The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior - to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service. - If your application is based on the Symfony Standard Edition, you can also secure your controller using annotations: diff --git a/cookbook/security/securing_services.rst b/cookbook/security/securing_services.rst index f877cffd125..fc33f05e083 100644 --- a/cookbook/security/securing_services.rst +++ b/cookbook/security/securing_services.rst @@ -14,17 +14,11 @@ and checking the current user's role:: public function helloAction($name) { - if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) { - throw new AccessDeniedException(); - } + $this->denyAccessUnlessGranted('ROLE_ADMIN'); // ... } -.. versionadded:: 2.6 - The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior - to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service. - You can also secure *any* service in a similar way by injecting the ``security.authorization_checker`` service into it. For a general introduction to injecting dependencies into services see the :doc:`/book/service_container` chapter of the book. For From 5b015f2375e6e0b837049b587a3fe12232642522 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Sun, 4 Jan 2015 12:17:32 +0100 Subject: [PATCH 047/103] Modifications according to comments --- book/controller.rst | 18 +++++++++++++++++- book/security.rst | 29 ++++++++++++++++------------- 2 files changed, 33 insertions(+), 14 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index 746e9f6c5ec..3bccb90ce6d 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -434,6 +434,20 @@ If you want to redirect the user to another page, use the ``redirectToRoute()`` public function indexAction() { return $this->redirectToRoute('homepage'); + + // redirectToRoute is equivalent to using redirect() and generateUrl() together: + // return $this->redirect($this->generateUrl('homepage'), 301); + } + +.. versionadded:: 2.6 + The ``redirectToRoute()`` method was added in Symfony 2.6. Previously (and still now), you + could use ``redirect()`` and ``generateUrl()`` together for this (see the example below). + +Or, if you want to redirect externally, just use ``redirect()`` and pass it the URL:: + + public function indexAction() + { + return $this->redirect('http://symfony.com/doc'); } By default, the ``redirectToRoute()`` method performs a 302 (temporary) redirect. To @@ -446,7 +460,7 @@ perform a 301 (permanent) redirect, modify the second argument:: .. tip:: - The ``redirectToRoute()`` method is simply a shortcut that creates a ``Response`` + The ``redirect()`` method is simply a shortcut that creates a ``Response`` object that specializes in redirecting the user. It's equivalent to:: use Symfony\Component\HttpFoundation\RedirectResponse; @@ -622,6 +636,8 @@ For example, imagine you're processing a form submit:: 'Your changes were saved!' ); + // $this->addFlash is equivalent to $this->get('session')->getFlashBag()->add + return $this->redirectToRoute(...); } diff --git a/book/security.rst b/book/security.rst index c945cb19299..cca1efebafb 100644 --- a/book/security.rst +++ b/book/security.rst @@ -816,7 +816,14 @@ to users that have a specific role. Securing Controllers and other Code ................................... -You can easily deny access from inside a controller:: +You can easily deny access from inside a controller: + +.. versionadded:: 2.6 + The ``denyAccessUnlessGranted()`` method was introduced in Symfony 2.6. Previously (and + still now), you could check access directly and throw the ``AccessDeniedException`` as shown + in the example below). + +.. code-block:: php // ... @@ -824,21 +831,17 @@ You can easily deny access from inside a controller:: { $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!'); + // Old way : + // if (false === $this->isGranted('ROLE_ADMIN')) { + // throw $this->createAccessDeniedException('Unable to access this page!'); + // } + // ... } -.. versionadded:: 2.5 - The ``createAccessDeniedException`` method was introduced in Symfony 2.5. - -The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAccessDeniedException` -method creates a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException` -object, which ultimately triggers a 403 HTTP response inside Symfony. - -.. versionadded:: 2.6 - You can use directly `$this->isGranted($role)` instead of - `$this->get('security.context')->isGranted($role)` to check if - a role is granted and `denyAccessUnlessGranted` to throw an exception - if the access is not granted (like in the example above). +In both cases, a special +:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException` +is thrown, which ultimately triggers a 403 HTTP response inside Symfony. That's it! If the user isn't logged in yet, they will be asked to login (e.g. redirected to the login page). If they *are* logged in, they'll be shown From f807d14aaccf7e40d4f75fc73011696ffee67126 Mon Sep 17 00:00:00 2001 From: Thomas Royer Date: Sun, 4 Jan 2015 15:49:50 +0100 Subject: [PATCH 048/103] Fixes --- book/security.rst | 28 +++++++--------------------- cookbook/expression/expressions.rst | 6 ++---- 2 files changed, 9 insertions(+), 25 deletions(-) diff --git a/book/security.rst b/book/security.rst index cca1efebafb..1316111bc27 100644 --- a/book/security.rst +++ b/book/security.rst @@ -802,33 +802,18 @@ the ``^``) would match ``/admin/foo`` but would also match URLs like ``/foo/admi To learn about all of this, see :doc:`/cookbook/security/access_control`. -Securing other Services -~~~~~~~~~~~~~~~~~~~~~~~ - -In fact, anything in Symfony can be protected using a strategy similar to -the one seen in the previous section. For example, suppose you have a service -(i.e. a PHP class) whose job is to send emails from one user to another. -You can restrict use of this class - no matter where it's being used from - -to users that have a specific role. - .. _`book-security-securing-controller`: Securing Controllers and other Code ................................... -You can easily deny access from inside a controller: - -.. versionadded:: 2.6 - The ``denyAccessUnlessGranted()`` method was introduced in Symfony 2.6. Previously (and - still now), you could check access directly and throw the ``AccessDeniedException`` as shown - in the example below). - -.. code-block:: php +You can easily deny access from inside a controller:: // ... public function helloAction($name) { + // The second parameter is used to specify on what object the role is tested. $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!'); // Old way : @@ -839,6 +824,11 @@ You can easily deny access from inside a controller: // ... } +.. versionadded:: 2.6 + The ``denyAccessUnlessGranted()`` method was introduced in Symfony 2.6. Previously (and + still now), you could check access directly and throw the ``AccessDeniedException`` as shown + in the example above). + In both cases, a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException` is thrown, which ultimately triggers a 403 HTTP response inside Symfony. @@ -860,10 +850,6 @@ using annotations:: */ public function helloAction($name) { - $this->denyAccessUnlessGranted(new Expression( - '"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())' - )); - // ... } diff --git a/cookbook/expression/expressions.rst b/cookbook/expression/expressions.rst index 63fc728343c..73e43745bb8 100644 --- a/cookbook/expression/expressions.rst +++ b/cookbook/expression/expressions.rst @@ -33,11 +33,9 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object:: public function indexAction() { - if (!$this->get('security.authorization_checker')->isGranted(new Expression( + $this->denyAccessUnlessGranted(new Expression( '"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())' - ))) { - throw $this->createAccessDeniedException(); - } + )); // ... } From 544a6769b7cdc471f007f5c96356b9a76c945dce Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 1 Mar 2015 21:42:29 +0100 Subject: [PATCH 049/103] [OptionsResolver] Fixed deprecated functionality usage --- cookbook/form/create_form_type_extension.rst | 2 +- cookbook/form/data_transformers.rst | 8 ++------ 2 files changed, 3 insertions(+), 7 deletions(-) diff --git a/cookbook/form/create_form_type_extension.rst b/cookbook/form/create_form_type_extension.rst index 02cef5f12b7..4d855c1d5f3 100644 --- a/cookbook/form/create_form_type_extension.rst +++ b/cookbook/form/create_form_type_extension.rst @@ -216,7 +216,7 @@ it in the view:: */ public function setDefaultOptions(OptionsResolverInterface $resolver) { - $resolver->setOptional(array('image_path')); + $resolver->setDefined(array('image_path')); } /** diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst index 072d02a1aa8..ff848e90b87 100644 --- a/cookbook/form/data_transformers.rst +++ b/cookbook/form/data_transformers.rst @@ -139,12 +139,8 @@ by calling ``addModelTransformer`` (or ``addViewTransformer`` - see ->setDefaults(array( 'data_class' => 'Acme\TaskBundle\Entity\Task', )) - ->setRequired(array( - 'em', - )) - ->setAllowedTypes(array( - 'em' => 'Doctrine\Common\Persistence\ObjectManager', - )); + ->setRequired(array('em')) + ->setAllowedTypes('em', 'Doctrine\Common\Persistence\ObjectManager') // ... } From 987f5a58b1852ef87e8084d15cd0a977e27c8690 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 2 Mar 2015 09:00:16 +0100 Subject: [PATCH 050/103] "enum" is similar to "scalar", not "array" --- components/config/definition.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index 8ad3763142e..396328ef687 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -101,7 +101,7 @@ node definition. Node types are available for: * boolean * integer (new in 2.2) * float (new in 2.2) -* enum (new in 2.1) (similar to array, but it only allows a finite set of values) +* enum (new in 2.1) (similar to scalar, but it only allows a finite set of values) * array * variable (no validation) From 0195619ad152d675c3261c0c907c2e6051f254c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Terje=20Br=C3=A5ten?= Date: Mon, 2 Mar 2015 19:53:33 +0000 Subject: [PATCH 051/103] [Reference] Add missing option delivery_whitelist Q | A -------- Doc fix? | yes New docs? | no Applies to | SwiftMailerBundle 2.1 Fixed tickets | no --- reference/configuration/swiftmailer.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index 3aaf52b858a..69cd75208d0 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -32,6 +32,7 @@ Configuration * `threshold`_ * `sleep`_ * `delivery_address`_ +* `delivery_whitelist`_ * `disable_delivery`_ * `logging`_ @@ -156,6 +157,17 @@ emails sent during development go to a single account. This uses ``Swift_Plugins_RedirectingPlugin``. Original recipients are available on the ``X-Swift-To``, ``X-Swift-Cc`` and ``X-Swift-Bcc`` headers. +delivery_whitelist ++~~~~~~~~~~~~~~~~~~ ++ ++**type**: ``array`` ++ ++Used in combination with ``delivery_address``. If set, emails matching any of these +patterns will be delivered like normal, instead of being sent to `delivery_address`. +For details, see `the Cookbook entry.`_ + +.. _`the Cookbook entry.`: http://symfony.com/doc/current/cookbook/email/dev_environment.html#sending-to-a-specified-address-but-with-exceptions + disable_delivery ~~~~~~~~~~~~~~~~ From 07855f6790a1491a4ed28c9e5c78bad85ed802c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Terje=20Br=C3=A5ten?= Date: Mon, 2 Mar 2015 20:32:05 +0000 Subject: [PATCH 052/103] Removed + from copied diff --- reference/configuration/swiftmailer.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index 69cd75208d0..96fc743cd58 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -158,11 +158,11 @@ This uses ``Swift_Plugins_RedirectingPlugin``. Original recipients are available on the ``X-Swift-To``, ``X-Swift-Cc`` and ``X-Swift-Bcc`` headers. delivery_whitelist -+~~~~~~~~~~~~~~~~~~ -+ -+**type**: ``array`` -+ -+Used in combination with ``delivery_address``. If set, emails matching any of these +~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` + +Used in combination with ``delivery_address``. If set, emails matching any of these patterns will be delivered like normal, instead of being sent to `delivery_address`. For details, see `the Cookbook entry.`_ From ce8719df6e10a09a79ffe1b025d7301a11ded9ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Terje=20Br=C3=A5ten?= Date: Mon, 2 Mar 2015 20:54:51 +0000 Subject: [PATCH 053/103] Changed link into ref --- reference/configuration/swiftmailer.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index 96fc743cd58..5286f97c721 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -164,9 +164,7 @@ delivery_whitelist Used in combination with ``delivery_address``. If set, emails matching any of these patterns will be delivered like normal, instead of being sent to `delivery_address`. -For details, see `the Cookbook entry.`_ - -.. _`the Cookbook entry.`: http://symfony.com/doc/current/cookbook/email/dev_environment.html#sending-to-a-specified-address-but-with-exceptions +For details, see :ref:`the cookbook entry ` disable_delivery ~~~~~~~~~~~~~~~~ From 2aab241b6f47ac0011d1a9ecef41cf0f49028d3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Terje=20Br=C3=A5ten?= Date: Mon, 2 Mar 2015 21:21:02 +0000 Subject: [PATCH 054/103] added link target/label in the cookbook --- cookbook/email/dev_environment.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cookbook/email/dev_environment.rst b/cookbook/email/dev_environment.rst index 45719625773..bf16761a78b 100644 --- a/cookbook/email/dev_environment.rst +++ b/cookbook/email/dev_environment.rst @@ -119,6 +119,8 @@ the replaced address, so you can still see who it would have been sent to. These are ``X-Swift-Cc`` and ``X-Swift-Bcc`` for the ``CC`` and ``BCC`` addresses respectively. +.. _sending-to-a-specified-address-but-with-exceptions: + Sending to a Specified Address but with Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 03279dc229bb05b6f4ffac4bc9521c2312256617 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Terje=20Br=C3=A5ten?= Date: Tue, 3 Mar 2015 09:34:36 +0000 Subject: [PATCH 055/103] Added double backticks. And also a full stop. --- reference/configuration/swiftmailer.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index 5286f97c721..d9614377bb3 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -163,8 +163,8 @@ delivery_whitelist **type**: ``array`` Used in combination with ``delivery_address``. If set, emails matching any of these -patterns will be delivered like normal, instead of being sent to `delivery_address`. -For details, see :ref:`the cookbook entry ` +patterns will be delivered like normal, instead of being sent to ``delivery_address``. +For details, see :ref:`the cookbook entry. ` disable_delivery ~~~~~~~~~~~~~~~~ From 598e522f3f68682e11fd3e4d418b2fd55eca77ae Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 6 Mar 2015 17:34:07 +0100 Subject: [PATCH 056/103] Updated documentation standards (code examples and English use) --- contributing/documentation/standards.rst | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 39d073ec0da..ce68e98d2a3 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -8,7 +8,8 @@ Sphinx ------ * The following characters are chosen for different heading levels: level 1 - is ``=``, level 2 ``-``, level 3 ``~``, level 4 ``.`` and level 5 ``"``; + is ``=`` (equal sign), level 2 ``-`` (dash), level 3 ``~`` (tilde), level 4 + ``.`` (dot) and level 5 ``"`` (double quote); * Each line should break approximately after the first word that crosses the 72nd character (so most lines end up being 72-78 characters); * The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP @@ -48,6 +49,12 @@ Example Code Examples ------------- +* The code examples should look real for a web application context. Avoid abstract + and puerile examples (``foo``, ``bar``, ``demo``, etc.); +* Use ``Acme`` when the code requires to explicit a vendor name; +* The code should follow the :doc:`Symfony Best Practices `. + Unless the example requires to use a custom bundle, make sure to always use the + ``AppBundle`` bundle to store your code; * The code follows the :doc:`Symfony Coding Standards ` as well as the `Twig Coding Standards`_; * To avoid horizontal scrolling on code blocks, we prefer to break a line @@ -137,8 +144,17 @@ Files and Directories English Language Standards -------------------------- -* **English Dialect**: use the United States English dialect, commonly called - `American English`_. +Symfony documentation uses the United States English dialect, commonly called +`American English`_. + +Unlike most popular languages, the English language doesn't have a central +language authority and there is no official grammar or dictionary. Symfony +documentation uses the `American English Oxford Dictionary`_ to resolve disputes +over common words. In case a technical word isn't included in the dictionary yet, +Symfony Documentation maintainers will decide over the disputes. + +In addition, documentation contents should follow these rules: + * **Section titles**: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for the closed-class words (read Wikipedia article about `headings and titles`_). @@ -160,6 +176,7 @@ English Language Standards .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html .. _`American English`: http://en.wikipedia.org/wiki/American_English +.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/ .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma .. _`nosism`: http://en.wikipedia.org/wiki/Nosism From 9c443518b0f4ccd9f6301514f126b2af70754671 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 7 Mar 2015 17:14:50 +0100 Subject: [PATCH 057/103] Rewords, tweaks and fixes --- contributing/documentation/standards.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index ce68e98d2a3..a0e1a611a4d 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -49,14 +49,14 @@ Example Code Examples ------------- +* The code follows the :doc:`Symfony Coding Standards ` + as well as the `Twig Coding Standards`_; * The code examples should look real for a web application context. Avoid abstract - and puerile examples (``foo``, ``bar``, ``demo``, etc.); -* Use ``Acme`` when the code requires to explicit a vendor name; -* The code should follow the :doc:`Symfony Best Practices `. + or puerile examples (``foo``, ``bar``, ``demo``, etc.); +* The code should follow the :doc:`Symfony Best Practices `. Unless the example requires to use a custom bundle, make sure to always use the ``AppBundle`` bundle to store your code; -* The code follows the :doc:`Symfony Coding Standards ` - as well as the `Twig Coding Standards`_; +* Use ``Acme`` when the code requires a vendor name; * To avoid horizontal scrolling on code blocks, we prefer to break a line correctly if it crosses the 85th character; * When you fold one or more lines of code, place ``...`` in a comment at the point @@ -145,13 +145,9 @@ English Language Standards -------------------------- Symfony documentation uses the United States English dialect, commonly called -`American English`_. - -Unlike most popular languages, the English language doesn't have a central -language authority and there is no official grammar or dictionary. Symfony -documentation uses the `American English Oxford Dictionary`_ to resolve disputes -over common words. In case a technical word isn't included in the dictionary yet, -Symfony Documentation maintainers will decide over the disputes. +`American English`_. Disputes over vocabulary will always be resolved using the +`American English Oxford Dictionary`_ reference. Disputes over neologisms not +included yet in the dictionary will be resolved by Symfony Documentation maintainers. In addition, documentation contents should follow these rules: From f5b9934e75da4a10b2e81a031bf59418746aa57b Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Sun, 8 Mar 2015 10:57:21 +0100 Subject: [PATCH 058/103] enclose data type with double backticks --- reference/forms/types/options/data.rst.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index 9873740cf48..13afdfc44ac 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -1,7 +1,7 @@ data ~~~~ -**type**: mixed **default**: Defaults to field of the underlying object (if there is one) +**type**: ``mixed`` **default**: Defaults to field of the underlying object (if there is one) When you create a form, each field initially displays the value of the corresponding property of the form's domain object (if an object is bound From b17f422654ba9690ed592b112c738db9270971f4 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Sat, 21 Feb 2015 16:27:10 +0100 Subject: [PATCH 059/103] use definition list instead of table --- cookbook/controller/service.rst | 114 +++++++++++++++++++++----------- 1 file changed, 75 insertions(+), 39 deletions(-) diff --git a/cookbook/controller/service.rst b/cookbook/controller/service.rst index efcfdd33c11..97320377c11 100644 --- a/cookbook/controller/service.rst +++ b/cookbook/controller/service.rst @@ -234,47 +234,83 @@ inject *only* the exact service(s) that you need directly into the controller. are valid, exactly how you want to organize your reusable code is up to you. -Base Controller Methods and their Service Replacements +Base Controller Methods and Their Service Replacements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This table explains how to replace the convenience methods of the base -controller. - -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| Method | Service | PHP Code | -+=============================+======================+=================================================================+ -| ``createForm`` | ``form.factory`` | ``$formFactory->create($type, $data, $options)`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``createFormBuilder`` | ``form.factory`` | ``$formFactory->createBuilder('form', $data, $options)`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``createNotFoundException`` | \- | ``throw new NotFoundHttpException($message, $previous);`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``forward`` | ``http_kernel`` | ``$httpKernel->forward($controller, $path, $query)`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``generateUrl`` | ``router`` | ``$router->generate($route, $params, $absolute)`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``getDoctrine`` | ``doctrine`` | *Simply inject doctrine instead of fetching from the container* | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``getUser`` | ``security.context`` | $user = null; | -| | | $token = $securityContext->getToken(); | -| | | if (null !== $token && is_object($token->getUser())) { | -| | | $user = $token->getUser(); | -| | | } | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``isGranted`` | ``security.context`` | ``$authorizationChecker->isGranted($attributes, $object);`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``redirect`` | \- | ``return new RedirectResponse($url, $status);`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``render`` | ``templating`` | ``$templating->renderResponse($view, $parameters, $response)`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``renderViev`` | ``templating`` | ``$templating->render($view, $parameters)`` | -+-----------------------------+----------------------+-----------------------------------------------------------------+ -| ``stream`` | ``templating`` | $templating = $this->templating; | -| | | $callback = function () use ($templating, $view, $parameters) { | -| | | $templating->stream($view, $parameters); | -| | | } | -| | | return new StreamedResponse($callback); | -+-----------------------------+----------------------+-----------------------------------------------------------------+ +This list explains how to replace the convenience methods of the base +controller: + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createForm` (service: ``form.factory``) + .. code-block:: php + + $formFactory->create($type, $data, $options); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createFormBuilder` (service: ``form.factory``) + .. code-block:: php + + $formFactory->createBuilder('form', $data, $options); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createNotFoundException` + .. code-block:: php + + new NotFoundHttpException($message, $previous); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::forward` (service: ``http_kernel``) + .. code-block:: php + + $httpKernel->forward($controller, $path, $query); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::generateUrl` (service: ``router``) + .. code-block:: php + + $router->generate($route, $params, $absolute); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` (service: ``doctrine``) + + *Simply inject doctrine instead of fetching it from the container* + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getUser` (service: ``security.context``) + .. code-block:: php + + $user = null; + $token = $securityContext->getToken(); + if (null !== $token && is_object($token->getUser())) { + $user = $token->getUser(); + } + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isGranted` (service: ``security.context``) + .. code-block:: php + + $authorizationChecker->isGranted($attributes, $object); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect` + .. code-block:: php + + use Symfony\Component\HttpFoundation\RedirectResponse; + + return new RedirectResponse($url, $status); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::render` (service: ``templating``) + .. code-block:: php + + $templating->renderResponse($view, $parameters, $response); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::renderView` (service: ``templating``) + .. code-block:: php + + $templating->render($view, $parameters); + +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::stream` (service: ``templating``) + .. code-block:: php + + use Symfony\Component\HttpFoundation\StreamedResponse; + + $templating = $this->templating; + $callback = function () use ($templating, $view, $parameters) { + $templating->stream($view, $parameters); + } + + return new StreamedResponse($callback); .. tip:: From b96abbb3ae62a7ff23356bb44d17a2e2263b72f4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Mar 2015 11:59:33 +0100 Subject: [PATCH 060/103] Reworded the paragraph about enforcing an English reference --- contributing/documentation/standards.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index a0e1a611a4d..db3e0624585 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -145,11 +145,10 @@ English Language Standards -------------------------- Symfony documentation uses the United States English dialect, commonly called -`American English`_. Disputes over vocabulary will always be resolved using the -`American English Oxford Dictionary`_ reference. Disputes over neologisms not -included yet in the dictionary will be resolved by Symfony Documentation maintainers. +`American English`_. The `American English Oxford Dictionary`_ is used as the +vocabulary reference. -In addition, documentation contents should follow these rules: +In addition, documentation follows these rules: * **Section titles**: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for From e5b6145aaba6bd93e7bdc885eb2e60b4135f5df3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Mar 2015 12:00:22 +0100 Subject: [PATCH 061/103] Improved the URL of the English reference dictionary --- contributing/documentation/standards.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index db3e0624585..e87e065c8ca 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -171,7 +171,7 @@ In addition, documentation follows these rules: .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html .. _`American English`: http://en.wikipedia.org/wiki/American_English -.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/ +.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/definition/american_english/ .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma .. _`nosism`: http://en.wikipedia.org/wiki/Nosism From 994ed3a4ab0f19961a51bb992e4887a49e1e3cd2 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 10 Mar 2015 11:12:52 +0100 Subject: [PATCH 062/103] Little fixes --- book/controller.rst | 14 +++++++++----- book/security.rst | 2 +- cookbook/security/securing_services.rst | 20 ++++++++++---------- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index 3bccb90ce6d..d424d8b4426 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -441,7 +441,7 @@ If you want to redirect the user to another page, use the ``redirectToRoute()`` .. versionadded:: 2.6 The ``redirectToRoute()`` method was added in Symfony 2.6. Previously (and still now), you - could use ``redirect()`` and ``generateUrl()`` together for this (see the example below). + could use ``redirect()`` and ``generateUrl()`` together for this (see the example above). Or, if you want to redirect externally, just use ``redirect()`` and pass it the URL:: @@ -455,17 +455,21 @@ perform a 301 (permanent) redirect, modify the second argument:: public function indexAction() { - return $this->redirectToRoute('homepage', 301); + return $this->redirectToRoute('homepage', array(), 301); } .. tip:: - The ``redirect()`` method is simply a shortcut that creates a ``Response`` - object that specializes in redirecting the user. It's equivalent to:: + The ``redirectToRoute()`` method is simply a shortcut that creates a + ``Response`` object that specializes in redirecting the user. It's + equivalent to:: use Symfony\Component\HttpFoundation\RedirectResponse; - return new RedirectResponse($this->generateUrl('homepage')); + public function indexAction() + { + return new RedirectResponse($this->generateUrl('homepage')); + } .. index:: single: Controller; Rendering templates diff --git a/book/security.rst b/book/security.rst index 1316111bc27..f96a277c256 100644 --- a/book/security.rst +++ b/book/security.rst @@ -817,7 +817,7 @@ You can easily deny access from inside a controller:: $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!'); // Old way : - // if (false === $this->isGranted('ROLE_ADMIN')) { + // if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) { // throw $this->createAccessDeniedException('Unable to access this page!'); // } diff --git a/cookbook/security/securing_services.rst b/cookbook/security/securing_services.rst index fc33f05e083..0b37720654a 100644 --- a/cookbook/security/securing_services.rst +++ b/cookbook/security/securing_services.rst @@ -5,9 +5,10 @@ How to Secure any Service or Method in your Application ======================================================= -In the security chapter, you can see how to :ref:`secure a controller ` -by requesting the ``security.authorization_checker`` service from the Service Container -and checking the current user's role:: +In the security chapter, you can see how to +:ref:`secure a controller ` by requesting +the ``security.authorization_checker`` service from the Service Container and +checking the current user's role:: // ... use Symfony\Component\Security\Core\Exception\AccessDeniedException; @@ -19,21 +20,19 @@ and checking the current user's role:: // ... } -You can also secure *any* service in a similar way by injecting the ``security.authorization_checker`` +You can also secure *any* service by injecting the ``security.authorization_checker`` service into it. For a general introduction to injecting dependencies into services see the :doc:`/book/service_container` chapter of the book. For example, suppose you have a ``NewsletterManager`` class that sends out emails -and you want to restrict its use to only users who have some ``ROLE_NEWSLETTER_ADMIN`` -role. Before you add security, the class looks something like this: - -.. code-block:: php +and you want to restrict its use to only users who have some +``ROLE_NEWSLETTER_ADMIN`` role. Before you add security, the class looks +something like this:: // src/AppBundle/Newsletter/NewsletterManager.php namespace AppBundle\Newsletter; class NewsletterManager { - public function sendNewsletter() { // ... where you actually do the work @@ -49,8 +48,9 @@ check, this is an ideal candidate for constructor injection, which guarantees that the authorization checker object will be available inside the ``NewsletterManager`` class:: - namespace AppBundle\Newsletter; + // src/AppBundle/Newsletter/NewsletterManager.php + // ... use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface; class NewsletterManager From 6ea16f0a0fa2b554777ddc2a8e8e711f9c7ef0e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katharina=20St=C3=B6rmer?= Date: Tue, 10 Mar 2015 22:09:47 +0100 Subject: [PATCH 063/103] Fixed incorrect plural form --- book/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/testing.rst b/book/testing.rst index 4a836f6c313..ebe3b003c60 100644 --- a/book/testing.rst +++ b/book/testing.rst @@ -377,7 +377,7 @@ or perform more complex requests:: array('photo' => $photo) ); - // Perform a DELETE requests, and pass HTTP headers + // Perform a DELETE request, and pass HTTP headers $client->request( 'DELETE', '/post/12', From 712a8588ced3ddcc62d6d1f87f949579ed1ea4f1 Mon Sep 17 00:00:00 2001 From: Omer Karadagli Date: Wed, 11 Mar 2015 00:48:07 +0000 Subject: [PATCH 064/103] Add missing use statement in Building Login Form doc Also removed use statement for Route as it is only needed when using annotations for routing --- cookbook/security/form_login_setup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/security/form_login_setup.rst b/cookbook/security/form_login_setup.rst index 011ab6f6894..607cfd37586 100644 --- a/cookbook/security/form_login_setup.rst +++ b/cookbook/security/form_login_setup.rst @@ -81,8 +81,8 @@ bundle with an empty ``loginAction``:: // src/AppBundle/Controller/SecurityController.php namespace AppBundle\Controller; - use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; use Symfony\Bundle\FrameworkBundle\Controller\Controller; + use Symfony\Component\HttpFoundation\Request; class SecurityController extends Controller { From 5b527aed85ab26188ec74fa4dd2f9e5abed701b1 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 11 Mar 2015 15:38:03 +0100 Subject: [PATCH 065/103] Removed an admonition that is no longer true for Symfony 2.6+ --- cookbook/serializer.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/cookbook/serializer.rst b/cookbook/serializer.rst index 762a0f86d19..75910f61e31 100644 --- a/cookbook/serializer.rst +++ b/cookbook/serializer.rst @@ -101,11 +101,4 @@ Here is an example on how to load the $definition->addTag('serializer.normalizer'); $container->setDefinition('get_set_method_normalizer', $definition); -.. note:: - - The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` - is broken by design. As soon as you have a circular object graph, an - infinite loop is created when calling the getters. You're encouraged - to add your own normalizers that fit your use-case. - .. _JMSSerializerBundle: http://jmsyst.com/bundles/JMSSerializerBundle From 7fc1145ba3736cc329c22d7a1b6700e124231cbf Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Thu, 12 Mar 2015 18:39:42 +0100 Subject: [PATCH 066/103] link to deciders' GitHub profiles --- contributing/code/core_team.rst | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/contributing/code/core_team.rst b/contributing/code/core_team.rst index 55f0332bde7..eb57b929428 100644 --- a/contributing/code/core_team.rst +++ b/contributing/code/core_team.rst @@ -37,37 +37,37 @@ Active Core Members * **Project Leader**: - * **Fabien Potencier** (:leader:`fabpot`). + * **Fabien Potencier** (`fabpot`_). * **Mergers** (``@symfony/mergers`` on GitHub): - * **Bernhard Schussek** (:merger:`webmozart`) can merge into the Form_, + * **Bernhard Schussek** (`webmozart`_) can merge into the Form_, Validator_, Icu_, Intl_, Locale_, OptionsResolver_ and PropertyAccess_ components; - * **Tobias Schultze** (:merger:`Tobion`) can merge into the Routing_ + * **Tobias Schultze** (`Tobion`_) can merge into the Routing_ component; - * **Romain Neutron** (:merger:`romainneutron`) can merge into the + * **Romain Neutron** (`romainneutron`_) can merge into the Process_ component; - * **Nicolas Grekas** (:merger:`nicolas-grekas`) can merge into the Debug_ + * **Nicolas Grekas** (`nicolas-grekas`_) can merge into the Debug_ component; - * **Christophe Coevoet** (:merger:`stof`) can merge into the BrowserKit_, + * **Christophe Coevoet** (`stof`_) can merge into the BrowserKit_, Config_, Console_, DependencyInjection_, DomCrawler_, EventDispatcher_, HttpFoundation_, HttpKernel_, Serializer_, Stopwatch_, DoctrineBridge_, MonologBridge_, and TwigBridge_ components; - * **Kévin Dunglas** (:merger:`dunglas`) can merge into the Serializer_ + * **Kévin Dunglas** (`dunglas`_) can merge into the Serializer_ component. * **Deciders** (``@symfony/deciders`` on GitHub): - * **Jakub Zalas** (:decider:`jakzal`); - * **Jordi Boggiano** (:decider:`seldaek`); - * **Lukas Kahwe Smith** (:decider:`lsmith77`); - * **Ryan Weaver** (:decider:`weaverryan`). + * **Jakub Zalas** (`jakzal`_); + * **Jordi Boggiano** (`seldaek`_); + * **Lukas Kahwe Smith** (`lsmith77`_); + * **Ryan Weaver** (`weaverryan`_). Core Membership Application ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -168,3 +168,14 @@ discretion of the **Project Leader**. .. _Stopwatch: https://github.com/symfony/Stopwatch .. _TwigBridge: https://github.com/symfony/TwigBridge .. _Validator: https://github.com/symfony/Validator +.. _`fabpot`: https://github.com/fabpot/ +.. _`webmozart`: https://github.com/webmozart/ +.. _`Tobion`: https://github.com/Tobion/ +.. _`romainneutron`: https://github.com/romainneutron/ +.. _`nicolas-grekas`: https://github.com/nicolas-grekas/ +.. _`stof`: https://github.com/stof/ +.. _`dunglas`: https://github.com/dunglas/ +.. _`jakzal`: https://github.com/jakzal/ +.. _`Seldaek`: https://github.com/Seldaek/ +.. _`lsmith77`: https://github.com/lsmith77/ +.. _`weaverryan`: https://github.com/weaverryan/ From 5377525fd07308a0ab9af105ece62170acacaaad Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Fri, 13 Mar 2015 20:17:10 +0100 Subject: [PATCH 067/103] some language tweaks --- cookbook/session/locale_sticky_session.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/session/locale_sticky_session.rst b/cookbook/session/locale_sticky_session.rst index 3946ed85a87..09d58a606e7 100644 --- a/cookbook/session/locale_sticky_session.rst +++ b/cookbook/session/locale_sticky_session.rst @@ -116,10 +116,10 @@ before the ``FirewallListener``, which is responsible for handling authenticatio setting the user token on the ``TokenStorage``, you have no access to the user which is logged in. -Let's pretend you have defined a ``locale"`` property on your ``User`` entity -and you want to use this as the locale for the given user. To accomplish this, -you can hook into the login process and update the user's session with the -this locale value before they are redirected to their first page. +Assumed you have defined a ``locale`` property on your ``User`` entity and +you want to use this as the locale for the given user. To accomplish this, +you can hook into the login process and update the user's session with this +locale value before they are redirected to their first page. To do this, you need an event listener for the ``security.interactive_login`` event: From 5ab1adf12eba4204dbfcf23a3f7c46c68729e6ed Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 29 Jan 2015 21:41:13 -0500 Subject: [PATCH 068/103] Adding a section to emailing showing off absolute_url --- cookbook/email/email.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/cookbook/email/email.rst b/cookbook/email/email.rst index 4d97ec31b62..431a9d60ea1 100644 --- a/cookbook/email/email.rst +++ b/cookbook/email/email.rst @@ -123,7 +123,21 @@ an email is pretty straightforward:: } To keep things decoupled, the email body has been stored in a template and -rendered with the ``renderView()`` method. +rendered with the ``renderView()`` method. The ``registration.html.twig`` +template might look something like this: + +.. code-block:: html+jinja + + {# app/Resources/views/Emails/registration.html.twig #} +

You did it! You registered!

+ + {# example, assuming you have a route named "login" $} + To login, go to: {{ url('login') }}. + + Thanks! + + {# Makes an absolute URL to the /images/logo.png file #} + Date: Fri, 13 Mar 2015 16:51:05 -0400 Subject: [PATCH 069/103] minor tweak thanks to Javier --- cookbook/email/email.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/email/email.rst b/cookbook/email/email.rst index 431a9d60ea1..7a90d0626bc 100644 --- a/cookbook/email/email.rst +++ b/cookbook/email/email.rst @@ -132,7 +132,7 @@ template might look something like this:

You did it! You registered!

{# example, assuming you have a route named "login" $} - To login, go to: {{ url('login') }}. + To login, go to: .... Thanks! From 6d367b16fb3bc9eb0d84c1c292ad0159d8dcd477 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 11 Feb 2015 12:52:51 +0100 Subject: [PATCH 070/103] Added the documentation for the new Asset component --- components/asset.rst | 249 +++++++++++++++++++++++++++++++++++++++++ components/index.rst | 1 + components/map.rst.inc | 4 + 3 files changed, 254 insertions(+) create mode 100644 components/asset.rst diff --git a/components/asset.rst b/components/asset.rst new file mode 100644 index 00000000000..ba37caa4c4a --- /dev/null +++ b/components/asset.rst @@ -0,0 +1,249 @@ +.. index:: + single: Asset + single: Components; Asset + +The Asset Component +=================== + + The Asset manages URL generation and versioning for web assets such as CSS + stylsheets, JavaScript files and image files. + +Installation +------------ + +You can install the component in two different ways: + +* :doc:`Install it via Composer ` (``symfony/asset`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/Asset). + +Usage +----- + +Asset Packages +~~~~~~~~~~~~~~ + +The Asset component manages its assets through packages. A package groups all +the assets which use the same versioning strategy. In the following basic +example, a package is created to manage assets without any versioning: + +.. code-block:: php + + use Symfony\Component\Asset\Package; + use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy; + + $package = new Package(new EmptyVersionStrategy()); + + echo $package->getUrl('/image.png'); + // result: /image.png + +Packages implement the ``PackageInterface``, which defines the following two +methods:: + + namespace Symfony\Component\Asset; + + interface PackageInterface + { + /** + * Returns the asset version for an asset. + */ + public function getVersion($path); + + /** + * Returns an absolute or root-relative public path. + */ + public function getUrl($path); + } + +Versioned Assets +~~~~~~~~~~~~~~~~ + +One of the main features of the Asset component is to manage the versioning of +the application's assets. Asset versions are commonly used to control how these +assets are cached. + +Instead of relying on a simple version mechanism, the Asset component allows to +define advanced version strategies via PHP classes. The two built-in strategies +provided by the component are ``EmptyVersionStrategy``, which doesn't add any +version to the asset, and ``StaticVersionStrategy``, which allows to set the +version with a format string. + +In this example, the ``StaticVersionStrategy`` is used to append the ``v1`` +suffix to any asset path:: + + use Symfony\Component\Asset\Package; + use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; + + $package = new Package(new StaticVersionStrategy('v1')); + + echo $package->getUrl('/image.png'); + // result: /image.png?v1 + +In case you want to modify the version format, pass a sprintf-compatible format +string as the second argument of the ``StaticVersionStrategy`` constructor:: + + // put the 'version' word before the version value + $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); + + echo $package->getUrl('/image.png'); + // result: /image.png?version=v1 + + // put the asset version before its path + $package = new Package(new StaticVersionStrategy('v1', '%2$s/%1$s')); + + echo $package->getUrl('/image.png'); + // result: /v1/image.png + +Custom Version Strategies +......................... + +Use the ``VersionStrategyInterface`` to define your own version strategy. For +example, you could define a versioning where the current date is appended to +bust the cache every day:: + + use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface; + + class DateVersionStrategy implements VersionStrategyInterface + { + private $version; + + public function __construct() + { + $this->version = date('Ymd'); + } + + public function getVersion($path) + { + return $this->version; + } + + public function applyVersion($path) + { + return sprintf('%s?v=%s', $path, $this->getVersion($path)); + } + } + +Grouped Assets +~~~~~~~~~~~~~~ + +It's common for applications to store their assets in a common path. If that's +your case, replace the default ``Package`` class by ``PathPackage`` to avoid +repeating the same path time and again:: + + use Symfony\Component\Asset\PathPackage; + + $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); + + echo $package->getUrl('/logo.png'); + // result: /static/images/logo.png?v1 + +Request Context Aware Assets +............................ + +If you are also using the HttpFoundation component in your project, for example +in a Symfony application, the ``PathPackage`` class can take into account the +context of the current request:: + + use Symfony\Component\Asset\PathPackage; + use Symfony\Component\Asset\Context\RequestStackContext; + + $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); + $package->setContext(new RequestStackContext($requestStack)); + + echo $package->getUrl('/logo.png'); + // result: /somewhere/static/images/logo.png?v1 + +When the request context is set, in addition to the configured base path, +``PathPackage`` also prepends the current request base URL (``/somewhere/`` in +this example) to assets. This allows your website to be hosted anywhere under +the web server root directory. + +Absolute Assets and CDNs +~~~~~~~~~~~~~~~~~~~~~~~~ + +Applications that host their assets on different domains and CDNs (*Content +Delivery Networks*) should use instead the ``UrlPackage`` class to generate +absolute URLs for their assets:: + + use Symfony\Component\Asset\UrlPackage; + + $package = new UrlPackage('http://static.example.com/images/', new StaticVersionStrategy('v1')); + + echo $package->getUrl('/logo.png'); + // result: http://static.example.com/images/logo.png?v1 + +In case you serve assets from more than one domain to improve application +performance, pass an array of URLs as the first argument of ``UrlPackage`` +constructor:: + + use Symfony\Component\Asset\UrlPackage; + + $urls = array( + 'http://static1.example.com/images/', + 'http://static2.example.com/images/', + ); + $package = new UrlPackage($urls, new StaticVersionStrategy('v1')); + + echo $package->getUrl('/logo.png'); + // result: http://static1.example.com/images/logo.png?v1 + +The selection of the domain which will serve the asset is deterministic, meaning +that each asset will be always served by the same domain. This behavior simplifies +the management of HTTP cache. + +Request Context Aware Assets +............................ + +Similarly to application-relative assets, absolute assets can also take into +account the context of the current request. In this case, only the request +scheme is considered, in order to select the appropriate base URL (HTTPs or +protocol-relative URLs for HTTPs requests, any base URL for HTTP requests):: + + use Symfony\Component\Asset\UrlPackage; + use Symfony\Component\Asset\Context\RequestStackContext; + + $package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1')); + $package->setContext(new RequestStackContext($requestStack)); + + echo $package->getUrl('/logo.png'); + // result: https://example.com/logo.png?v1 + +Named Packages +~~~~~~~~~~~~~~ + +Applications that manage lots of different assets may need to group them in +packages with the same versioning strategy and base path. The Asset component +includes a ``Packages`` class to simplify the management of several packages. + +In the following example, all packages use the same versioning strategy, but +they all have different base paths:: + + use Symfony\Component\Asset\Package; + use Symfony\Component\Asset\PathPackage; + use Symfony\Component\Asset\UrlPackage; + use Symfony\Component\Asset\Packages; + + $versionStrategy = new StaticVersionStrategy('v1'); + + $defaultPackage = new Package($versionStrategy); + + $namedPackages = array( + 'img' => new UrlPackage('http://img.example.com/', $versionStrategy), + 'doc' => new PathPackage('/somewhere/deep/for/documents', $versionStrategy), + ); + + $packages = new Packages($defaultPackage, $namedPackages) + +The ``Packages`` class requires to define a default package which will be applied +to all assets except those which indicate the name of the package to use. In +addition, this application defines a package named ``img`` to serve images from +an external domain and a ``doc`` package to avoid repeating long paths when +linking to a document inside a template:: + + echo $packages->getUrl('/main.css'); + // result: /main.css?v1 + + echo $packages->getUrl('/logo.png', 'img'); + // result: http://img.example.com/logo.png?v1 + + echo $packages->getUrl('/resume.pdf', 'doc'); + // result: /somewhere/deep/for/documents/resume.pdf?v1 diff --git a/components/index.rst b/components/index.rst index d16b78de06f..9e0acc26da3 100644 --- a/components/index.rst +++ b/components/index.rst @@ -5,6 +5,7 @@ The Components :hidden: using_components + asset class_loader/index config/index console/index diff --git a/components/map.rst.inc b/components/map.rst.inc index 7b6ceae5db2..d8921083591 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -1,5 +1,9 @@ * :doc:`/components/using_components` +* **Asset** + + * :doc:`/components/asset` + * :doc:`/components/class_loader/index` * :doc:`/components/class_loader/introduction` From d39b26eeb0c548f7f7b704b77fe1cf5ae354ce40 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 11 Feb 2015 17:26:00 +0100 Subject: [PATCH 071/103] Minor rewording --- components/asset.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/asset.rst b/components/asset.rst index ba37caa4c4a..09bfc4c6b6b 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -5,8 +5,8 @@ The Asset Component =================== - The Asset manages URL generation and versioning for web assets such as CSS - stylsheets, JavaScript files and image files. + The Asset component manages URL generation and versioning of web assets such + as CSS stylsheets, JavaScript files and image files. Installation ------------ @@ -62,7 +62,7 @@ the application's assets. Asset versions are commonly used to control how these assets are cached. Instead of relying on a simple version mechanism, the Asset component allows to -define advanced version strategies via PHP classes. The two built-in strategies +define advanced versioning strategies via PHP classes. The two built-in strategies provided by the component are ``EmptyVersionStrategy``, which doesn't add any version to the asset, and ``StaticVersionStrategy``, which allows to set the version with a format string. From 76b8beacc7914c7e7789363ce0319e7e6d3b0cb0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 12 Feb 2015 11:59:33 +0100 Subject: [PATCH 072/103] Added a missing link reference --- components/asset.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/components/asset.rst b/components/asset.rst index 09bfc4c6b6b..0f8fe4e5a35 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -247,3 +247,5 @@ linking to a document inside a template:: echo $packages->getUrl('/resume.pdf', 'doc'); // result: /somewhere/deep/for/documents/resume.pdf?v1 + +.. _Packagist: https://packagist.org/packages/symfony/asset From 49548b3d5abdd608d78dc65ccd488ded6bd459eb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 15 Feb 2015 13:25:56 +0100 Subject: [PATCH 073/103] Tweaked documentation and added links to API methods/classes --- components/asset.rst | 96 +++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 46 deletions(-) diff --git a/components/asset.rst b/components/asset.rst index 0f8fe4e5a35..2b5389d0fd6 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -24,9 +24,7 @@ Asset Packages The Asset component manages its assets through packages. A package groups all the assets which use the same versioning strategy. In the following basic -example, a package is created to manage assets without any versioning: - -.. code-block:: php +example, a package is created to manage assets without any versioning:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy; @@ -36,23 +34,14 @@ example, a package is created to manage assets without any versioning: echo $package->getUrl('/image.png'); // result: /image.png -Packages implement the ``PackageInterface``, which defines the following two -methods:: +Packages implement the :class:`Symfony\\Component\\Asset\\PackageInterface`, +which defines the following two methods:: - namespace Symfony\Component\Asset; +:method:`Symfony\\Component\\Asset\\PackageInterface::getVersion` + Returns the asset version for an asset. - interface PackageInterface - { - /** - * Returns the asset version for an asset. - */ - public function getVersion($path); - - /** - * Returns an absolute or root-relative public path. - */ - public function getUrl($path); - } +:method:`Symfony\\Component\\Asset\\PackageInterface::getUrl` + Returns an absolute or root-relative public path. Versioned Assets ~~~~~~~~~~~~~~~~ @@ -63,12 +52,12 @@ assets are cached. Instead of relying on a simple version mechanism, the Asset component allows to define advanced versioning strategies via PHP classes. The two built-in strategies -provided by the component are ``EmptyVersionStrategy``, which doesn't add any -version to the asset, and ``StaticVersionStrategy``, which allows to set the -version with a format string. +provided by the component are :class:`Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy`, +which doesn't add any version to the asset and :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy`, +which allows to set the version with a format string. -In this example, the ``StaticVersionStrategy`` is used to append the ``v1`` -suffix to any asset path:: +In this example, the :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` +is used to append the ``v1`` suffix to any asset path:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; @@ -79,7 +68,8 @@ suffix to any asset path:: // result: /image.png?v1 In case you want to modify the version format, pass a sprintf-compatible format -string as the second argument of the ``StaticVersionStrategy`` constructor:: +string as the second argument of the +:class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` constructor:: // put the 'version' word before the version value $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); @@ -96,9 +86,9 @@ string as the second argument of the ``StaticVersionStrategy`` constructor:: Custom Version Strategies ......................... -Use the ``VersionStrategyInterface`` to define your own version strategy. For -example, you could define a versioning where the current date is appended to -bust the cache every day:: +Use the :class:`Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface` +to define your own version strategy. For example, you could define a versioning +where the current date is appended to bust the cache every day:: use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface; @@ -126,10 +116,12 @@ Grouped Assets ~~~~~~~~~~~~~~ It's common for applications to store their assets in a common path. If that's -your case, replace the default ``Package`` class by ``PathPackage`` to avoid -repeating the same path time and again:: +your case, replace the default :class:`Symfony\Component\Asset\Package` class by +:class:`Symfony\Component\Asset\PathPackage` to avoid repeating the same path +time and again:: use Symfony\Component\Asset\PathPackage; + // ... $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); @@ -140,11 +132,12 @@ Request Context Aware Assets ............................ If you are also using the HttpFoundation component in your project, for example -in a Symfony application, the ``PathPackage`` class can take into account the -context of the current request:: +in a Symfony application, the :class:`Symfony\Component\Asset\PathPackage` class +can take into account the context of the current request:: use Symfony\Component\Asset\PathPackage; use Symfony\Component\Asset\Context\RequestStackContext; + // ... $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); $package->setContext(new RequestStackContext($requestStack)); @@ -153,29 +146,34 @@ context of the current request:: // result: /somewhere/static/images/logo.png?v1 When the request context is set, in addition to the configured base path, -``PathPackage`` also prepends the current request base URL (``/somewhere/`` in -this example) to assets. This allows your website to be hosted anywhere under -the web server root directory. +:class:`Symfony\Component\Asset\PathPackage` also prepends the current request +base URL (``/somewhere/`` in this example) to assets. This allows your website +to be hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ Applications that host their assets on different domains and CDNs (*Content -Delivery Networks*) should use instead the ``UrlPackage`` class to generate -absolute URLs for their assets:: +Delivery Networks*) should use the :class:`Symfony\Component\Asset\UrlPackage` +class to generate absolute URLs for their assets:: use Symfony\Component\Asset\UrlPackage; + // ... - $package = new UrlPackage('http://static.example.com/images/', new StaticVersionStrategy('v1')); + $package = new UrlPackage( + 'http://static.example.com/images/', + new StaticVersionStrategy('v1') + ); echo $package->getUrl('/logo.png'); // result: http://static.example.com/images/logo.png?v1 In case you serve assets from more than one domain to improve application -performance, pass an array of URLs as the first argument of ``UrlPackage`` -constructor:: +performance, pass an array of URLs as the first argument of +:class:`Symfony\Component\Asset\UrlPackage` constructor:: use Symfony\Component\Asset\UrlPackage; + // ... $urls = array( 'http://static1.example.com/images/', @@ -200,8 +198,12 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests):: use Symfony\Component\Asset\UrlPackage; use Symfony\Component\Asset\Context\RequestStackContext; + // ... - $package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1')); + $package = new UrlPackage( + array('http://example.com/', 'https://example.com/'), + new StaticVersionStrategy('v1') + ); $package->setContext(new RequestStackContext($requestStack)); echo $package->getUrl('/logo.png'); @@ -212,7 +214,8 @@ Named Packages Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component -includes a ``Packages`` class to simplify the management of several packages. +includes a :class:`Symfony\Component\Asset\Packages` class to simplify the +management of several packages. In the following example, all packages use the same versioning strategy, but they all have different base paths:: @@ -221,6 +224,7 @@ they all have different base paths:: use Symfony\Component\Asset\PathPackage; use Symfony\Component\Asset\UrlPackage; use Symfony\Component\Asset\Packages; + // ... $versionStrategy = new StaticVersionStrategy('v1'); @@ -233,11 +237,11 @@ they all have different base paths:: $packages = new Packages($defaultPackage, $namedPackages) -The ``Packages`` class requires to define a default package which will be applied -to all assets except those which indicate the name of the package to use. In -addition, this application defines a package named ``img`` to serve images from -an external domain and a ``doc`` package to avoid repeating long paths when -linking to a document inside a template:: +The :class:`Symfony\Component\Asset\Packages` class requires to define a default +package which will be applied to all assets except those which indicate the name +of the package to use. In addition, this application defines a package named +``img`` to serve images from an external domain and a ``doc`` package to avoid +repeating long paths when linking to a document inside a template:: echo $packages->getUrl('/main.css'); // result: /main.css?v1 From fab3c89b6fd64301c1d54399102765c9f2fb723c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 11:23:17 +0100 Subject: [PATCH 074/103] Fixed a lot of errors and added an introduction --- components/asset.rst | 68 +++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/components/asset.rst b/components/asset.rst index 2b5389d0fd6..7ef34d1d276 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -6,7 +6,37 @@ The Asset Component =================== The Asset component manages URL generation and versioning of web assets such - as CSS stylsheets, JavaScript files and image files. + as CSS stylesheets, JavaScript files and image files. + +In the past, it was common for web applications to hardcode the URLs of the web +assets. For example: + +.. code-block:: html + + + + + + + +This practice is no longer recommended unless the web application is extremely +simple. The main problems of hardcoding asset URLs are the following: + +* **Templates get verbose** because you have to write the full path for each + asset. When using the Asset component, you can group assets in packages to + avoid repeating the common part of their path. +* **Versioning is difficult** because it has to be custom managed for each + application. Adding a version to the asset URLs is essential for some applications + because it allows to control how the assets are cached. The Asset component + allows to define different versioning strategies for each package. +* **Moving assets location** is cumbersome and error-prone, because it requires + you to carefully update the URLs of all assets included in all templates. + The Asset component allows to move assets effortlessly just by changing the + base path value associated with the package of assets. +* **Impossible to use multiple CDNs** because it requires to change the URL of + the asset randomly for each request. The Asset component provides out-of-the-box + support for any number of multiple CDNs, both regular (``http://``) and + secure (``https://``). Installation ------------ @@ -22,9 +52,10 @@ Usage Asset Packages ~~~~~~~~~~~~~~ -The Asset component manages its assets through packages. A package groups all -the assets which use the same versioning strategy. In the following basic -example, a package is created to manage assets without any versioning:: +The Asset component manages assets through packages. A package groups all the +assets which share the same properties: versioning strategy, base path, CDN hosts, +etc. In the following basic example, a package is created to manage assets without +any versioning:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy; @@ -139,16 +170,19 @@ can take into account the context of the current request:: use Symfony\Component\Asset\Context\RequestStackContext; // ... - $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); - $package->setContext(new RequestStackContext($requestStack)); + $package = new PathPackage( + '/static/images', + new StaticVersionStrategy('v1'), + new RequestStackContext($requestStack) + ); echo $package->getUrl('/logo.png'); // result: /somewhere/static/images/logo.png?v1 -When the request context is set, in addition to the configured base path, -:class:`Symfony\Component\Asset\PathPackage` also prepends the current request -base URL (``/somewhere/`` in this example) to assets. This allows your website -to be hosted anywhere under the web server root directory. +When the request context is set (via the third optional argument), in addition +to the configured base path, :class:`Symfony\Component\Asset\PathPackage` also +prepends the current request base URL (``/somewhere/`` in this example) to assets. +This allows your website to be hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -202,9 +236,9 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests):: $package = new UrlPackage( array('http://example.com/', 'https://example.com/'), - new StaticVersionStrategy('v1') + new StaticVersionStrategy('v1'), + new RequestStackContext($requestStack) ); - $package->setContext(new RequestStackContext($requestStack)); echo $package->getUrl('/logo.png'); // result: https://example.com/logo.png?v1 @@ -237,11 +271,11 @@ they all have different base paths:: $packages = new Packages($defaultPackage, $namedPackages) -The :class:`Symfony\Component\Asset\Packages` class requires to define a default -package which will be applied to all assets except those which indicate the name -of the package to use. In addition, this application defines a package named -``img`` to serve images from an external domain and a ``doc`` package to avoid -repeating long paths when linking to a document inside a template:: +The :class:`Symfony\Component\Asset\Packages` class allows to define a default +package, which will be applied to assets that don't define the name of package +to use. In addition, this application defines a package named ``img`` to serve +images from an external domain and a ``doc`` package to avoid repeating long +paths when linking to a document inside a template:: echo $packages->getUrl('/main.css'); // result: /main.css?v1 From 17269a30feb9a20bdb0310973dad39b3f8ab8c5c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 11:28:32 +0100 Subject: [PATCH 075/103] Moved the component documentation to its own folder --- components/asset/index.rst | 7 +++++++ components/{asset.rst => asset/introduction.rst} | 0 components/map.rst.inc | 4 ++-- 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 components/asset/index.rst rename components/{asset.rst => asset/introduction.rst} (100%) diff --git a/components/asset/index.rst b/components/asset/index.rst new file mode 100644 index 00000000000..14d04b7eb6f --- /dev/null +++ b/components/asset/index.rst @@ -0,0 +1,7 @@ +Asset +===== + +.. toctree:: + :maxdepth: 2 + + introduction diff --git a/components/asset.rst b/components/asset/introduction.rst similarity index 100% rename from components/asset.rst rename to components/asset/introduction.rst diff --git a/components/map.rst.inc b/components/map.rst.inc index d8921083591..009284614ce 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -1,8 +1,8 @@ * :doc:`/components/using_components` -* **Asset** +* :doc:`/components/asset/index` - * :doc:`/components/asset` + * :doc:`/components/asset/introduction` * :doc:`/components/class_loader/index` From 5ca85d1584267115049e4bc6776a2fd844e2cfa8 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 19:20:20 +0100 Subject: [PATCH 076/103] Fixed some RST syntax issues --- components/asset/introduction.rst | 2 +- components/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/components/asset/introduction.rst b/components/asset/introduction.rst index 7ef34d1d276..645793527bb 100644 --- a/components/asset/introduction.rst +++ b/components/asset/introduction.rst @@ -66,7 +66,7 @@ any versioning:: // result: /image.png Packages implement the :class:`Symfony\\Component\\Asset\\PackageInterface`, -which defines the following two methods:: +which defines the following two methods: :method:`Symfony\\Component\\Asset\\PackageInterface::getVersion` Returns the asset version for an asset. diff --git a/components/index.rst b/components/index.rst index 9e0acc26da3..41f72d049a4 100644 --- a/components/index.rst +++ b/components/index.rst @@ -5,7 +5,7 @@ The Components :hidden: using_components - asset + asset/index class_loader/index config/index console/index From 9e8de96e3ea01d816a9b918fa2bc76731db0c7e5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 17:23:14 +0100 Subject: [PATCH 077/103] Fixed RST syntax issues --- components/asset/introduction.rst | 47 +++++++++++++++---------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/components/asset/introduction.rst b/components/asset/introduction.rst index 645793527bb..70b6d0e400c 100644 --- a/components/asset/introduction.rst +++ b/components/asset/introduction.rst @@ -83,12 +83,12 @@ assets are cached. Instead of relying on a simple version mechanism, the Asset component allows to define advanced versioning strategies via PHP classes. The two built-in strategies -provided by the component are :class:`Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy`, -which doesn't add any version to the asset and :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy`, +provided by the component are :class:`Symfony\\Component\\Asset\\VersionStrategy\\EmptyVersionStrategy`, +which doesn't add any version to the asset and :class:`Symfony\\Component\\Asset\\VersionStrategy\\StaticVersionStrategy`, which allows to set the version with a format string. -In this example, the :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` -is used to append the ``v1`` suffix to any asset path:: +In this example, the ``StaticVersionStrategy`` is used to append the ``v1`` +suffix to any asset path:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; @@ -99,8 +99,7 @@ is used to append the ``v1`` suffix to any asset path:: // result: /image.png?v1 In case you want to modify the version format, pass a sprintf-compatible format -string as the second argument of the -:class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` constructor:: +string as the second argument of the ``StaticVersionStrategy`` constructor:: // put the 'version' word before the version value $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); @@ -117,7 +116,7 @@ string as the second argument of the Custom Version Strategies ......................... -Use the :class:`Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface` +Use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface` to define your own version strategy. For example, you could define a versioning where the current date is appended to bust the cache every day:: @@ -147,9 +146,9 @@ Grouped Assets ~~~~~~~~~~~~~~ It's common for applications to store their assets in a common path. If that's -your case, replace the default :class:`Symfony\Component\Asset\Package` class by -:class:`Symfony\Component\Asset\PathPackage` to avoid repeating the same path -time and again:: +your case, replace the default :class:`Symfony\\Component\\Asset\\Package` class +by :class:`Symfony\\Component\\Asset\\PathPackage` to avoid repeating the same +path time and again:: use Symfony\Component\Asset\PathPackage; // ... @@ -163,8 +162,8 @@ Request Context Aware Assets ............................ If you are also using the HttpFoundation component in your project, for example -in a Symfony application, the :class:`Symfony\Component\Asset\PathPackage` class -can take into account the context of the current request:: +in a Symfony application, the ``PathPackage`` class can take into account the +context of the current request:: use Symfony\Component\Asset\PathPackage; use Symfony\Component\Asset\Context\RequestStackContext; @@ -180,15 +179,15 @@ can take into account the context of the current request:: // result: /somewhere/static/images/logo.png?v1 When the request context is set (via the third optional argument), in addition -to the configured base path, :class:`Symfony\Component\Asset\PathPackage` also -prepends the current request base URL (``/somewhere/`` in this example) to assets. -This allows your website to be hosted anywhere under the web server root directory. +to the configured base path, ``PathPackage`` also prepends the current request +base URL (``/somewhere/`` in this example) to assets. This allows your website +to be hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ Applications that host their assets on different domains and CDNs (*Content -Delivery Networks*) should use the :class:`Symfony\Component\Asset\UrlPackage` +Delivery Networks*) should use the :class:`Symfony\\Component\\Asset\\UrlPackage` class to generate absolute URLs for their assets:: use Symfony\Component\Asset\UrlPackage; @@ -203,8 +202,8 @@ class to generate absolute URLs for their assets:: // result: http://static.example.com/images/logo.png?v1 In case you serve assets from more than one domain to improve application -performance, pass an array of URLs as the first argument of -:class:`Symfony\Component\Asset\UrlPackage` constructor:: +performance, pass an array of URLs as the first argument of ``UrlPackage`` +constructor:: use Symfony\Component\Asset\UrlPackage; // ... @@ -248,7 +247,7 @@ Named Packages Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component -includes a :class:`Symfony\Component\Asset\Packages` class to simplify the +includes a :class:`Symfony\\Component\\Asset\\Packages` class to simplify the management of several packages. In the following example, all packages use the same versioning strategy, but @@ -271,11 +270,11 @@ they all have different base paths:: $packages = new Packages($defaultPackage, $namedPackages) -The :class:`Symfony\Component\Asset\Packages` class allows to define a default -package, which will be applied to assets that don't define the name of package -to use. In addition, this application defines a package named ``img`` to serve -images from an external domain and a ``doc`` package to avoid repeating long -paths when linking to a document inside a template:: +The ``Packages`` class allows to define a default package, which will be applied +to assets that don't define the name of package to use. In addition, this +application defines a package named ``img`` to serve images from an external +domain and a ``doc`` package to avoid repeating long paths when linking to a +document inside a template:: echo $packages->getUrl('/main.css'); // result: /main.css?v1 From 7ab379a7242d0d66b2b9b1d7eb672bbed26bd4c9 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 08:53:45 +0100 Subject: [PATCH 078/103] Lots of fixes and rewordings --- components/asset/introduction.rst | 45 ++++++++++++++++--------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/components/asset/introduction.rst b/components/asset/introduction.rst index 70b6d0e400c..eb2d1d22ba2 100644 --- a/components/asset/introduction.rst +++ b/components/asset/introduction.rst @@ -8,8 +8,8 @@ The Asset Component The Asset component manages URL generation and versioning of web assets such as CSS stylesheets, JavaScript files and image files. -In the past, it was common for web applications to hardcode the URLs of the web -assets. For example: +In the past, it was common for web applications to hardcode URLs of web assets. +For example: .. code-block:: html @@ -20,23 +20,23 @@ assets. For example: This practice is no longer recommended unless the web application is extremely -simple. The main problems of hardcoding asset URLs are the following: +simple. Hardcoding URLs can be a disadvantage because: -* **Templates get verbose** because you have to write the full path for each +* **Templates get verbose**: you have to write the full path for each asset. When using the Asset component, you can group assets in packages to - avoid repeating the common part of their path. -* **Versioning is difficult** because it has to be custom managed for each + avoid repeating the common part of their path; +* **Versioning is difficult**: it has to be custom managed for each application. Adding a version to the asset URLs is essential for some applications because it allows to control how the assets are cached. The Asset component - allows to define different versioning strategies for each package. -* **Moving assets location** is cumbersome and error-prone, because it requires - you to carefully update the URLs of all assets included in all templates. - The Asset component allows to move assets effortlessly just by changing the - base path value associated with the package of assets. -* **Impossible to use multiple CDNs** because it requires to change the URL of - the asset randomly for each request. The Asset component provides out-of-the-box - support for any number of multiple CDNs, both regular (``http://``) and - secure (``https://``). + allows to define different versioning strategies for each package; +* **Moving assets location** is cumbersome and error-prone: it requires you to + carefully update the URLs of all assets included in all templates. The Asset + component allows to move assets effortlessly just by changing the base path + value associated with the package of assets; +* **It's nearly impossible to use multiple CDNs**: this technique requires to + change the URL of the asset randomly for each request. The Asset component + provides out-of-the-box support for any number of multiple CDNs, both regular + (``http://``) and secure (``https://``). Installation ------------ @@ -117,8 +117,9 @@ Custom Version Strategies ......................... Use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface` -to define your own version strategy. For example, you could define a versioning -where the current date is appended to bust the cache every day:: +to define your own versioning strategy. For example, your application may need +to append the current date to all its web assets in order to bust the cache +every day:: use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface; @@ -178,10 +179,10 @@ context of the current request:: echo $package->getUrl('/logo.png'); // result: /somewhere/static/images/logo.png?v1 -When the request context is set (via the third optional argument), in addition -to the configured base path, ``PathPackage`` also prepends the current request -base URL (``/somewhere/`` in this example) to assets. This allows your website -to be hosted anywhere under the web server root directory. +When the request context is set (via an optional third argument), in addition to +the configured base path, ``PathPackage`` also prepends the current request base +URL (``/somewhere/`` in this example) to assets. This allows your website to be +hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -247,7 +248,7 @@ Named Packages Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component -includes a :class:`Symfony\\Component\\Asset\\Packages` class to simplify the +includes a :class:`Symfony\\Component\\Asset\\Packages` class to simplify management of several packages. In the following example, all packages use the same versioning strategy, but From e7195103bce85e79c4fbd1ce1110a9c9ddd53a88 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Feb 2015 15:54:02 +0100 Subject: [PATCH 079/103] Added a note about how to enable http_method_override for caching kernels --- book/http_cache.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/book/http_cache.rst b/book/http_cache.rst index 5cae7a710e2..a039c066d2a 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -163,6 +163,24 @@ kernel:: The caching kernel will immediately act as a reverse proxy - caching responses from your application and returning them to the client. +.. caution:: + + By default, a kernel based on the cache ignores the ``framework.http_method_override`` + option, which could lead to errors when using ``PUT``, ``DELETE`` and ``PURGE`` + methods in HTTP requests. + + Invoke the ``enableHttpMethodParameterOverride()`` method before creating the + ``Request`` object in order to take this option into account:: + + // web/app.php + + // ... + $kernel = new AppCache($kernel); + + Request::enableHttpMethodParameterOverride(); // <-- add this line + $request = Request::createFromGlobals(); + // ... + .. tip:: The cache kernel has a special ``getLog()`` method that returns a string From 07cb14b228fd309ec4d12cca772d3dff760eceba Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 12:54:17 -0400 Subject: [PATCH 080/103] [#5008] Shortening section and moving much of the note to reference --- book/http_cache.rst | 18 +++--------------- reference/configuration/framework.rst | 18 ++++++++++++++++++ 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 8a65d2bb6ef..46ac1dd1208 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -168,21 +168,9 @@ from your application and returning them to the client. .. caution:: - By default, a kernel based on the cache ignores the ``framework.http_method_override`` - option, which could lead to errors when using ``PUT``, ``DELETE`` and ``PURGE`` - methods in HTTP requests. - - Invoke the ``enableHttpMethodParameterOverride()`` method before creating the - ``Request`` object in order to take this option into account:: - - // web/app.php - - // ... - $kernel = new AppCache($kernel); - - Request::enableHttpMethodParameterOverride(); // <-- add this line - $request = Request::createFromGlobals(); - // ... + If you're using the :ref:`framework.http_method_override ` + option to read the HTTP method from a ``_method`` parameter, see the + above link for a tweak you need to make. .. tip:: diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 1725789e7fd..4cdf689758e 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -82,6 +82,24 @@ method gets called automatically. It becomes the service container parameter named ``kernel.http_method_override``. For more information, see :doc:`/cookbook/routing/method_parameters`. +.. caution:: + + If you're using the :ref:`AppCache Reverse Proxy ` + with this option, the kernel will ignore the ``_method`` parameter, + which could lead to errors. + + To fix this, invoke the ``enableHttpMethodParameterOverride()`` method + before creating the ``Request`` object:: + + // web/app.php + + // ... + $kernel = new AppCache($kernel); + + Request::enableHttpMethodParameterOverride(); // <-- add this line + $request = Request::createFromGlobals(); + // ... + ide ~~~ From 45aff1dbb054187c34aec7d5a17f20d5b8ee40a5 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 12:59:19 -0400 Subject: [PATCH 081/103] [#5081] Very minor language tweak --- cookbook/session/locale_sticky_session.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/session/locale_sticky_session.rst b/cookbook/session/locale_sticky_session.rst index 09d58a606e7..239086b8e4e 100644 --- a/cookbook/session/locale_sticky_session.rst +++ b/cookbook/session/locale_sticky_session.rst @@ -116,7 +116,7 @@ before the ``FirewallListener``, which is responsible for handling authenticatio setting the user token on the ``TokenStorage``, you have no access to the user which is logged in. -Assumed you have defined a ``locale`` property on your ``User`` entity and +Suppose you have defined a ``locale`` property on your ``User`` entity and you want to use this as the locale for the given user. To accomplish this, you can hook into the login process and update the user's session with this locale value before they are redirected to their first page. From 04a12a5c9b167a2008fba455c7b9de21676f916a Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 13:07:40 -0400 Subject: [PATCH 082/103] [#5010] Removing note that doesn't affect 2.6 versions --- components/intl.rst | 79 --------------------------------------------- 1 file changed, 79 deletions(-) diff --git a/components/intl.rst b/components/intl.rst index 9ccdac77d47..c638f8bd2f6 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -60,85 +60,6 @@ code:: $loader->registerPrefixFallback('/path/to/Icu/Resources/stubs'); } -.. sidebar:: ICU and Deployment Problems - - .. note:: - - These deployment problems only affect the following Symfony versions: - 2.3.0 to 2.3.20 versions, any 2.4.x version and 2.5.0 to 2.5.5 versions. - - The intl extension internally uses the `ICU library`_ to obtain localization - data such as number formats in different languages, country names and more. - To make this data accessible to userland PHP libraries, Symfony ships a copy - in the `Icu component`_. - - Depending on the ICU version compiled with your intl extension, a matching - version of that component needs to be installed. It sounds complicated, - but usually Composer does this for you automatically: - - * 1.0.*: when the intl extension is not available - * 1.1.*: when intl is compiled with ICU 3.8 or higher - * 1.2.*: when intl is compiled with ICU 4.4 or higher - - These versions are important when you deploy your application to a **server with - a lower ICU version** than your development machines, because deployment will - fail if: - - * the development machines are compiled with ICU 4.4 or higher, but the - server is compiled with a lower ICU version than 4.4; - * the intl extension is available on the development machines but not on - the server. - - For example, consider that your development machines ship ICU 4.8 and the server - ICU 4.2. When you run ``composer update`` on the development machine, version - 1.2.* of the Icu component will be installed. But after deploying the - application, ``composer install`` will fail with the following error: - - .. code-block:: bash - - $ composer install - Loading composer repositories with package information - Installing dependencies from lock file - Your requirements could not be resolved to an installable set of packages. - - Problem 1 - - symfony/icu 1.2.x requires lib-icu >=4.4 -> the requested linked - library icu has the wrong version installed or is missing from your - system, make sure to have the extension providing it. - - The error tells you that the requested version of the Icu component, version - 1.2, is not compatible with PHP's ICU version 4.2. - - One solution to this problem is to run ``composer update`` instead of - ``composer install``. It is highly recommended **not** to do this. The - ``update`` command will install the latest versions of each Composer dependency - to your production server and potentially break the application. - - A better solution is to fix your composer.json to the version required by the - production server. First, determine the ICU version on the server: - - .. code-block:: bash - - $ php -i | grep ICU - ICU version => 4.2.1 - - Then fix the Icu component in your ``composer.json`` file to a matching version: - - .. code-block:: json - - "require: { - "symfony/icu": "1.1.*" - } - - Set the version to - - * "1.0.*" if the server does not have the intl extension installed; - * "1.1.*" if the server is compiled with ICU 4.2 or lower. - - Finally, run ``composer update symfony/icu`` on your development machine, test - extensively and deploy again. The installation of the dependencies will now - succeed. - Writing and Reading Resource Bundles ------------------------------------ From c4027c54a439c17375c0fba795196b42519fa390 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 13:32:39 -0400 Subject: [PATCH 083/103] [#5011] Fixing minor build issue --- book/doctrine.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/doctrine.rst b/book/doctrine.rst index e60ab0118fe..78aa46f0c7f 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -778,6 +778,8 @@ entities (the topic of :ref:`relations ` will be covered later), group, etc. For more information, see the official `Doctrine Query Language`_ documentation. +.. _book-doctrine-custom-repository-classes: + Custom Repository Classes ~~~~~~~~~~~~~~~~~~~~~~~~~ From 8119e85c00c07033a0013bce2cb8a93d0ae71250 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 13:35:45 -0400 Subject: [PATCH 084/103] [#5011] Adding one more fix I missed --- cookbook/security/entity_provider.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst index 125f8d6a184..e9b3f0142e8 100644 --- a/cookbook/security/entity_provider.rst +++ b/cookbook/security/entity_provider.rst @@ -586,7 +586,7 @@ The code below shows the implementation of the .. tip:: Don't forget to add the repository class to the - :ref: `mapping definition of your entity `. + :ref:`mapping definition of your entity `. To finish the implementation, the configuration of the security layer must be changed to tell Symfony to use the new custom entity provider instead of the From edd8618541cb7e8ffcdce505c0f9eb556dcb6dec Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 13:38:01 -0400 Subject: [PATCH 085/103] [#5015] Very small tweak --- cookbook/security/impersonating_user.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index b790f58384f..48a1adf498b 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -88,8 +88,7 @@ to show a link to exit impersonation: In some cases you may need to get the object that represents the impersonating user rather than the impersonated user. Use the following snippet to iterate -over user's roles until you get the ``SwitchUserRole`` related to the -impersonating user:: +over the user's roles until you find one that a ``SwitchUserRole`` object:: use Symfony\Component\Security\Core\Role\SwitchUserRole; From 50c8227dfdec75ef6047e93acdcb31b9eddb3afb Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 13:39:24 -0400 Subject: [PATCH 086/103] [#5015] Updating the security service name for 2.6 - thanks to Cordoval --- cookbook/security/impersonating_user.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index 48a1adf498b..f9003fd9b93 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -92,10 +92,10 @@ over the user's roles until you find one that a ``SwitchUserRole`` object:: use Symfony\Component\Security\Core\Role\SwitchUserRole; - $securityContext = $this->get('security.context'); + $authChecker = $this->get('security.authorization_checker'); - if ($securityContext->isGranted('ROLE_PREVIOUS_ADMIN')) { - foreach ($securityContext->getToken()->getRoles() as $role) { + if ($authChecker->isGranted('ROLE_PREVIOUS_ADMIN')) { + foreach ($authChecker->getToken()->getRoles() as $role) { if ($role instanceof SwitchUserRole) { $impersonatingUser = $role->getSource()->getUser(); break; From 32b6228d94ab148ee855b7a39e4de0ad9e5c8969 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 13:43:04 -0400 Subject: [PATCH 087/103] [#5017] Minor language tweaks --- reference/configuration/doctrine.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index 0ca3c03cf64..f5cc9e3dd09 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -449,11 +449,11 @@ The following block shows all possible configuration keys: .. note:: The ``server_version`` option was added in Doctrine DBAL 2.5, which is used - by DoctrineBundle 1.3 version. The value of this option should match your - database server version (use ``postgres -V`` or ``psql -V`` command to find + by DoctrineBundle 1.3. The value of this option should match your database + server version (use ``postgres -V`` or ``psql -V`` command to find your PostgreSQL version and ``mysql -V`` to get your MySQL version). - If you don't define this option and you don't have created your database yet, + If you don't define this option and you haven't created your database yet, you may get ``PDOException`` errors because Doctrine will try to guess the database server version automatically and none is available. From 42c9f530985e3a9913b67c5ff35cd9d2e3683e06 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:01:32 -0400 Subject: [PATCH 088/103] [#5033] Tweaking variable name to "match" the service id When I merge to 2.6, I'll properly change the service ids and variable names --- cookbook/controller/service.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/controller/service.rst b/cookbook/controller/service.rst index 97320377c11..50f781754b6 100644 --- a/cookbook/controller/service.rst +++ b/cookbook/controller/service.rst @@ -281,7 +281,7 @@ controller: :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isGranted` (service: ``security.context``) .. code-block:: php - $authorizationChecker->isGranted($attributes, $object); + $securityContext->isGranted($attributes, $object); :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect` .. code-block:: php From 2035d62e94005aabb71a86ccf786da91eac5fae2 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:05:36 -0400 Subject: [PATCH 089/103] Updating for new security service names in 2.6 --- cookbook/controller/service.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/controller/service.rst b/cookbook/controller/service.rst index df14ed46a00..1dcc60db143 100644 --- a/cookbook/controller/service.rst +++ b/cookbook/controller/service.rst @@ -273,19 +273,19 @@ controller: *Simply inject doctrine instead of fetching it from the container* -:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getUser` (service: ``security.context``) +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getUser` (service: ``security.token_storage``) .. code-block:: php $user = null; - $token = $securityContext->getToken(); + $token = $tokenStorage->getToken(); if (null !== $token && is_object($token->getUser())) { $user = $token->getUser(); } -:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isGranted` (service: ``security.context``) +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isGranted` (service: ``security.authorization_checker``) .. code-block:: php - $securityContext->isGranted($attributes, $object); + $authChecker->isGranted($attributes, $object); :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect` .. code-block:: php From 8e41e734ad4f3a7c8ec7706a2f3ea04b635d4d3c Mon Sep 17 00:00:00 2001 From: Antoine Makdessi Date: Fri, 20 Feb 2015 15:43:44 +0100 Subject: [PATCH 090/103] Minor improvement for symfony-installer with LTS based on the symfony-installer PR https://github.com/symfony/symfony-installer/pull/105 --- book/installation.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/book/installation.rst b/book/installation.rst index e117756eaf6..8dbfa169af9 100644 --- a/book/installation.rst +++ b/book/installation.rst @@ -98,6 +98,17 @@ number as the second argument of the ``new`` command: # Windows c:\projects\> php symfony.phar new my_project_name 2.3.23 +If you want your project to be based on the last Symfony LTS version, pass +``lts`` as the second argument of the ``new`` command: + +.. code-block:: bash + + # Linux, Mac OS X + $ symfony new my_project_name lts + + # Windows + c:\projects\> php symfony.phar new my_project_name lts + Read the :doc:`Symfony Release process ` to better understand why there are several Symfony versions and which one to use for your projects. From 18c08f340bbe650efc08f8c7e533fc466d1e1e9a Mon Sep 17 00:00:00 2001 From: Antoine Makdessi Date: Mon, 2 Mar 2015 13:21:21 +0100 Subject: [PATCH 091/103] Better wording --- book/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation.rst b/book/installation.rst index 8dbfa169af9..64894725fda 100644 --- a/book/installation.rst +++ b/book/installation.rst @@ -98,7 +98,7 @@ number as the second argument of the ``new`` command: # Windows c:\projects\> php symfony.phar new my_project_name 2.3.23 -If you want your project to be based on the last Symfony LTS version, pass +If you want your project to be based on the latest Symfony LTS version, pass ``lts`` as the second argument of the ``new`` command: .. code-block:: bash From 912682a324d5c0b6806e223e3674357477a8704e Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:10:51 -0400 Subject: [PATCH 092/103] Adding a link to define "lts" --- book/installation.rst | 4 ++-- contributing/community/releases.rst | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/book/installation.rst b/book/installation.rst index 64894725fda..5039178fe95 100644 --- a/book/installation.rst +++ b/book/installation.rst @@ -98,8 +98,8 @@ number as the second argument of the ``new`` command: # Windows c:\projects\> php symfony.phar new my_project_name 2.3.23 -If you want your project to be based on the latest Symfony LTS version, pass -``lts`` as the second argument of the ``new`` command: +If you want your project to be based on the latest :ref:`Symfony LTS version `, +pass ``lts`` as the second argument of the ``new`` command: .. code-block:: bash diff --git a/contributing/community/releases.rst b/contributing/community/releases.rst index 0f2dc92121f..988e39dc38f 100644 --- a/contributing/community/releases.rst +++ b/contributing/community/releases.rst @@ -60,6 +60,8 @@ Standard Versions A standard minor version is maintained for an *eight month* period for bug fixes, and for a *fourteen month* period for security issue fixes. +.. _releases-lts: + Long Term Support Versions ~~~~~~~~~~~~~~~~~~~~~~~~~~ From 5ef1e08433d4c1427d4cfd6b73a19b8640bd2490 Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Fri, 20 Feb 2015 23:26:21 -0500 Subject: [PATCH 093/103] reword to serves --- cookbook/configuration/web_server_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst index 59528aa83c6..f5e84c7c66d 100644 --- a/cookbook/configuration/web_server_configuration.rst +++ b/cookbook/configuration/web_server_configuration.rst @@ -21,7 +21,7 @@ to use PHP :ref:`with Nginx `. static files, including images, stylesheets and JavaScript files. It is also where the front controllers live. For more details, see the :ref:`the-web-directory`. - The web directory services as the document root when configuring your + The web directory serves as the document root when configuring your web server. In the examples below, the ``web/`` directory will be the document root. This directory is ``/var/www/project/web/``. From e2453038e4ea95af93ede147de0cbcc37e11359c Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:19:07 -0400 Subject: [PATCH 094/103] [#5036] Typo fix (probably mine originally) caught by xabbuh --- cookbook/security/form_login_setup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/security/form_login_setup.rst b/cookbook/security/form_login_setup.rst index cfed1d88679..9dce6cc2cc2 100644 --- a/cookbook/security/form_login_setup.rst +++ b/cookbook/security/form_login_setup.rst @@ -87,7 +87,7 @@ bundle:: { } -Next, create two routes: one for each of the paths your configured earlier +Next, create two routes: one for each of the paths you configured earlier under your ``form_login`` configuration (``/login`` and ``/login_check``): .. configuration-block:: From 55ee2550df05da055d2f6987b9e43900d77b492f Mon Sep 17 00:00:00 2001 From: Amine Matmati Date: Mon, 23 Feb 2015 15:28:39 -0600 Subject: [PATCH 095/103] Fixed variable name in : Reference -> validation constraints -> count -> basic usage -> PHP --- reference/constraints/Count.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/Count.rst b/reference/constraints/Count.rst index 0e1f0fbe51c..8a5d007ec99 100644 --- a/reference/constraints/Count.rst +++ b/reference/constraints/Count.rst @@ -88,7 +88,7 @@ you might add the following: class Participant { - public static function loadValidatorMetadata(ClassMetadata $data) + public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('emails', new Assert\Count(array( 'min' => 1, From ebf77d762e902ec26ed086b7453b35a21cb0ffe9 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Tue, 24 Feb 2015 08:09:07 +0100 Subject: [PATCH 096/103] added some more components for Tobion as a merger --- contributing/code/core_team.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/code/core_team.rst b/contributing/code/core_team.rst index 55f0332bde7..a684a8bfd00 100644 --- a/contributing/code/core_team.rst +++ b/contributing/code/core_team.rst @@ -45,8 +45,8 @@ Active Core Members Validator_, Icu_, Intl_, Locale_, OptionsResolver_ and PropertyAccess_ components; - * **Tobias Schultze** (:merger:`Tobion`) can merge into the Routing_ - component; + * **Tobias Schultze** (:merger:`Tobion`) can merge into the Routing_, + OptionsResolver_ and PropertyAccess_ components; * **Romain Neutron** (:merger:`romainneutron`) can merge into the Process_ component; From 118513b1e42391afdc2f916e69260fc00fb01066 Mon Sep 17 00:00:00 2001 From: Stepan Anchugov Date: Tue, 24 Feb 2015 17:56:08 +0500 Subject: [PATCH 097/103] Switched the first example to a static constructor method I believe having a non-static method for class instantiation is not something the documentation should encourage. It's much better to use a named constructor here (also note that `TestObject` class code isn't supplied). --- cookbook/form/unit_testing.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cookbook/form/unit_testing.rst b/cookbook/form/unit_testing.rst index 29f54372cf3..c39d3514b7e 100644 --- a/cookbook/form/unit_testing.rst +++ b/cookbook/form/unit_testing.rst @@ -55,8 +55,7 @@ The simplest ``TypeTestCase`` implementation looks like the following:: $type = new TestedType(); $form = $this->factory->create($type); - $object = new TestObject(); - $object->fromArray($formData); + $object = TestObject::fromArray($formData); // submit the data to the form directly $form->submit($formData); From cf31894e885416a15d3f93d97527a3e80e1b7d63 Mon Sep 17 00:00:00 2001 From: JhonnyL Date: Thu, 26 Feb 2015 14:21:22 +0100 Subject: [PATCH 098/103] Fix service id --- cookbook/controller/service.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/controller/service.rst b/cookbook/controller/service.rst index 1dcc60db143..403ca08aed2 100644 --- a/cookbook/controller/service.rst +++ b/cookbook/controller/service.rst @@ -124,7 +124,7 @@ the route ``_controller`` value: .. versionadded:: 2.6 If your controller service implements the ``__invoke`` method, you can simply refer to the service id - (``acme.hello.controller``). + (``app.hello_controller``). Alternatives to base Controller Methods --------------------------------------- From 757549501d1a9d1c0409192dc4310e2ef29fc2c3 Mon Sep 17 00:00:00 2001 From: hacfi Date: Mon, 2 Mar 2015 04:45:26 +0100 Subject: [PATCH 099/103] Correct RegisterListenersPass namespace See https://github.com/symfony/symfony/pull/9792 --- components/event_dispatcher/introduction.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst index 573061b0556..15f0f67dd44 100644 --- a/components/event_dispatcher/introduction.rst +++ b/components/event_dispatcher/introduction.rst @@ -212,14 +212,14 @@ instance of ``Symfony\Component\HttpKernel\Event\FilterResponseEvent``:: and the :doc:`DependencyInjection component `, you can use the - :class:`Symfony\\Component\\HttpKernel\\DependencyInjection\\RegisterListenersPass` - from the HttpKernel component to tag services as event listeners:: + :class:`Symfony\\Component\\EventDispatcher\\DependencyInjection\\RegisterListenersPass` + from the EventDispatcher component to tag services as event listeners:: use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Definition; use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag; use Symfony\Component\DependencyInjection\Reference; - use Symfony\Component\HttpKernel\DependencyInjection\RegisterListenersPass; + use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass; $containerBuilder = new ContainerBuilder(new ParameterBag()); $containerBuilder->addCompilerPass(new RegisterListenersPass()); From 383de544f09ed231ef08cc14cc4109b23eadf7ae Mon Sep 17 00:00:00 2001 From: hacfi Date: Mon, 2 Mar 2015 08:49:06 +0100 Subject: [PATCH 100/103] Remove unnecessary component reference --- components/event_dispatcher/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst index 15f0f67dd44..e3f8da1916f 100644 --- a/components/event_dispatcher/introduction.rst +++ b/components/event_dispatcher/introduction.rst @@ -213,7 +213,7 @@ instance of ``Symfony\Component\HttpKernel\Event\FilterResponseEvent``:: :doc:`DependencyInjection component `, you can use the :class:`Symfony\\Component\\EventDispatcher\\DependencyInjection\\RegisterListenersPass` - from the EventDispatcher component to tag services as event listeners:: + to tag services as event listeners:: use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Definition; From 236797ee23ce8ce9d93fa96479bce556625b0bff Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:41:34 -0400 Subject: [PATCH 101/103] Fixing bad merge conflict (forgot to save!) --- book/propel.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/book/propel.rst b/book/propel.rst index 0b41ed63940..7cf5755c09b 100644 --- a/book/propel.rst +++ b/book/propel.rst @@ -241,15 +241,11 @@ have a route that maps a product id to an update action in a controller:: ); } -<<<<<<< HEAD $product->setName('New product name!'); $product->save(); - return $this->redirect($this->generateUrl('homepage')); + return $this->redirectToRoute('homepage'); } -======= - return $this->redirectToRoute('homepage'); ->>>>>>> pull/5046 } Updating an object involves just three steps: From c87ae8a36259bc1caad4c7da9891c4a3abe3ff66 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:42:54 -0400 Subject: [PATCH 102/103] [#5064] Minor language tweaks --- contributing/documentation/standards.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index aa135d2922a..3210ee65927 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -52,9 +52,9 @@ Code Examples * The code follows the :doc:`Symfony Coding Standards ` as well as the `Twig Coding Standards`_; * The code examples should look real for a web application context. Avoid abstract - or puerile examples (``foo``, ``bar``, ``demo``, etc.); + or trivial examples (``foo``, ``bar``, ``demo``, etc.); * The code should follow the :doc:`Symfony Best Practices `. - Unless the example requires to use a custom bundle, make sure to always use the + Unless the example requires a custom bundle, make sure to always use the ``AppBundle`` bundle to store your code; * Use ``Acme`` when the code requires a vendor name; * To avoid horizontal scrolling on code blocks, we prefer to break a line From 66831a698df427fafaa04fd9f8847a45ddce4b15 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Mar 2015 14:53:58 -0400 Subject: [PATCH 103/103] Backporting some stuff from 2.7, that I think must have gotten merged only there by accident --- book/security.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/book/security.rst b/book/security.rst index f96a277c256..59460ec4067 100644 --- a/book/security.rst +++ b/book/security.rst @@ -817,7 +817,7 @@ You can easily deny access from inside a controller:: $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!'); // Old way : - // if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) { + // if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) { // throw $this->createAccessDeniedException('Unable to access this page!'); // } @@ -829,6 +829,10 @@ You can easily deny access from inside a controller:: still now), you could check access directly and throw the ``AccessDeniedException`` as shown in the example above). +.. versionadded:: 2.6 + The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior + to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service. + In both cases, a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException` is thrown, which ultimately triggers a 403 HTTP response inside Symfony.