From d5be25ef3c89a0f55078f0cf03b5783ffaf2c3f5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 14 Dec 2014 16:23:25 +0100 Subject: [PATCH 01/36] Documented the characters that provoke a YAML escaping string --- components/yaml/yaml_format.rst | 51 +++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index a86bcd05030..9419526c0cc 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -23,6 +23,9 @@ The syntax for scalars is similar to the PHP syntax. Strings ~~~~~~~ +Strings in YAML can be wrapped both in single and double quotes. In some cases, +they can also be unquoted: + .. code-block:: yaml A string in YAML @@ -31,26 +34,50 @@ Strings 'A singled-quoted string in YAML' -.. tip:: +.. code-block:: yaml - In a single quoted string, a single quote ``'`` must be doubled: + "A double-quoted string in YAML" - .. code-block:: yaml +Quoted styles are useful when a string starts or ends with one or more +relevant spaces, because unquoted strings are trimmed on both ends when parsing +their contents. - 'A single quote '' in a single-quoted string' +When using single-quoted strings, any single quote ``'`` inside its contents +must be doubled to escape it: -.. code-block:: yaml + .. code-block:: yaml - "A double-quoted string in YAML\n" + 'A single quote '' inside a single-quoted string' -Quoted styles are useful when a string starts or ends with one or more -relevant spaces. +The double-quoted style provides a way to express arbitrary strings, by +using ``\`` escape sequences. It is very useful when you need to embed a +``\n`` or a Unicode character in a string. + +.. code-block:: yaml -.. tip:: + "A double-quoted string in YAML\n" - The double-quoted style provides a way to express arbitrary strings, by - using ``\`` escape sequences. It is very useful when you need to embed a - ``\n`` or a unicode character in a string. +If the string contains any of the following characters, it must be escaped with +single quotes: + +===== ===== ===== ===== ===== +``:`` ``{`` ``}`` ``[`` ``]`` +``,`` ``&`` ``*`` ``#`` ``?`` +``|`` ``-`` ``<`` ``>`` ``=`` +``!`` ``%`` ``@`` ``\``` +===== ===== ===== ===== ===== + +If the string contains any of the following control characters, it must be +escaped with double quotes. In addition, the escaping must use a double slash +``\\`` to avoid parsing issues: + +======== ======== ======== ======== ======== ======== ======== ======== +``\0`` ``\x01`` ``\x02`` ``\x03`` ``\x04`` ``\x05`` ``\x06`` ``\a`` +``\b`` ``\t`` ``\n`` ``\v`` ``\f`` ``\r`` ``\x0e`` ``\x0f`` +``\x10`` ``\x11`` ``\x12`` ``\x13`` ``\x14`` ``\x15`` ``\x16`` ``\x17`` +``\x18`` ``\x19`` ``\x1a`` ``\e`` ``\x1c`` ``\x1d`` ``\x1e`` ``\x1f`` +``\N`` ``\_`` ``\L`` ``\P`` +======== ======== ======== ======== ======== ======== ======== ======== When a string contains line breaks, you can use the literal style, indicated by the pipe (``|``), to indicate that the string will span several lines. In From caaa2728fd2b8eabd26940fba6550e4968e3dcad Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 14 Dec 2014 17:02:12 +0100 Subject: [PATCH 02/36] Addressed all the comments made by Wouter --- components/yaml/yaml_format.rst | 84 ++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 23 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 9419526c0cc..c45a45117a2 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -30,12 +30,8 @@ they can also be unquoted: A string in YAML -.. code-block:: yaml - 'A singled-quoted string in YAML' -.. code-block:: yaml - "A double-quoted string in YAML" Quoted styles are useful when a string starts or ends with one or more @@ -45,9 +41,32 @@ their contents. When using single-quoted strings, any single quote ``'`` inside its contents must be doubled to escape it: - .. code-block:: yaml +.. code-block:: yaml - 'A single quote '' inside a single-quoted string' + 'A single quote '' inside a single-quoted string' + +If the string contains any of the following characters, it must be escaped with +single quotes: + +* ``:`` +* ``{`` +* ``}`` +* ``[`` +* ``]`` +* ``,`` +* ``&`` +* ``*`` +* ``#`` +* ``?`` +* ``|`` +* ``-`` +* ``<`` +* ``>`` +* ``=`` +* ``!`` +* ``%`` +* ``@`` +* ``\``` The double-quoted style provides a way to express arbitrary strings, by using ``\`` escape sequences. It is very useful when you need to embed a @@ -57,27 +76,46 @@ using ``\`` escape sequences. It is very useful when you need to embed a "A double-quoted string in YAML\n" -If the string contains any of the following characters, it must be escaped with -single quotes: - -===== ===== ===== ===== ===== -``:`` ``{`` ``}`` ``[`` ``]`` -``,`` ``&`` ``*`` ``#`` ``?`` -``|`` ``-`` ``<`` ``>`` ``=`` -``!`` ``%`` ``@`` ``\``` -===== ===== ===== ===== ===== - If the string contains any of the following control characters, it must be escaped with double quotes. In addition, the escaping must use a double slash ``\\`` to avoid parsing issues: -======== ======== ======== ======== ======== ======== ======== ======== -``\0`` ``\x01`` ``\x02`` ``\x03`` ``\x04`` ``\x05`` ``\x06`` ``\a`` -``\b`` ``\t`` ``\n`` ``\v`` ``\f`` ``\r`` ``\x0e`` ``\x0f`` -``\x10`` ``\x11`` ``\x12`` ``\x13`` ``\x14`` ``\x15`` ``\x16`` ``\x17`` -``\x18`` ``\x19`` ``\x1a`` ``\e`` ``\x1c`` ``\x1d`` ``\x1e`` ``\x1f`` -``\N`` ``\_`` ``\L`` ``\P`` -======== ======== ======== ======== ======== ======== ======== ======== +* ``\0`` +* ``\x01`` +* ``\x02`` +* ``\x03`` +* ``\x04`` +* ``\x05`` +* ``\x06`` +* ``\a`` +* ``\b`` +* ``\t`` +* ``\n`` +* ``\v`` +* ``\f`` +* ``\r`` +* ``\x0e`` +* ``\x0f`` +* ``\x10`` +* ``\x11`` +* ``\x12`` +* ``\x13`` +* ``\x14`` +* ``\x15`` +* ``\x16`` +* ``\x17`` +* ``\x18`` +* ``\x19`` +* ``\x1a`` +* ``\e`` +* ``\x1c`` +* ``\x1d`` +* ``\x1e`` +* ``\x1f`` +* ``\N`` +* ``\_`` +* ``\L`` +* ``\P`` When a string contains line breaks, you can use the literal style, indicated by the pipe (``|``), to indicate that the string will span several lines. In From ce6e3eba726957c0c5ccec82b55936f523d5b3bb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Dec 2014 12:19:30 +0100 Subject: [PATCH 03/36] Reworded some explanations to make them more clear --- components/yaml/yaml_format.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index c45a45117a2..7be2f0d931b 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -45,8 +45,9 @@ must be doubled to escape it: 'A single quote '' inside a single-quoted string' -If the string contains any of the following characters, it must be escaped with -single quotes: +Strings containing any of the following characters must be quoted. Although you +can use double quotes, for these characters is more convenient to use single +quotes, which avoids having to escape any backslash ``\``: * ``:`` * ``{`` @@ -69,16 +70,15 @@ single quotes: * ``\``` The double-quoted style provides a way to express arbitrary strings, by -using ``\`` escape sequences. It is very useful when you need to embed a -``\n`` or a Unicode character in a string. +using ``\`` to escape characters and sequences. For instance, it is very useful +when you need to embed a ``\n`` or a Unicode character in a string. .. code-block:: yaml "A double-quoted string in YAML\n" If the string contains any of the following control characters, it must be -escaped with double quotes. In addition, the escaping must use a double slash -``\\`` to avoid parsing issues: +escaped with double quotes: * ``\0`` * ``\x01`` From 63ea6597255541a4dc2858fe3e3f3de5ddb5efd4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Dec 2014 15:37:17 +0100 Subject: [PATCH 04/36] Added a lot more cases for enclosing strings with quotes --- components/yaml/yaml_format.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 7be2f0d931b..1d45167fc52 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -117,6 +117,19 @@ escaped with double quotes: * ``\L`` * ``\P`` +Finally, there are other cases when the strings must be quoted, no matter if +using single or double quotes: + +* when the string is ``true`` or ``false`` (otherwise, it would be treated as a + boolean value); +* when the string is ``null`` or ``~`` (otherwise, it would be considered as a + ``null`` value); +* when the string looks like a number, such as integers (e.g. ``2``, ``14``, etc.), + floats (e.g. ``2.6``, ``14.9``) and exponential numbers (e.g. ``12e7``, etc.) + (otherwise, it would be treated as a numeric value); +* when the string looks like a date (e.g. ``2014-12-31``) (otherwise it would be + automatically converted into a Unix timestamp). + When a string contains line breaks, you can use the literal style, indicated by the pipe (``|``), to indicate that the string will span several lines. In literals, newlines are preserved: From 044e88bc1cf08a6c469259dc4808a14de368e25d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 16 Dec 2014 16:43:32 +0100 Subject: [PATCH 05/36] Fixed a minor typo --- components/yaml/yaml_format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 1d45167fc52..d9a290f9537 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -46,7 +46,7 @@ must be doubled to escape it: 'A single quote '' inside a single-quoted string' Strings containing any of the following characters must be quoted. Although you -can use double quotes, for these characters is more convenient to use single +can use double quotes, for these characters it is more convenient to use single quotes, which avoids having to escape any backslash ``\``: * ``:`` From d4d2236ab63037d03f83705f03b8af1b41a2466d Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Thu, 11 Dec 2014 15:17:40 +0100 Subject: [PATCH 06/36] clean up cache invalidation information on the cache chapter --- book/http_cache.rst | 64 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 13 deletions(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 46e80ed4e73..048d1b96e75 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -328,6 +328,13 @@ its creation more manageable:: // set a custom Cache-Control directive $response->headers->addCacheControlDirective('must-revalidate', true); +.. tip:: + + If you need to set cache headers for many different controller actions, + you might want to look into the FOSHttpCacheBundle_. It provides a way + to define cache headers based on the URL pattern and other request + properties. + Public vs private Responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1051,21 +1058,35 @@ Cache Invalidation "There are only two hard things in Computer Science: cache invalidation and naming things." -- Phil Karlton -You should never need to invalidate cached data because invalidation is already -taken into account natively in the HTTP cache models. If you use validation, -you never need to invalidate anything by definition; and if you use expiration -and need to invalidate a resource, it means that you set the expires date -too far away in the future. +Once an URL is cached by a caching reverse proxy, the proxy will not ask the +application for that content anymore. This allows the cache to do fast +responses and reduces the load on your application. However, you risk +delivering outdated content. A way out of this dilemma is to use long +cache lifetimes, but to actively notify the caching proxy when content +changes. Reverse proxies usually provide a channel to receive such +notifications, usually through special HTTP requests. -.. note:: +.. tip:: + + While cache invalidation sounds powerful, avoid it when possible. If you + fail to invalidate something, outdated caches will stay for a potentially + long time. Instead, use short cache lifetimes or use the validation model, + and adjust your controllers to perform efficient validation checks as + explained in :ref:`optimizing-cache-validation`. - Since invalidation is a topic specific to each type of reverse proxy, - if you don't worry about invalidation, you can switch between reverse - proxies without changing anything in your application code. + Furthermore, since invalidation is a topic specific to each type of reverse + proxy, using this concept will tie you to a specific reverse proxy or need + additional efforts to support different proxies. -Actually, all reverse proxies provide ways to purge cached data, but you -should avoid them as much as possible. The most standard way is to purge the -cache for a given URL by requesting it with the special ``PURGE`` HTTP method. +Sometimes, however, you need that extra performance you can get when +explicitly invalidating. For invalidation, your application needs to detect +when content changes and tell the cache to remove the URLs which contain +that data from its cache. + +If one content corresponds to one URL, the ``PURGE`` model works well. +You send a request to the cache proxy with the HTTP method ``PURGE`` instead +of ``GET`` and make the cache proxy detect this and remove the data from the +cache instead of going to Symfony to get a response. Here is how you can configure the Symfony reverse proxy to support the ``PURGE`` HTTP method:: @@ -1085,11 +1106,15 @@ Here is how you can configure the Symfony reverse proxy to support the return parent::invalidate($request, $catch); } + if ('127.0.0.1' !== $request->getClientIp()) { + return new Response('Invalid HTTP method', Response::HTTP_BAD_REQUEST); + } + $response = new Response(); if ($this->getStore()->purge($request->getUri())) { $response->setStatusCode(200, 'Purged'); } else { - $response->setStatusCode(404, 'Not purged'); + $response->setStatusCode(200, 'Not found'); } return $response; @@ -1101,6 +1126,18 @@ Here is how you can configure the Symfony reverse proxy to support the You must protect the ``PURGE`` HTTP method somehow to avoid random people purging your cached data. +In many applications, content is used in various URLs. More flexible concepts +exist for those cases: + +* **Banning** invalidates responses matching regular expressions on the + URL or other criteria. +* **Cache tagging** lets you add a tag for each content used in a response + so that you can invalidate all URLs containing a certain content. + +If you need such features, you should use the `FOSHttpCacheBundle`_. This +bundle documents the configuration for the caching proxy and provides +services to send invalidation requests based on URLs and Symfony routes. + Summary ------- @@ -1128,3 +1165,4 @@ Learn more from the Cookbook .. _`P6 - Caching: Browser and intermediary caches`: http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache .. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html .. _`ESI`: http://www.w3.org/TR/esi-lang +.. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/ From 44b03ac961304ac69ee221523c18180b5d407f8a Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Tue, 23 Dec 2014 14:30:19 -0500 Subject: [PATCH 07/36] adding note to assetic cache busting --- reference/configuration/assetic.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reference/configuration/assetic.rst b/reference/configuration/assetic.rst index f7e52faf03b..ae9415ea4fe 100644 --- a/reference/configuration/assetic.rst +++ b/reference/configuration/assetic.rst @@ -49,6 +49,9 @@ Full Default Configuration # An array of named filters (e.g. some_filter, some_other_filter) some_filter: [] workers: + # see https://github.com/symfony/AsseticBundle/pull/119 + # Cache can also be busted via the framework.templating.assets_version + # setting - see the "framework" configuration section cache_busting: enabled: false twig: From 2bddbb17ce1d7e676d6d3be846ad63dabde8e0f9 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Thu, 25 Dec 2014 17:57:51 +0100 Subject: [PATCH 08/36] move invalidation up into expiration and validation section --- book/http_cache.rst | 193 +++++++++++++++++++++++--------------------- 1 file changed, 100 insertions(+), 93 deletions(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 048d1b96e75..97d9de9959f 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -335,7 +335,7 @@ its creation more manageable:: to define cache headers based on the URL pattern and other request properties. -Public vs private Responses +Public vs Private Responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Both gateway and proxy caches are considered "shared" caches as the cached @@ -801,7 +801,105 @@ Additionally, most cache-related HTTP headers can be set via the single )); .. index:: - single: Cache; ESI +single: Cache; Invalidation + +.. _http-cache-invalidation: + +Cache Invalidation +~~~~~~~~~~~~~~~~~~ + + "There are only two hard things in Computer Science: cache invalidation + and naming things." -- Phil Karlton + +Once an URL is cached by a gateway cache, the cache will not ask the +application for that content anymore. This allows the cache to provide fast +responses and reduces the load on your application. However, you risk +delivering outdated content. A way out of this dilemma is to use long +cache lifetimes, but to actively notify the gateway cache when content +changes. Reverse proxies usually provide a channel to receive such +notifications, typically through special HTTP requests. + +.. tip:: + + While cache invalidation is powerful, avoid it when possible. If you fail + to invalidate something, outdated caches will be served for a potentially + long time. Instead, use short cache lifetimes or use the validation model, + and adjust your controllers to perform efficient validation checks as + explained in :ref:`optimizing-cache-validation`. + + Furthermore, since invalidation is a topic specific to each type of reverse + proxy, using this concept will tie you to a specific reverse proxy or need + additional efforts to support different proxies. + +Sometimes, however, you need that extra performance you can get when +explicitly invalidating. For invalidation, your application needs to detect +when content changes and tell the cache to remove the URLs which contain +that data from its cache. + +If one content corresponds to one URL, the ``PURGE`` model works well. +You send a request to the cache proxy with the HTTP method ``PURGE`` instead +of ``GET`` and make the cache proxy detect this and remove the data from the +cache instead of going to Symfony to get a response. + +Here is how you can configure the Symfony reverse proxy to support the +``PURGE`` HTTP method:: + + // app/AppCache.php + + // ... + use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache; + use Symfony\Component\HttpFoundation\Request; + use Symfony\Component\HttpFoundation\Response; + + class AppCache extends HttpCache + { + protected function invalidate(Request $request, $catch = false) + { + if ('PURGE' !== $request->getMethod()) { + return parent::invalidate($request, $catch); + } + + if ('127.0.0.1' !== $request->getClientIp()) { + return new Response('Invalid HTTP method', Response::HTTP_BAD_REQUEST); + } + + $response = new Response(); + if ($this->getStore()->purge($request->getUri())) { + $response->setStatusCode(200, 'Purged'); + } else { + $response->setStatusCode(200, 'Not found'); + } + + return $response; + } + } + +.. caution:: + + You must protect the ``PURGE`` HTTP method somehow to avoid random people + purging your cached data. + +**Purge** instructs the cache to drop a resource in *all its variants* +(according to the ``Vary`` header, see above). An alternative to purging is +**refreshing** a content. Refreshing means that the caching proxy is +instructed to discard its local cache and fetch the content again. This way, +the new content is already available in the cache. The drawback of refreshing +is that variants are not invalidated. + +In many applications, the same content bit is used on various pages with +different URLs. More flexible concepts exist for those cases: + +* **Banning** invalidates responses matching regular expressions on the + URL or other criteria. +* **Cache tagging** lets you add a tag for each content used in a response + so that you can invalidate all URLs containing a certain content. + +If you need such features, you should use the `FOSHttpCacheBundle`_. This +bundle documents the configuration for the caching proxy and provides +services to send invalidation requests based on URLs and Symfony routes. + +.. index:: +single: Cache; ESI single: ESI .. _edge-side-includes: @@ -1047,97 +1145,6 @@ The ``render_esi`` helper supports two other useful options: to the ESI with a value of ``continue`` indicating that, in the event of a failure, the gateway cache will simply remove the ESI tag silently. -.. index:: - single: Cache; Invalidation - -.. _http-cache-invalidation: - -Cache Invalidation ------------------- - - "There are only two hard things in Computer Science: cache invalidation - and naming things." -- Phil Karlton - -Once an URL is cached by a caching reverse proxy, the proxy will not ask the -application for that content anymore. This allows the cache to do fast -responses and reduces the load on your application. However, you risk -delivering outdated content. A way out of this dilemma is to use long -cache lifetimes, but to actively notify the caching proxy when content -changes. Reverse proxies usually provide a channel to receive such -notifications, usually through special HTTP requests. - -.. tip:: - - While cache invalidation sounds powerful, avoid it when possible. If you - fail to invalidate something, outdated caches will stay for a potentially - long time. Instead, use short cache lifetimes or use the validation model, - and adjust your controllers to perform efficient validation checks as - explained in :ref:`optimizing-cache-validation`. - - Furthermore, since invalidation is a topic specific to each type of reverse - proxy, using this concept will tie you to a specific reverse proxy or need - additional efforts to support different proxies. - -Sometimes, however, you need that extra performance you can get when -explicitly invalidating. For invalidation, your application needs to detect -when content changes and tell the cache to remove the URLs which contain -that data from its cache. - -If one content corresponds to one URL, the ``PURGE`` model works well. -You send a request to the cache proxy with the HTTP method ``PURGE`` instead -of ``GET`` and make the cache proxy detect this and remove the data from the -cache instead of going to Symfony to get a response. - -Here is how you can configure the Symfony reverse proxy to support the -``PURGE`` HTTP method:: - - // app/AppCache.php - - // ... - use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache; - use Symfony\Component\HttpFoundation\Request; - use Symfony\Component\HttpFoundation\Response; - - class AppCache extends HttpCache - { - protected function invalidate(Request $request, $catch = false) - { - if ('PURGE' !== $request->getMethod()) { - return parent::invalidate($request, $catch); - } - - if ('127.0.0.1' !== $request->getClientIp()) { - return new Response('Invalid HTTP method', Response::HTTP_BAD_REQUEST); - } - - $response = new Response(); - if ($this->getStore()->purge($request->getUri())) { - $response->setStatusCode(200, 'Purged'); - } else { - $response->setStatusCode(200, 'Not found'); - } - - return $response; - } - } - -.. caution:: - - You must protect the ``PURGE`` HTTP method somehow to avoid random people - purging your cached data. - -In many applications, content is used in various URLs. More flexible concepts -exist for those cases: - -* **Banning** invalidates responses matching regular expressions on the - URL or other criteria. -* **Cache tagging** lets you add a tag for each content used in a response - so that you can invalidate all URLs containing a certain content. - -If you need such features, you should use the `FOSHttpCacheBundle`_. This -bundle documents the configuration for the caching proxy and provides -services to send invalidation requests based on URLs and Symfony routes. - Summary ------- From 979034a10a606516495bae3cbdba26d7c6d7ca5c Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Thu, 25 Dec 2014 18:07:22 +0100 Subject: [PATCH 09/36] move fos httpcache bundle tip up to beginning of invalidation section --- book/http_cache.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 97d9de9959f..19da513be99 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -401,8 +401,8 @@ header when none is set by the developer by following these rules: .. _http-expiration-validation: -HTTP Expiration and Validation ------------------------------- +HTTP Expiration, Validation and Invalidation +-------------------------------------------- The HTTP specification defines two caching models: @@ -419,7 +419,9 @@ The HTTP specification defines two caching models: header) to check if the page has changed since being cached. The goal of both models is to never generate the same response twice by relying -on a cache to store and return "fresh" responses. +on a cache to store and return "fresh" responses. To achieve long caching times +but still provide updated content immediately, *cache invalidation* is +sometimes used. .. sidebar:: Reading the HTTP Specification @@ -819,7 +821,7 @@ cache lifetimes, but to actively notify the gateway cache when content changes. Reverse proxies usually provide a channel to receive such notifications, typically through special HTTP requests. -.. tip:: +.. warning:: While cache invalidation is powerful, avoid it when possible. If you fail to invalidate something, outdated caches will be served for a potentially @@ -836,6 +838,13 @@ explicitly invalidating. For invalidation, your application needs to detect when content changes and tell the cache to remove the URLs which contain that data from its cache. +.. tip:: + + If you want to use cache invalidation, have a look at the + `FOSHttpCacheBundle`_. This bundle provides services to help with various + cache invalidation concepts, and also documents the configuration for the + a couple of common caching proxies. + If one content corresponds to one URL, the ``PURGE`` model works well. You send a request to the cache proxy with the HTTP method ``PURGE`` instead of ``GET`` and make the cache proxy detect this and remove the data from the @@ -894,10 +903,6 @@ different URLs. More flexible concepts exist for those cases: * **Cache tagging** lets you add a tag for each content used in a response so that you can invalidate all URLs containing a certain content. -If you need such features, you should use the `FOSHttpCacheBundle`_. This -bundle documents the configuration for the caching proxy and provides -services to send invalidation requests based on URLs and Symfony routes. - .. index:: single: Cache; ESI single: ESI From 0accf631a5b97b95823721d262ba9eeded230418 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Sat, 27 Dec 2014 09:35:26 +0100 Subject: [PATCH 10/36] cleanup cache book chapter --- book/http_cache.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 19da513be99..e6903692dc8 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -400,6 +400,7 @@ header when none is set by the developer by following these rules: ``private`` directive automatically (except when ``s-maxage`` is set). .. _http-expiration-validation: +.. _http-expiration-and-validation: HTTP Expiration, Validation and Invalidation -------------------------------------------- @@ -775,7 +776,7 @@ at some interval (the expiration) to verify that the content is still valid. annotations. See the `FrameworkExtraBundle documentation`_. .. index:: - pair: Cache; Configuration + pair: Cache; Configuration More Response Methods ~~~~~~~~~~~~~~~~~~~~~ @@ -803,7 +804,7 @@ Additionally, most cache-related HTTP headers can be set via the single )); .. index:: -single: Cache; Invalidation + single: Cache; Invalidation .. _http-cache-invalidation: @@ -821,7 +822,7 @@ cache lifetimes, but to actively notify the gateway cache when content changes. Reverse proxies usually provide a channel to receive such notifications, typically through special HTTP requests. -.. warning:: +.. caution:: While cache invalidation is powerful, avoid it when possible. If you fail to invalidate something, outdated caches will be served for a potentially @@ -846,7 +847,8 @@ that data from its cache. a couple of common caching proxies. If one content corresponds to one URL, the ``PURGE`` model works well. -You send a request to the cache proxy with the HTTP method ``PURGE`` instead +You send a request to the cache proxy with the HTTP method ``PURGE`` (using +the word "PURGE" is a convention, technically this can be any string) instead of ``GET`` and make the cache proxy detect this and remove the data from the cache instead of going to Symfony to get a response. @@ -899,13 +901,13 @@ In many applications, the same content bit is used on various pages with different URLs. More flexible concepts exist for those cases: * **Banning** invalidates responses matching regular expressions on the - URL or other criteria. + URL or other criteria; * **Cache tagging** lets you add a tag for each content used in a response so that you can invalidate all URLs containing a certain content. .. index:: -single: Cache; ESI - single: ESI + single: Cache; ESI + single: ESI .. _edge-side-includes: From d89ad215ce9c6830a31c61cbd6f486fe82691c6a Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 16 Dec 2014 00:45:47 +0100 Subject: [PATCH 11/36] Tried to clarify private services --- components/dependency_injection/advanced.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/components/dependency_injection/advanced.rst b/components/dependency_injection/advanced.rst index 2d07d0eab13..74e7fe35463 100644 --- a/components/dependency_injection/advanced.rst +++ b/components/dependency_injection/advanced.rst @@ -20,11 +20,14 @@ argument for another service. .. _inlined-private-services: -.. note:: +Since a container is not able to detect if a service is retrieved from inside +the container or the outside, a private service may still be retrieved using +the ``get()`` method. - If you use a private service as an argument to only one other service, - this will result in an inlined instantiation (e.g. ``new PrivateFooBar()``) - inside this other service, making it publicly unavailable at runtime. +What makes private services special, is that they are converted from services +to inlined instantiation (e.g. ``new PrivateThing()``) when they are only +injected once, to increase the container performance. This means that you can +never be sure if a private service exists in the container. Simply said: A service will be private when you do not want to access it directly from your code. @@ -60,7 +63,8 @@ Here is an example: $definition->setPublic(false); $container->setDefinition('foo', $definition); -Now that the service is private, you *cannot* call:: +Now that the service is private, you *should not* call (should not means, this +*might* fail, see the explaination above):: $container->get('foo'); From ee6291c2eb86e484975d879b368fbaff50d30c1e Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Tue, 23 Dec 2014 23:08:24 +0100 Subject: [PATCH 12/36] [Reference] update the configuration reference Move some `versionadded` directive to right position and add missing type information. --- reference/configuration/doctrine.rst | 64 ++++++++++------- reference/configuration/framework.rst | 26 +++---- reference/configuration/security.rst | 94 ++++++++++++++++--------- reference/configuration/swiftmailer.rst | 4 +- 4 files changed, 114 insertions(+), 74 deletions(-) diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index 2a04200b361..5a7afc42dca 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -314,31 +314,45 @@ Explicit definition of all the mapped entities is the only necessary configuration for the ORM and there are several configuration options that you can control. The following configuration options exist for a mapping: -* ``type`` One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``. - This specifies which type of metadata type your mapping uses. - -* ``dir`` Path to the mapping or entity files (depending on the driver). - If this path is relative it is assumed to be relative to the bundle root. - This only works if the name of your mapping is a bundle name. If you want - to use this option to specify absolute paths you should prefix the path - with the kernel parameters that exist in the DIC (for example ``%kernel.root_dir%``). - -* ``prefix`` A common namespace prefix that all entities of this mapping - share. This prefix should never conflict with prefixes of other defined - mappings otherwise some of your entities cannot be found by Doctrine. - This option defaults to the bundle namespace + ``Entity``, for example - for an application bundle called ``AcmeHelloBundle`` prefix would be - ``Acme\HelloBundle\Entity``. - -* ``alias`` Doctrine offers a way to alias entity namespaces to simpler, - shorter names to be used in DQL queries or for Repository access. When - using a bundle the alias defaults to the bundle name. - -* ``is_bundle`` This option is a derived value from ``dir`` and by default - is set to true if dir is relative proved by a ``file_exists()`` check - that returns false. It is false if the existence check returns true. In - this case an absolute path was specified and the metadata files are most - likely in a directory outside of a bundle. +type +.... + +One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``. This specifies +which type of metadata type your mapping uses. + +dir +... + +Path to the mapping or entity files (depending on the driver). If this path +is relative it is assumed to be relative to the bundle root. This only works +if the name of your mapping is a bundle name. If you want to use this option +to specify absolute paths you should prefix the path with the kernel parameters +that exist in the DIC (for example ``%kernel.root_dir%``). + +prefix +...... + +A common namespace prefix that all entities of this mapping share. This prefix +should never conflict with prefixes of other defined mappings otherwise some +of your entities cannot be found by Doctrine. This option defaults to the +bundle namespace + ``Entity``, for example for an application bundle called +``AcmeHelloBundle`` prefix would be ``Acme\HelloBundle\Entity``. + +alias +..... + +Doctrine offers a way to alias entity namespaces to simpler, shorter names +to be used in DQL queries or for Repository access. When using a bundle the +alias defaults to the bundle name. + +is_bundle +......... + +This option is a derived value from ``dir`` and by default is set to ``true`` +if dir is relative proved by a ``file_exists()`` check that returns ``false``. +It is ``false`` if the existence check returns ``true``. In this case an +absolute path was specified and the metadata files are most likely in a directory +outside of a bundle. .. index:: single: Configuration; Doctrine DBAL diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index bdbaf06aa96..dacdb535b76 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -464,19 +464,24 @@ would be ``/images/logo.png?version=5``. profiler ~~~~~~~~ -.. versionadded:: 2.2 - The ``enabled`` option was introduced in Symfony 2.2. Previously, the profiler - could only be disabled by omitting the ``framework.profiler`` configuration - entirely. - .. _profiler.enabled: enabled ....... -**default**: ``true`` in the ``dev`` and ``test`` environments +.. versionadded:: 2.2 + The ``enabled`` option was introduced in Symfony 2.2. Prior to Symfony + 2.2, the profiler could only be disabled by omitting the ``framework.profiler`` + configuration entirely. + +**type**: ``boolean`` **default**: ``false`` -The profiler can be disabled by setting this key to ``false``. +The profiler can be enabled by setting this key to ``true``. When you are +using the Symfony Standard Edition, the profiler is enabled in the ``dev`` +and ``test`` environments. + +collect +....... .. versionadded:: 2.3 The ``collect`` option was introduced in Symfony 2.3. Previously, when @@ -484,10 +489,7 @@ The profiler can be disabled by setting this key to ``false``. but the collectors were disabled. Now, the profiler and the collectors can be controlled independently. -collect -....... - -**default**: ``true`` +**type**: ``boolean`` **default**: ``true`` This option configures the way the profiler behaves when it is enabled. If set to ``true``, the profiler collects data for all requests. If you want to only @@ -511,7 +513,7 @@ Whether or not to enable the ``translator`` service in the service container. fallback ........ -**default**: ``en`` +**type**: ``string`` **default**: ``en`` This option is used when the translation key for the current locale wasn't found. diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst index c680bba3d4f..c6418805901 100644 --- a/reference/configuration/security.rst +++ b/reference/configuration/security.rst @@ -248,41 +248,65 @@ For even more details, see :doc:`/cookbook/security/form_login`. The Login Form and Process ~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``login_path`` (type: ``string``, default: ``/login``) - This is the route or path that the user will be redirected to (unless - ``use_forward`` is set to ``true``) when they try to access a - protected resource but isn't fully authenticated. - - This path **must** be accessible by a normal, un-authenticated user, - else you may create a redirect loop. For details, see - ":ref:`Avoid Common Pitfalls `". - -* ``check_path`` (type: ``string``, default: ``/login_check``) - This is the route or path that your login form must submit to. The - firewall will intercept any requests (``POST`` requests only, by default) - to this URL and process the submitted login credentials. - - Be sure that this URL is covered by your main firewall (i.e. don't create - a separate firewall just for ``check_path`` URL). - -* ``use_forward`` (type: ``Boolean``, default: ``false``) - If you'd like the user to be forwarded to the login form instead of - being redirected, set this option to ``true``. - -* ``username_parameter`` (type: ``string``, default: ``_username``) - This is the field name that you should give to the username field of - your login form. When you submit the form to ``check_path``, the security - system will look for a POST parameter with this name. - -* ``password_parameter`` (type: ``string``, default: ``_password``) - This is the field name that you should give to the password field of - your login form. When you submit the form to ``check_path``, the security - system will look for a POST parameter with this name. - -* ``post_only`` (type: ``Boolean``, default: ``true``) - By default, you must submit your login form to the ``check_path`` URL - as a POST request. By setting this option to ``false``, you can send a - GET request to the ``check_path`` URL. +login_path +.......... + +**type**: ``string`` **default**: ``/login`` + +This is the route or path that the user will be redirected to (unless ``use_forward`` +is set to ``true``) when they try to access a protected resource but isn't +fully authenticated. + +This path **must** be accessible by a normal, un-authenticated user, else +you may create a redirect loop. For details, see +":ref:`Avoid Common Pitfalls `". + +check_path +.......... + +**type**: ``string`` **default**: ``/login_check`` + +This is the route or path that your login form must submit to. The firewall +will intercept any requests (``POST`` requests only, by default) to this +URL and process the submitted login credentials. + +Be sure that this URL is covered by your main firewall (i.e. don't create +a separate firewall just for ``check_path`` URL). + +use_forward +........... + +**type**: ``Boolean`` **default**: ``false`` + +If you'd like the user to be forwarded to the login form instead of being +redirected, set this option to ``true``. + +username_parameter +.................. + +**type**: ``string`` **default**: ``_username`` + +This is the field name that you should give to the username field of your +login form. When you submit the form to ``check_path``, the security system +will look for a POST parameter with this name. + +password_parameter +.................. + +**type**: ``string`` **default**: ``_password`` + +This is the field name that you should give to the password field of your +login form. When you submit the form to ``check_path``, the security system +will look for a POST parameter with this name. + +post_only +......... + +**type**: ``Boolean`` **default**: ``true`` + +By default, you must submit your login form to the ``check_path`` URL as +a POST request. By setting this option to ``false``, you can send a GET request +to the ``check_path`` URL. Redirecting after Login ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index 9295493eb68..3aaf52b858a 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -130,7 +130,7 @@ antiflood threshold ......... -**type**: ``string`` **default**: ``99`` +**type**: ``integer`` **default**: ``99`` Used with ``Swift_Plugins_AntiFloodPlugin``. This is the number of emails to send before restarting the transport. @@ -138,7 +138,7 @@ to send before restarting the transport. sleep ..... -**type**: ``string`` **default**: ``0`` +**type**: ``integer`` **default**: ``0`` Used with ``Swift_Plugins_AntiFloodPlugin``. This is the number of seconds to sleep for during a transport restart. From 7427051c8127ef513b8a2043fed2f13f86f5a1a9 Mon Sep 17 00:00:00 2001 From: "Andrew (Andrius) Marcinkevicius" Date: Sun, 28 Dec 2014 21:19:24 +0200 Subject: [PATCH 13/36] Set twig service as private During the best practices workshop it was suggested that it's best to set services to private if they won't be accessed from your code/container --- best_practices/templates.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/best_practices/templates.rst b/best_practices/templates.rst index 01a4b80e80b..516e85b1e42 100644 --- a/best_practices/templates.rst +++ b/best_practices/templates.rst @@ -153,6 +153,7 @@ name is irrelevant because you never use it in your own code): app.twig.app_extension: class: AppBundle\Twig\AppExtension arguments: ["@markdown"] + public: false tags: - { name: twig.extension } From 3d62349398695224643387c5a6f316e760489b5e Mon Sep 17 00:00:00 2001 From: "Andrew (Andrius) Marcinkevicius" Date: Mon, 29 Dec 2014 10:06:00 +0200 Subject: [PATCH 14/36] Fix representation It might be just me, but with `unless` it sounds like **if you want to use your forms in multiple places you should define it in your controllers**. | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | 2.3 | Fixed tickets | --- best_practices/forms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best_practices/forms.rst b/best_practices/forms.rst index 5bd2cfb8757..3778e1d891f 100644 --- a/best_practices/forms.rst +++ b/best_practices/forms.rst @@ -13,7 +13,7 @@ Building Forms Define your forms as PHP classes. The Form component allows you to build forms right inside your controller -code. Honestly, unless you need to reuse the form somewhere else, that's +code. Honestly, if you don't need to reuse the form somewhere else, that's totally fine. But for organization and reuse, we recommend that you define each form in its own PHP class:: From 3a40d5a54fe92b4dd42a3f9f25edb2f7a76f7bda Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 29 Dec 2014 16:12:15 +0100 Subject: [PATCH 15/36] MAde some tweaks suggested by Wouter --- components/yaml/yaml_format.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index d9a290f9537..9e01336734e 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -118,16 +118,16 @@ escaped with double quotes: * ``\P`` Finally, there are other cases when the strings must be quoted, no matter if -using single or double quotes: +you're using single or double quotes: -* when the string is ``true`` or ``false`` (otherwise, it would be treated as a +* When the string is ``true`` or ``false`` (otherwise, it would be treated as a boolean value); -* when the string is ``null`` or ``~`` (otherwise, it would be considered as a +* When the string is ``null`` or ``~`` (otherwise, it would be considered as a ``null`` value); -* when the string looks like a number, such as integers (e.g. ``2``, ``14``, etc.), +* When the string looks like a number, such as integers (e.g. ``2``, ``14``, etc.), floats (e.g. ``2.6``, ``14.9``) and exponential numbers (e.g. ``12e7``, etc.) (otherwise, it would be treated as a numeric value); -* when the string looks like a date (e.g. ``2014-12-31``) (otherwise it would be +* When the string looks like a date (e.g. ``2014-12-31``) (otherwise it would be automatically converted into a Unix timestamp). When a string contains line breaks, you can use the literal style, indicated From 2824867ce86cf2ab0e2510d8d687d3535174fce0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 29 Dec 2014 16:47:07 +0100 Subject: [PATCH 16/36] Rewroded some contents and fixed some lists of elements --- components/yaml/yaml_format.rst | 68 +++++---------------------------- 1 file changed, 10 insertions(+), 58 deletions(-) diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst index 9e01336734e..c8a6f4a0813 100644 --- a/components/yaml/yaml_format.rst +++ b/components/yaml/yaml_format.rst @@ -34,9 +34,9 @@ they can also be unquoted: "A double-quoted string in YAML" -Quoted styles are useful when a string starts or ends with one or more -relevant spaces, because unquoted strings are trimmed on both ends when parsing -their contents. +Quoted styles are useful when a string starts or end with one or more relevant +spaces, because unquoted strings are trimmed on both end when parsing their +contents. Quotes are required when the string contains special or reserved characters. When using single-quoted strings, any single quote ``'`` inside its contents must be doubled to escape it: @@ -49,25 +49,8 @@ Strings containing any of the following characters must be quoted. Although you can use double quotes, for these characters it is more convenient to use single quotes, which avoids having to escape any backslash ``\``: -* ``:`` -* ``{`` -* ``}`` -* ``[`` -* ``]`` -* ``,`` -* ``&`` -* ``*`` -* ``#`` -* ``?`` -* ``|`` -* ``-`` -* ``<`` -* ``>`` -* ``=`` -* ``!`` -* ``%`` -* ``@`` -* ``\``` +* ``:``, ``{``, ``}``, ``[``, ``]``, ``,``, ``&``, ``*``, ``#``, ``?``, ``|``, + ``-``, ``<``, ``>``, ``=``, ``!``, ``%``, ``@``, ``\``` The double-quoted style provides a way to express arbitrary strings, by using ``\`` to escape characters and sequences. For instance, it is very useful @@ -80,42 +63,11 @@ when you need to embed a ``\n`` or a Unicode character in a string. If the string contains any of the following control characters, it must be escaped with double quotes: -* ``\0`` -* ``\x01`` -* ``\x02`` -* ``\x03`` -* ``\x04`` -* ``\x05`` -* ``\x06`` -* ``\a`` -* ``\b`` -* ``\t`` -* ``\n`` -* ``\v`` -* ``\f`` -* ``\r`` -* ``\x0e`` -* ``\x0f`` -* ``\x10`` -* ``\x11`` -* ``\x12`` -* ``\x13`` -* ``\x14`` -* ``\x15`` -* ``\x16`` -* ``\x17`` -* ``\x18`` -* ``\x19`` -* ``\x1a`` -* ``\e`` -* ``\x1c`` -* ``\x1d`` -* ``\x1e`` -* ``\x1f`` -* ``\N`` -* ``\_`` -* ``\L`` -* ``\P`` +* ``\0``, ``\x01``, ``\x02``, ``\x03``, ``\x04``, ``\x05``, ``\x06``, ``\a``, + ``\b``, ``\t``, ``\n``, ``\v``, ``\f``, ``\r``, ``\x0e``, ``\x0f``, ``\x10``, + ``\x11``, ``\x12``, ``\x13``, ``\x14``, ``\x15``, ``\x16``, ``\x17``, ``\x18``, + ``\x19``, ``\x1a``, ``\e``, ``\x1c``, ``\x1d``, ``\x1e``, ``\x1f``, ``\N``, + ``\_``, ``\L``, ``\P`` Finally, there are other cases when the strings must be quoted, no matter if you're using single or double quotes: From 6a5561732c730a6f05fb377ed3f470d65c0a7c54 Mon Sep 17 00:00:00 2001 From: "Andrew (Andrius) Marcinkevicius" Date: Tue, 30 Dec 2014 14:49:23 +0200 Subject: [PATCH 17/36] Update forms.rst --- best_practices/forms.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/best_practices/forms.rst b/best_practices/forms.rst index 3778e1d891f..897e4266468 100644 --- a/best_practices/forms.rst +++ b/best_practices/forms.rst @@ -13,8 +13,8 @@ Building Forms Define your forms as PHP classes. The Form component allows you to build forms right inside your controller -code. Honestly, if you don't need to reuse the form somewhere else, that's -totally fine. But for organization and reuse, we recommend that you define each +code. This is perfectly fine if you don't need to reuse the form somewhere else. +But for organization and reuse, we recommend that you define each form in its own PHP class:: namespace AppBundle\Form; From 7b9d583cdefc7c03f67961b31f7d42ce903b52fe Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Mon, 29 Dec 2014 02:00:59 +0100 Subject: [PATCH 18/36] Clarify tip for creating a new AppBundle The previous description was not quite right, since an AppBundle can also be there in versions before 2.6. --- best_practices/creating-the-project.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/best_practices/creating-the-project.rst b/best_practices/creating-the-project.rst index d9f378ce98a..42dca76c3da 100644 --- a/best_practices/creating-the-project.rst +++ b/best_practices/creating-the-project.rst @@ -152,8 +152,7 @@ that follows these best practices: .. tip:: - If you are using Symfony 2.6 or a newer version, the ``AppBundle`` bundle - is already generated for you. If you are using an older Symfony version, + If your Symfony installation doesn't come with a pre-generated ``AppBundle``, you can generate it by hand executing this command: .. code-block:: bash From 7ae34891054f83fad540ca526d36ec65c09ccc3e Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Tue, 30 Dec 2014 07:44:30 +0100 Subject: [PATCH 19/36] [Reference] Add default_locale config description --- reference/configuration/framework.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index dbe3f463ac7..8336ef0497c 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -19,6 +19,7 @@ Configuration * `http_method_override`_ * `ide`_ * `test`_ +* `default_locale`_ * `trusted_proxies`_ * `form`_ * enabled @@ -76,8 +77,8 @@ http_method_override This determines whether the ``_method`` request parameter is used as the intended HTTP method on POST requests. If enabled, the :method:`Request::enableHttpMethodParameterOverride ` -gets called automatically. It becomes the service container parameter named -``kernel.http_method_override``. For more information, see +method gets called automatically. It becomes the service container parameter +named ``kernel.http_method_override``. For more information, see :doc:`/cookbook/routing/method_parameters`. ide @@ -151,6 +152,17 @@ This setting should be present in your ``test`` environment (usually via .. _reference-framework-trusted-proxies: +default_locale +~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``en`` + +The default locale is used if no ``_locale`` routing parameter has been set. It +becomes the service container parameter named ``kernel.default_locale`` and it +is also available with the +:method:`Request::getDefaultLocale ` +method. + trusted_proxies ~~~~~~~~~~~~~~~ From 7fc4d525b530d84d66ef9a64b92bb94e75098786 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Sat, 20 Dec 2014 23:53:43 +0100 Subject: [PATCH 20/36] document the `2.5` validation options --- reference/configuration/framework.rst | 44 ++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 14e198d0025..cda9a5bbb29 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -55,6 +55,8 @@ Configuration * `cache`_ * `enable_annotations`_ * `translation_domain`_ + * `strict_email`_ + * `api`_ secret ~~~~~~ @@ -531,11 +533,8 @@ cache **type**: ``string`` -This value is used to determine the service that is used to persist class -metadata in a cache. The actual service name is built by prefixing the configured -value with ``validator.mapping.cache.`` (e.g. if the value is ``apc``, the -``validator.mapping.cache.apc`` service will be injected). The service has -to implement the :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface`. +The service that is used to persist class metadata in a cache. The service +has to implement the :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface`. enable_annotations .................. @@ -552,6 +551,41 @@ translation_domain The translation domain that is used when translating validation constraint error messages. +strict_email +............ + +.. versionadded:: 2.5 + The ``strict_email`` option was introduced in Symfony 2.5. + +**type**: ``Boolean`` **default**: ``false`` + +If this option is enabled, the `egulias/email-validator`_ library will be +used by the :doc:`/reference/constraints/Email` constraint validator. Otherwise, +the validator uses a simple regular expression to validate email addresses. + +api +... + +.. versionadded:: 2.5 + The ``api`` option was introduced in Symfony 2.5. + +**type**: ``string`` + +Starting with Symfony 2.5, the Validator component introduced a new validation +API. The ``api`` option is used to switch between the different implementations: + +``2.4`` + Use the vaidation API that is compatible with older Symfony versions. + +``2.5`` + Use the validation API introduced in Symfony 2.5. + +``2.5-bc`` or ``auto`` + If you omit a value or set the ``api`` option to ``2.5-bc`` or ``auto``, + Symfony will use an API implementation that is compatible with both the + legacy implementation and the ``2.5`` implementation. You have to use + PHP 5.3.9 or higher to be able to use this implementation. + Full default Configuration -------------------------- From a30bb1d3e25811720c49950bb421a6d6336a62d7 Mon Sep 17 00:00:00 2001 From: Wouter J Date: Sat, 3 Jan 2015 00:11:59 +0100 Subject: [PATCH 21/36] Formatting fix --- 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 e4cc04152f9..56acbe9a7f1 100644 --- a/components/dependency_injection/factories.rst +++ b/components/dependency_injection/factories.rst @@ -5,7 +5,7 @@ Using a Factory to Create Services ================================== .. versionadded:: 2.6 - The new `Symfony\\Component\\DependencyInjection\\Definition::setFactory` + The new :method:`Symfony\\Component\\DependencyInjection\\Definition::setFactory` method was introduced in Symfony 2.6. Refer to older versions for the syntax for factories prior to 2.6. From f56d26f8ba30707af9a9e80a16abff71e52737b4 Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Sat, 3 Jan 2015 08:51:12 +0100 Subject: [PATCH 22/36] Fix typo and remove redundant sentence --- book/security.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/security.rst b/book/security.rst index daecfa876c4..343fb34f8df 100644 --- a/book/security.rst +++ b/book/security.rst @@ -655,7 +655,7 @@ There are **two** ways to deny access to something: Securing URL patterns (access_control) ...................................... -The most basic way to secure part of your application is to secure an entire +The most basic way to secure parts of your application is to secure an entire URL pattern. You saw this earlier, where anything matching the regular expression ``^/admin`` requires the ``ROLE_ADMIN`` role: @@ -1082,8 +1082,7 @@ Next, you'll need to create a route for this URL (but not a controller): return $collection; And that's it! By sending a user to ``/logout`` (or whatever you configure -the ``path`` to be), Symfony will un-authenticate the current user. and -redirect them the homepage (the value defined by ``target``). +the ``path`` to be), Symfony will un-authenticate the current user. Once the user has been logged out, they will be redirected to whatever path is defined by the ``target`` parameter above (e.g. the ``homepage``). From f86b9c91592f9ff2ca118a01fbdecda3b2483c31 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 7 Dec 2014 20:20:07 -0500 Subject: [PATCH 23/36] Adding a guide about upgrading --- cookbook/upgrading.rst | 127 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 cookbook/upgrading.rst diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst new file mode 100644 index 00000000000..15458e4d93f --- /dev/null +++ b/cookbook/upgrading.rst @@ -0,0 +1,127 @@ +How to Upgrade your Symfony Project +=================================== + +So a new Symfony release has come out and you want to upgrade, great! Fortunately, +because Symfony protects backwards-compatibility very closely, this *should* +be quite easy. + +Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1) +----------------------------------------------- + +If you're upgrading and only the patch version (the last number) is changing, +then it's *really* easy: + +.. code-block:: bash + + $ composer update symfony/symfony + +That's it! You should not encounter any backwards-compatability breaks or +need to change anything else in your code. + +You may also want to upgrade the rest of your libraries. If you've done a +good job with your version constraints in ``composer.json``, you can do this +safely by running: + +.. code-block:: bash + + $ composer update symfony/symfony + +But beware. If you have some bad version constraints in your ``composer.json``, +(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries +to new versions that contain backwards-compability changes. + +Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0) +----------------------------------------------- + +If you're upgrading a minor version (where the middle number changes), then +you should also *not* encounter significant backwards compability changes. +For details, see our :doc:`/contributing/code/bc`. + +However, some backwards-compability breaks *are* possible, and you'll learn +in a second how to prepare for them. + +There are two steps to upgrading: + +1. :ref:`upgrade-minor-symfony-composer`; +2. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. + +.. _`upgrade-minor-symfony-composer`: + +Update the Symfony Library +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, you need to update Symfony by modifying your ``composer.json`` to +use the new version: + +.. code-block:: json + + { + "...": "...", + + "require": { + "php": ">=5.3.3", + "symfony/symfony": "~2.6.0", + "...": "... no changes to anything else..." + }, + "...": "...", + } + +Next, update the same as before: + +.. code-block:: bash + + $ composer update symfony/symfony + +Updating a minor version like this should *not* cause any dependency issues, +though it's always possible that an outside library or bundle you're using +didn't support this new version of Symfony at the version you have of that +library. In that case, consult the library: you may need to modify its version +in ``composer.json`` and run a full ``composer update``. + +.. _`upgrade-minor-symfony-code`: + +Updating your Code to work with the new Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In theory, you should be done! However, you *may* need to make a few changes +to your code to get everything working. Additionally, some features you're +using might still work, but might now be deprecated. That's actually ok, +but if you know about these deprecations, you can start to fix them over +time. + +Every version of Symfony comes with an UPGRADE file that describes these +changes. Below are links to the file for each version, along with some other +details. + +Upgrading to Symfony 2.6 +........................ + +First, of course, update your ``composer.json`` file with the ``2.6`` version +of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. + +Check the `UPGRADE-2.6`_ document for details. Highlights: + +* If you're using PdoSessionStorage, there was a change in the session schema + that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`. + +* Symfony 2.6 comes with a great new `dump`_ function. To use it, you'll + need to add the new ``DebugBundle`` to your ``AppKernel``. See + `UPGRADE-2.6-DebugBundle`_ for details. + +Upgrading to Symfony 2.5 +........................ + +First, of course, update your ``composer.json`` file with the ``2.5`` version +of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. + +Check the `UPGRADE-2.5`_ document for details. Highlights: + +* This version introduced a new Validator API. But, as long as you're using + PHP 5.3.9 or higher, you can configure Symfony in a way that allows you + to use the new API, but still let the old API work (called ``2.5-bc``). + See the `UPGRADE-2.5-Validator`_ for details. + +.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md +.. _`UPGRADE-2.5-Validator`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.5.md#validator +.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md +.. _`UPGRADE-2.6-DebugBundle`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md#vardumper-and-debugbundle From 92b4310da171be45cd4ad36bc8b42417fc24a9e0 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 12:31:11 -0500 Subject: [PATCH 24/36] [#4611] Making many tweaks thanks to guys like Javier, Wouter, Christian (xabbuh) and Stof --- cookbook/upgrading.rst | 64 +++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index 15458e4d93f..eaa63674532 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -1,10 +1,17 @@ -How to Upgrade your Symfony Project +How to Upgrade Your Symfony Project =================================== So a new Symfony release has come out and you want to upgrade, great! Fortunately, because Symfony protects backwards-compatibility very closely, this *should* be quite easy. +There are two types of upgrades, and both are a little different: + +* :ref:`upgrading-patch-version` +* :ref:`upgrading-minor-version` + +.. _upgrading-patch-version: + Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1) ----------------------------------------------- @@ -15,8 +22,10 @@ then it's *really* easy: $ composer update symfony/symfony -That's it! You should not encounter any backwards-compatability breaks or -need to change anything else in your code. +That's it! You should not encounter any backwards-compatibility breaks or +need to change anything else in your code. That's because when you started +your Symfony project, your ``composer.json`` included Symfony using a constraint +such as ``2.6.*``, where only the *last* version number changes when you update. You may also want to upgrade the rest of your libraries. If you've done a good job with your version constraints in ``composer.json``, you can do this @@ -24,31 +33,33 @@ safely by running: .. code-block:: bash - $ composer update symfony/symfony + $ composer update But beware. If you have some bad version constraints in your ``composer.json``, (e.g. ``dev-master``), then this could upgrade some non-Symfony libraries -to new versions that contain backwards-compability changes. +to new versions that contain backwards-compatibility breaking changes. + +.. _upgrading-minor-version: Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0) ----------------------------------------------- If you're upgrading a minor version (where the middle number changes), then -you should also *not* encounter significant backwards compability changes. +you should also *not* encounter significant backwards compatibility changes. For details, see our :doc:`/contributing/code/bc`. -However, some backwards-compability breaks *are* possible, and you'll learn +However, some backwards-compatibility breaks *are* possible, and you'll learn in a second how to prepare for them. There are two steps to upgrading: -1. :ref:`upgrade-minor-symfony-composer`; -2. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. +#. :ref:`upgrade-minor-symfony-composer`; +#. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. .. _`upgrade-minor-symfony-composer`: -Update the Symfony Library -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Update the Symfony Library via Composer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First, you need to update Symfony by modifying your ``composer.json`` to use the new version: @@ -60,13 +71,13 @@ use the new version: "require": { "php": ">=5.3.3", - "symfony/symfony": "~2.6.0", + "symfony/symfony": "~2.6.*", "...": "... no changes to anything else..." }, "...": "...", } -Next, update the same as before: +Next, use Composer to download new versions of the libraries: .. code-block:: bash @@ -75,12 +86,12 @@ Next, update the same as before: Updating a minor version like this should *not* cause any dependency issues, though it's always possible that an outside library or bundle you're using didn't support this new version of Symfony at the version you have of that -library. In that case, consult the library: you may need to modify its version +library. In that case, consult the library: you may need to modify its version in ``composer.json`` and run a full ``composer update``. .. _`upgrade-minor-symfony-code`: -Updating your Code to work with the new Version +Updating Your Code to Work with the new Version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In theory, you should be done! However, you *may* need to make a few changes @@ -90,8 +101,13 @@ but if you know about these deprecations, you can start to fix them over time. Every version of Symfony comes with an UPGRADE file that describes these -changes. Below are links to the file for each version, along with some other -details. +changes. Below are links to the file for each version, which you'll need +to read to see if you need any code changes. + +.. tip:: + + Don't see the version here that you're upgrading too? Just find the + UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_. Upgrading to Symfony 2.6 ........................ @@ -99,7 +115,8 @@ Upgrading to Symfony 2.6 First, of course, update your ``composer.json`` file with the ``2.6`` version of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. -Check the `UPGRADE-2.6`_ document for details. Highlights: +Next, check the `UPGRADE-2.6`_ document for details about any code changes +that you might need to make in your project. * If you're using PdoSessionStorage, there was a change in the session schema that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`. @@ -114,14 +131,9 @@ Upgrading to Symfony 2.5 First, of course, update your ``composer.json`` file with the ``2.5`` version of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. -Check the `UPGRADE-2.5`_ document for details. Highlights: - -* This version introduced a new Validator API. But, as long as you're using - PHP 5.3.9 or higher, you can configure Symfony in a way that allows you - to use the new API, but still let the old API work (called ``2.5-bc``). - See the `UPGRADE-2.5-Validator`_ for details. +Next, check the `UPGRADE-2.5`_ document for details about any code changes +that you might need to make in your project. .. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md -.. _`UPGRADE-2.5-Validator`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.5.md#validator .. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md -.. _`UPGRADE-2.6-DebugBundle`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md#vardumper-and-debugbundle +.. _`Symfony Repository`: https://github.com/symfony/symfony From 8195a66ed2aa6d4969a12dbb32bbfc73413b0352 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 12:56:21 -0500 Subject: [PATCH 25/36] [#4611] Removing a few entries I meant to remove before --- cookbook/upgrading.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index eaa63674532..9794b791815 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -118,13 +118,6 @@ of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. Next, check the `UPGRADE-2.6`_ document for details about any code changes that you might need to make in your project. -* If you're using PdoSessionStorage, there was a change in the session schema - that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`. - -* Symfony 2.6 comes with a great new `dump`_ function. To use it, you'll - need to add the new ``DebugBundle`` to your ``AppKernel``. See - `UPGRADE-2.6-DebugBundle`_ for details. - Upgrading to Symfony 2.5 ........................ From e6b3f1364fef2f7a8217ab6fdc1af6e8ea768a64 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 12:57:00 -0500 Subject: [PATCH 26/36] Basically copying a section about upgrading other libraries down into the minor version section --- cookbook/upgrading.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index 9794b791815..f88b191af9a 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -35,7 +35,7 @@ safely by running: $ composer update -But beware. If you have some bad version constraints in your ``composer.json``, +But beware. If you have some bad `version constraints`_ in your ``composer.json``, (e.g. ``dev-master``), then this could upgrade some non-Symfony libraries to new versions that contain backwards-compatibility breaking changes. @@ -83,11 +83,17 @@ Next, use Composer to download new versions of the libraries: $ composer update symfony/symfony -Updating a minor version like this should *not* cause any dependency issues, -though it's always possible that an outside library or bundle you're using -didn't support this new version of Symfony at the version you have of that -library. In that case, consult the library: you may need to modify its version -in ``composer.json`` and run a full ``composer update``. +You may also want to upgrade the rest of your libraries. If you've done a +good job with your version constraints in ``composer.json``, you can do this +safely by running: + +.. code-block:: bash + + $ composer update + +But beware. If you have some bad `version constraints`_ in your ``composer.json``, +(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries +to new versions that contain backwards-compatibility breaking changes. .. _`upgrade-minor-symfony-code`: @@ -130,3 +136,5 @@ that you might need to make in your project. .. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md .. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md .. _`Symfony Repository`: https://github.com/symfony/symfony +.. _`Composer Package Versions`: https://getcomposer.org/doc/01-basic-usage.md#package-versions +.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions \ No newline at end of file From ca1e7dff9add4b8406135721fdae4345b4b396c1 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 13:08:55 -0500 Subject: [PATCH 27/36] [#4611] A few more tweaks and fixes --- cookbook/upgrading.rst | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index f88b191af9a..0dc36fcd160 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -24,12 +24,13 @@ then it's *really* easy: That's it! You should not encounter any backwards-compatibility breaks or need to change anything else in your code. That's because when you started -your Symfony project, your ``composer.json`` included Symfony using a constraint -such as ``2.6.*``, where only the *last* version number changes when you update. +your project, your ``composer.json`` included Symfony using a constraint +like ``2.6.*``, where only the *last* version number will change when you +update. You may also want to upgrade the rest of your libraries. If you've done a -good job with your version constraints in ``composer.json``, you can do this -safely by running: +good job with your `version constraints`_ in ``composer.json``, you can do +this safely by running: .. code-block:: bash @@ -41,7 +42,7 @@ to new versions that contain backwards-compatibility breaking changes. .. _upgrading-minor-version: -Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0) +Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1) ----------------------------------------------- If you're upgrading a minor version (where the middle number changes), then @@ -53,16 +54,16 @@ in a second how to prepare for them. There are two steps to upgrading: -#. :ref:`upgrade-minor-symfony-composer`; -#. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. +:ref:`upgrade-minor-symfony-composer`; +:ref:`upgrade-minor-symfony-code` .. _`upgrade-minor-symfony-composer`: -Update the Symfony Library via Composer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1) Update the Symfony Library via Composer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, you need to update Symfony by modifying your ``composer.json`` to -use the new version: +First, you need to update Symfony by modifying your ``composer.json`` file +to use the new version: .. code-block:: json @@ -71,7 +72,7 @@ use the new version: "require": { "php": ">=5.3.3", - "symfony/symfony": "~2.6.*", + "symfony/symfony": "2.6.*", "...": "... no changes to anything else..." }, "...": "...", @@ -84,8 +85,8 @@ Next, use Composer to download new versions of the libraries: $ composer update symfony/symfony You may also want to upgrade the rest of your libraries. If you've done a -good job with your version constraints in ``composer.json``, you can do this -safely by running: +good job with your `version constraints`_ in ``composer.json``, you can do +this safely by running: .. code-block:: bash @@ -97,8 +98,8 @@ to new versions that contain backwards-compatibility breaking changes. .. _`upgrade-minor-symfony-code`: -Updating Your Code to Work with the new Version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +2) Updating Your Code to Work with the new Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In theory, you should be done! However, you *may* need to make a few changes to your code to get everything working. Additionally, some features you're @@ -112,7 +113,7 @@ to read to see if you need any code changes. .. tip:: - Don't see the version here that you're upgrading too? Just find the + Don't see the version here that you're upgrading to? Just find the UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_. Upgrading to Symfony 2.6 From 9701e466f91d6feb4402241a09f6fe9e860f3925 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 13:10:54 -0500 Subject: [PATCH 28/36] Adding missing index/map documents --- cookbook/index.rst | 1 + cookbook/map.rst.inc | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/cookbook/index.rst b/cookbook/index.rst index 7fc317ab45a..03d29060c7f 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -28,6 +28,7 @@ The Cookbook symfony1 templating/index testing/index + upgrading validation/index web_server/index web_services/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index ee726b0f96f..ca553febe91 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -199,6 +199,10 @@ * (email) :doc:`/cookbook/email/testing` * (form) :doc:`/cookbook/form/unit_testing` +* **Upgrading** + + * :doc:`/cookbook/upgrading` + * :doc:`/cookbook/validation/index` * :doc:`/cookbook/validation/custom_constraint` From 81728b63798763fc8d22a68de4186aa736a010b2 Mon Sep 17 00:00:00 2001 From: Peter Rehm Date: Wed, 12 Nov 2014 21:37:02 +0100 Subject: [PATCH 29/36] More concrete explanation of validation groups --- book/forms.rst | 35 ++++++++++++++++++++++++++++++++--- book/validation.rst | 29 ++++++++++++++++++++++++++++- 2 files changed, 60 insertions(+), 4 deletions(-) diff --git a/book/forms.rst b/book/forms.rst index 0ff9231e4c2..01097646b7a 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -526,6 +526,7 @@ to an array callback:: use Symfony\Component\OptionsResolver\OptionsResolverInterface; + // ... public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( @@ -541,23 +542,51 @@ This will call the static method ``determineValidationGroups()`` on the The Form object is passed as an argument to that method (see next example). You can also define whole logic inline by using a ``Closure``:: + use Acme\AcmeBundle\Entity\Client; use Symfony\Component\Form\FormInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; + // ... public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'validation_groups' => function(FormInterface $form) { $data = $form->getData(); - if (Entity\Client::TYPE_PERSON == $data->getType()) { + if (Client::TYPE_PERSON == $data->getType()) { return array('person'); - } else { - return array('company'); } + + return array('company'); + }, + )); + } + +Using the ``validation_groups`` option overrides the default validation +group which is being used. If you want to validate the default constraints +of the entity as well you have to adjust the option as follows:: + + use Acme\AcmeBundle\Entity\Client; + use Symfony\Component\Form\FormInterface; + use Symfony\Component\OptionsResolver\OptionsResolverInterface; + + // ... + public function setDefaultOptions(OptionsResolverInterface $resolver) + { + $resolver->setDefaults(array( + 'validation_groups' => function(FormInterface $form) { + $data = $form->getData(); + if (Client::TYPE_PERSON == $data->getType()) { + return array('Default', 'person'); + } + + return array('Default', 'company'); }, )); } +You can find more information about how the validation groups and the default constraints +work in the book section about :ref:`validation groups `. + .. index:: single: Forms; Validation groups based on clicked button diff --git a/book/validation.rst b/book/validation.rst index c6037c81f2f..bb47e2dedcf 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -814,11 +814,38 @@ With this configuration, there are three validation groups: that belong to no other group. ``User`` - Equivalent to all constraints of the ``User`` object in the ``Default`` group. + Equivalent to all constraints of the ``User`` object in the ``Default`` + group. This is always the name of the class. The difference between this + and ``Default`` is explained below. ``registration`` Contains the constraints on the ``email`` and ``password`` fields only. +Constraints in the ``Default`` group of a class are the constraints that have either no +explicit group configured or that are configured to a group equal to the class name or +the string ``Default``. + +.. caution:: + + When validating *just* the User object, there is no difference between the ``Default`` group + and the ``User`` group. But, there is a difference if ``User`` has embedded objects. For example, + imagine ``User`` has an ``address`` property that contains some ``Address`` object and that + you've added the :doc:`/reference/constraints/valid` constraint to this property so that it's + validated when you validate the ``User`` object. + + If you validate ``User`` using the ``Default`` group, then any constraints on the ``Address`` + class that are in the ``Default`` group *will* be used. But, if you validate ``User`` using the + ``User`` validation group, then only constraints on the ``Address`` class with the ``User`` + group will be validated. + + In other words, the ``Default`` group and the class name group (e.g. ``User``) are identical, + except when the class is embedded in another object that's actually the one being validated. + + In case you have inheritance in your data model and you validate with the class name of + the subclass in the subclass and in the baseclass all constraints in the default group + will be validated. If you use the name of the baseclass only the constraints in the base + class will be validated. + To tell the validator to use a specific group, pass one or more group names as the second argument to the ``validate()`` method:: From 09f9d3dc68812156d91f79b7642f6c61dbc6318e Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 14:22:45 -0500 Subject: [PATCH 30/36] [#4454] Re-wording section, but it may not actually be accurate --- book/validation.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/book/validation.rst b/book/validation.rst index bb47e2dedcf..e77c7f727d4 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -841,10 +841,11 @@ the string ``Default``. In other words, the ``Default`` group and the class name group (e.g. ``User``) are identical, except when the class is embedded in another object that's actually the one being validated. - In case you have inheritance in your data model and you validate with the class name of - the subclass in the subclass and in the baseclass all constraints in the default group - will be validated. If you use the name of the baseclass only the constraints in the base - class will be validated. + If you have inheritance (e.g. ``User extends BaseUser``) and you validate + with the class name of the subclass (i.e. ``User``), then all constraints + in the ``User`` and ``BaseUser`` will be validated. However, if you validate + using the base class (i.e. ``BaseUser``), then only the constraints in + the ``BaseUser`` group will be validated. To tell the validator to use a specific group, pass one or more group names as the second argument to the ``validate()`` method:: From 2baace0bbf05fb6691b4f68f29c9bfe6974a8fbf Mon Sep 17 00:00:00 2001 From: Adrien Brault Date: Mon, 22 Dec 2014 14:04:50 +0100 Subject: [PATCH 31/36] Add exception to console exception log --- cookbook/console/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/console/logging.rst b/cookbook/console/logging.rst index 031121051f1..ae69c4264da 100644 --- a/cookbook/console/logging.rst +++ b/cookbook/console/logging.rst @@ -156,7 +156,7 @@ Then implement the actual listener:: $command->getName() ); - $this->logger->error($message); + $this->logger->error($message, array('exception' => $exception)); } } From 71a24aa66cdb5c32a8f7b9a61b5108e7f886c28c Mon Sep 17 00:00:00 2001 From: TeLiXj Date: Mon, 29 Dec 2014 18:15:08 +0100 Subject: [PATCH 32/36] Update web_server_configuration.rst I had problems using ProxyPassMatch and mod_rewrite and now I use SetHandler to send the request to proxy. This change works fine and should be the standar configuration in the future for Apache and php-fpm. You can read the php developers discussion here http://www.serverphorums.com/read.php?7,956732 or some about problems fixed here http://blog.famillecollet.com/post/2014/03/28/PHP-FPM-and-HTTPD-2.4-improvement --- cookbook/configuration/web_server_configuration.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst index c7ac9f015ac..69e29461cb6 100644 --- a/cookbook/configuration/web_server_configuration.rst +++ b/cookbook/configuration/web_server_configuration.rst @@ -132,8 +132,14 @@ directive to pass requests for PHP files to PHP FPM: # # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1 - ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/web/$1 - + # For Apache 2.4.9 or upper + # This avoid problems with ProxyPassMatch and mod_rewrite or mod_autoindex + + SetHandler proxy:fcgi://127.0.0.1:9000 + + # If you use Apache version below 2.4.9 you must consider update or use this instead + # ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/web/$1 + DocumentRoot /var/www/project/web # enable the .htaccess rewrites From 41ac8c716ee4ca276fdcf9244bd686e318d6f2eb Mon Sep 17 00:00:00 2001 From: TeLiXj Date: Mon, 29 Dec 2014 18:40:34 +0100 Subject: [PATCH 33/36] Update web_server_configuration.rst --- cookbook/configuration/web_server_configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst index 69e29461cb6..44f0a4eff89 100644 --- a/cookbook/configuration/web_server_configuration.rst +++ b/cookbook/configuration/web_server_configuration.rst @@ -132,8 +132,8 @@ directive to pass requests for PHP files to PHP FPM: # # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1 - # For Apache 2.4.9 or upper - # This avoid problems with ProxyPassMatch and mod_rewrite or mod_autoindex + # For Apache 2.4.9 or higher + # Using SetHandler avoids issues with using ProxyPassMatch in combination with mod_rewrite or mod_autoindex SetHandler proxy:fcgi://127.0.0.1:9000 From 18733051c0598d86e2825022c7508a8335e8dc68 Mon Sep 17 00:00:00 2001 From: TeLiXj Date: Mon, 29 Dec 2014 18:49:14 +0100 Subject: [PATCH 34/36] Update web_server_configuration.rst --- cookbook/configuration/web_server_configuration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst index 44f0a4eff89..8a46dbbc9e2 100644 --- a/cookbook/configuration/web_server_configuration.rst +++ b/cookbook/configuration/web_server_configuration.rst @@ -133,7 +133,8 @@ directive to pass requests for PHP files to PHP FPM: # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1 # For Apache 2.4.9 or higher - # Using SetHandler avoids issues with using ProxyPassMatch in combination with mod_rewrite or mod_autoindex + # Using SetHandler avoids issues with using ProxyPassMatch in combination + # with mod_rewrite or mod_autoindex SetHandler proxy:fcgi://127.0.0.1:9000 From 5a56624eea55c3577e8a2b39ce1e17a0bb996673 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 15:45:00 -0500 Subject: [PATCH 35/36] [#4743] parts -> part - subjective, but this sounds slightly better to me --- book/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/security.rst b/book/security.rst index 343fb34f8df..e9dc4df6826 100644 --- a/book/security.rst +++ b/book/security.rst @@ -655,7 +655,7 @@ There are **two** ways to deny access to something: Securing URL patterns (access_control) ...................................... -The most basic way to secure parts of your application is to secure an entire +The most basic way to secure part of your application is to secure an entire URL pattern. You saw this earlier, where anything matching the regular expression ``^/admin`` requires the ``ROLE_ADMIN`` role: From 050722520fef04d96335f2d28219bf7465e29d2b Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 15:47:19 -0500 Subject: [PATCH 36/36] Fixing bad reference --- book/validation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/validation.rst b/book/validation.rst index e77c7f727d4..e81fa66d5c6 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -830,7 +830,7 @@ the string ``Default``. When validating *just* the User object, there is no difference between the ``Default`` group and the ``User`` group. But, there is a difference if ``User`` has embedded objects. For example, imagine ``User`` has an ``address`` property that contains some ``Address`` object and that - you've added the :doc:`/reference/constraints/valid` constraint to this property so that it's + you've added the :doc:`/reference/constraints/Valid` constraint to this property so that it's validated when you validate the ``User`` object. If you validate ``User`` using the ``Default`` group, then any constraints on the ``Address``