From f1de07982fa504b18777a8c304cd203bd9b86c6a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 3 Aug 2015 12:33:05 +0200 Subject: [PATCH 01/15] Updated the article about data collectors --- cookbook/profiler/data_collector.rst | 243 +++++++++++++++++++-------- 1 file changed, 172 insertions(+), 71 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 05343769443..3e090f811b8 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -4,9 +4,9 @@ How to Create a custom Data Collector ===================================== -:doc:`The Symfony Profiler ` delegates data collecting to -data collectors. Symfony comes bundled with a few of them, but you can easily -create your own. +:doc:`The Symfony Profiler ` delegates data collection +to some special classes called data collectors. Symfony comes bundled with a few +of them, but you can easily create your own. Creating a custom Data Collector -------------------------------- @@ -33,12 +33,12 @@ Creating a custom data collector is as simple as implementing the function getName(); } -The ``getName()`` method must return a unique name. This is used to access the -information later on (see :doc:`/cookbook/testing/profiling` for -instance). +The value returned by ``getName()`` must be unique in the application. This value +is also used to access the information later on (see :doc:`/cookbook/testing/profiling` +for instance). -The ``collect()`` method is responsible for storing the data it wants to give -access to in local properties. +The ``collect()`` method is responsible for storing the collected data in local +properties. .. caution:: @@ -51,101 +51,169 @@ Most of the time, it is convenient to extend populate the ``$this->data`` property (it takes care of serializing the ``$this->data`` property):: - class MemoryDataCollector extends DataCollector + // src/AppBundle/DataCollector/MyCollector.php + use Symfony\Component\HttpKernel\DataCollector\DataCollector; + + class MyCollector extends DataCollector { public function collect(Request $request, Response $response, \Exception $exception = null) { $this->data = array( - 'memory' => memory_get_peak_usage(true), + 'variable' => 'value', ); } - public function getMemory() + public function getVariable() { - return $this->data['memory']; + return $this->data['variable']; } public function getName() { - return 'memory'; + return 'app.my_collector'; } } .. _data_collector_tag: -Enabling custom Data Collectors +Enabling Custom Data Collectors ------------------------------- -To enable a data collector, add it as a regular service in one of your -configuration, and tag it with ``data_collector``: +To enable a data collector, define it as a regular service and tag it with +``data_collector``: .. configuration-block:: .. code-block:: yaml + # app/config/services.yml services: - data_collector.your_collector_name: - class: Fully\Qualified\Collector\Class\Name + app.my_collector: + class: AppBundle\DataCollector\MyCollector + public: false tags: - { name: data_collector } .. code-block:: xml - - - + + + + + + + + + .. code-block:: php + // app/config/services.php $container - ->register('data_collector.your_collector_name', 'Fully\Qualified\Collector\Class\Name') + ->register('app.my_collector', 'AppBundle\DataCollector\MyCollector') + ->setPublic(false) ->addTag('data_collector') ; Adding Web Profiler Templates ----------------------------- -When you want to display the data collected by your data collector in the web -debug toolbar or the web profiler, you will need to create a Twig template. The -following example can help you get started: +The information collected by your data collector can be displayed both in the +web debug toolbar and in the web profiler. To do so, you need to create a Twig +template that includes some specific blocks. + +In the simplest case, you just want to display the information in the toolbar +without providing a profiler panel. This requires to define the ``toolbar`` +block and set the value of two variables called ``icon`` and ``text``: -.. code-block:: jinja +.. code-block:: html+jinja {% extends 'WebProfilerBundle:Profiler:layout.html.twig' %} {% block toolbar %} - {# This toolbar item may appear along the top or bottom of the screen.#} {% set icon %} - - Example + {# this is the content displayed as a panel in the toolbar #} + + Information {% endset %} {% set text %} -
- Quick piece of data - 100 units -
-
- Another quick thing - 300 units -
+ {# this is the content displayed when hovering the mouse over + the toolbar panel #} +
+ Quick piece of data + 100 units +
+
+ Another piece of data + 300 units +
{% endset %} - {# Set the "link" value to false if you do not have a big "panel" - section that you want to direct the user to. #} - {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { 'link': true }) }} + {# the 'link' value set to 'false' means that this panel doesn't + show a section in the web profiler. #} + {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: false }) }} + {% endblock %} + +.. tip:: + + Built-in collector templates define all their images as embedded base64-encoded + images. This makes them work everywhere without having to mess with web assets + links: + + .. code-block:: html + + + + Another solution is to define the images as SVG files. In addition to being + resolution-independent, these images can be easily embedded in the Twig + template or included from an external file to reuse them in several templates: + .. code-block:: jinja + + {{ include('@App/data_collector/icon.svg') }} + + You are encouraged to use the latter technique for your own toolbar panels. + +If the toolbar panel includes extended web profiler information, the Twig template +must also define additional blocks: + +.. code-block:: html+jinja + + {% extends '@WebProfiler/Profiler/layout.html.twig' %} + + {% block toolbar %} + {% set icon %} + + Information + {% endset %} + + {% set text %} +
+ {# ... #} +
+ {% endset %} + + {# the 'link' value is now set to 'true', which allows the user to click + on it to access the web profiler panel. Since 'true' is the default + value, you can omit the 'link' parameter entirely #} + {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true }) }} {% endblock %} {% block head %} - {# Optional, if you need your own JS or CSS files. #} - {{ parent() }} {# Use parent() to keep the default styles #} + {# Optional, you can here link to or define your own CSS and JS contents #} + {# {{ parent() }} to keep the default styles #} {% endblock %} {% block menu %} {# This left-hand menu appears when using the full-screen profiler. #} - + Example Collector {% endblock %} @@ -158,57 +226,90 @@ following example can help you get started:

{% endblock %} -Each block is optional. The ``toolbar`` block is used for the web debug -toolbar and ``menu`` and ``panel`` are used to add a panel to the web -profiler. - +The ``menu`` and ``panel`` blocks are the only required blocks to define the +contents displayed in the web profiler panel associated with this data collector. All blocks have access to the ``collector`` object. -.. tip:: +Finally, to enable the data collector template, add a ``template`` attribute to +the ``data_collector`` tag in your service configuration: - Built-in templates use a base64 encoded image for the toolbar: +.. configuration-block:: - .. code-block:: html + .. code-block:: yaml - + # app/config/services.yml + services: + app.my_collector: + class: AppBundle\DataCollector\MyCollector + tags: + - + name: data_collector + template: 'data_collector/template.html.twig' + id: 'app.my_collector' + public: false - You can easily calculate the base64 value for an image with this - little script:: + .. code-block:: xml - #!/usr/bin/env php - + + + + + + + + -To enable the template, add a ``template`` attribute to the ``data_collector`` -tag in your configuration. For example, assuming your template is in AppBundle: + .. code-block:: php + + // app/config/services.php + $container + ->register('app.my_collector', 'AppBundle\DataCollector\MyCollector') + ->setPublic(false) + ->addTag('data_collector', array( + 'template' => 'data_collector/template.html.twig', + 'id' => 'app.my_collector', + )) + ; + +.. caution:: + + The ``id`` attribute must match the value returned by the ``getName()`` method. + +The position of each panel in the toolbar is determined by the priority defined +by each collector. Most built-in collectors use ``255`` as their priority. If you +want your collector to be displayed before them, use a higher value: .. configuration-block:: .. code-block:: yaml + # app/config/services.yml services: - data_collector.your_collector_name: - class: AppBundle\Collector\Class\Name + app.my_collector: + class: AppBundle\DataCollector\MyCollector tags: - - { name: data_collector, template: "AppBundle:Collector:templatename", id: "your_collector_name" } + - { name: data_collector, template: '...', id: '...', priority: '300' } .. code-block:: xml - - + + + .. code-block:: php + // app/config/services.php $container - ->register('data_collector.your_collector_name', 'AppBundle\Collector\Class\Name') + ->register('app.my_collector', 'AppBundle\DataCollector\MyCollector') ->addTag('data_collector', array( - 'template' => 'AppBundle:Collector:templatename', - 'id' => 'your_collector_name', + 'template' => '...', + 'id' => '...', + 'priority' => 300, )) ; - -.. caution:: - - Make sure the ``id`` attribute is the same string you used for the - ``getName()`` method. From e3a80a4e0db51b6e352b8aa32649bc51bd80cf2e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 3 Aug 2015 13:12:33 +0200 Subject: [PATCH 02/15] Implemented all suggestions --- cookbook/profiler/data_collector.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 3e090f811b8..24bc9709c09 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -176,7 +176,11 @@ block and set the value of two variables called ``icon`` and ``text``: .. code-block:: jinja +<<<<<<< HEAD {{ include('@App/data_collector/icon.svg') }} +======= + {{ include('@WebProfiler/Icon/my_collector.svg') }} +>>>>>>> Implemented all suggestions You are encouraged to use the latter technique for your own toolbar panels. @@ -200,14 +204,23 @@ must also define additional blocks: {% endset %} {# the 'link' value is now set to 'true', which allows the user to click +<<<<<<< HEAD on it to access the web profiler panel. Since 'true' is the default +======= + on it to access to the web profiler panel. Since 'true' is the default +>>>>>>> Implemented all suggestions value, you can omit the 'link' parameter entirely #} {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true }) }} {% endblock %} {% block head %} +<<<<<<< HEAD {# Optional, you can here link to or define your own CSS and JS contents #} {# {{ parent() }} to keep the default styles #} +======= + {# Optional, here you can link to or define your own CSS and JS contents #} + {# Use {{ parent() }} to keep the default styles #} +>>>>>>> Implemented all suggestions {% endblock %} {% block menu %} From 93bd994239f4c23023045f3a74b24f02f548c95c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 19 Aug 2015 21:57:49 +0200 Subject: [PATCH 03/15] Tweaks and fixes --- cookbook/profiler/data_collector.rst | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 24bc9709c09..3e090f811b8 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -176,11 +176,7 @@ block and set the value of two variables called ``icon`` and ``text``: .. code-block:: jinja -<<<<<<< HEAD {{ include('@App/data_collector/icon.svg') }} -======= - {{ include('@WebProfiler/Icon/my_collector.svg') }} ->>>>>>> Implemented all suggestions You are encouraged to use the latter technique for your own toolbar panels. @@ -204,23 +200,14 @@ must also define additional blocks: {% endset %} {# the 'link' value is now set to 'true', which allows the user to click -<<<<<<< HEAD on it to access the web profiler panel. Since 'true' is the default -======= - on it to access to the web profiler panel. Since 'true' is the default ->>>>>>> Implemented all suggestions value, you can omit the 'link' parameter entirely #} {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true }) }} {% endblock %} {% block head %} -<<<<<<< HEAD {# Optional, you can here link to or define your own CSS and JS contents #} {# {{ parent() }} to keep the default styles #} -======= - {# Optional, here you can link to or define your own CSS and JS contents #} - {# Use {{ parent() }} to keep the default styles #} ->>>>>>> Implemented all suggestions {% endblock %} {% block menu %} From 69bd67736939831a5b17189ee9bf8acedaadab1d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Sep 2015 17:52:51 +0200 Subject: [PATCH 04/15] Fixed some issues --- cookbook/profiler/data_collector.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 3e090f811b8..47229033063 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -246,7 +246,7 @@ the ``data_collector`` tag in your service configuration: name: data_collector template: 'data_collector/template.html.twig' id: 'app.my_collector' - public: false + public: false .. code-block:: xml @@ -258,8 +258,8 @@ the ``data_collector`` tag in your service configuration: http://symfony.com/schema/dic/services/services-1.0.xsd" > - - + + @@ -293,7 +293,7 @@ want your collector to be displayed before them, use a higher value: app.my_collector: class: AppBundle\DataCollector\MyCollector tags: - - { name: data_collector, template: '...', id: '...', priority: '300' } + - { name: data_collector, template: '...', id: '...', priority: 300 } .. code-block:: xml From b38c36ce895a32cc9325ee826f63a79d092ed014 Mon Sep 17 00:00:00 2001 From: Antonio Mansilla Date: Mon, 5 Oct 2015 19:36:30 +0200 Subject: [PATCH 05/15] Remove not existing response constant --- book/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/testing.rst b/book/testing.rst index 28619de8c04..f7c4a1e5831 100644 --- a/book/testing.rst +++ b/book/testing.rst @@ -273,7 +273,7 @@ document:: $this->assertTrue($client->getResponse()->isNotFound()); // Assert a specific 200 status code $this->assertEquals( - 200, // or Symfony\Component\HttpFoundation\Response::HTTP_OK + 200, $client->getResponse()->getStatusCode() ); From b2e78a6a4a40e64588cc800c5b4f7b0454659e64 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Thu, 1 Oct 2015 19:26:01 +0200 Subject: [PATCH 06/15] translations have been removed from symfony.com --- contributing/documentation/index.rst | 6 +- contributing/documentation/overview.rst | 5 -- contributing/documentation/translations.rst | 86 +-------------------- contributing/map.rst.inc | 1 - 4 files changed, 8 insertions(+), 90 deletions(-) diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index 08782431605..e3711184813 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -7,5 +7,9 @@ Contributing Documentation overview format standards - translations license + +.. toctree:: + :hidden: + + translations diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 378bbd9aeb6..1bf32357620 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -299,11 +299,6 @@ Please be patient. It can take up to several days before your pull request can be fully reviewed. After merging the changes, it could take again several hours before your changes appear on the symfony.com website. -What If I Want to Translate Some Documentation into my Language? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Read the dedicated :doc:`document `. - Why Should I Use the Oldest Maintained Branch Instead of the Master Branch? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index 73779ba3afa..8a00220a198 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -1,87 +1,7 @@ Translations ============ -The Symfony documentation is written in English and many people are involved -in the translation process. +The Symfony documentation is not officially translated, though some community +groups still maintain some translations. For more information, see `this blog post`_. -.. note:: - - Symfony Project officially discourages from starting new translations for the - documentation. As a matter of fact, there is `an ongoing discussion`_ in - the community about the benefits and drawbacks of community driven translations. - -Contributing ------------- - -First, become familiar with the :doc:`markup language ` -used by the documentation. - -Finally, find the *master* repository for the language you want to contribute -for. Here is the list of the official *master* repositories: - -* *English*: https://github.com/symfony/symfony-docs -* *French*: https://github.com/symfony-fr/symfony-docs-fr -* *Italian*: https://github.com/garak/symfony-docs-it -* *Japanese*: https://github.com/symfony-japan/symfony-docs-ja -* *Portuguese (Brazilian)*: https://github.com/andreia/symfony-docs-pt-BR - -.. note:: - - If you want to contribute translations for a new language, read the - :ref:`dedicated section `. - -Joining the Translation Team ----------------------------- - -If you want to help translating some documents for your language or fix some -bugs, consider joining us; it's a very easy process: - -* *(optional)* Ask which documents you can work on; -* Fork the *master* repository for your language (click the "Fork" button on - the GitHub page); -* Translate some documents; -* Ask for a pull request (click on the "Pull Request" from your page on - GitHub); -* The team manager accepts your modifications and merges them into the master - repository; -* The documentation website is updated every other night from the master - repository. - -.. _translations-adding-a-new-language: - -Adding a new Language ---------------------- - -This section gives some guidelines for starting the translation of the -Symfony documentation for a new language. - -As starting a translation is a lot of work, try to find motivated people -willing to help. - -When the team is ready, nominate a team manager; they will be responsible for -the *master* repository. - -Create the repository and copy the *English* documents. - -The team can now start the translation process. - -When the team is confident that the repository is in a consistent and stable -state (everything is translated, or non-translated documents have been removed -from the toctrees -- files named ``index.rst`` and ``map.rst.inc``), the team -manager can ask that the repository is added to the list of official *master* -repositories by sending an email to Fabien (fabien at symfony.com). - -Maintenance ------------ - -Translation does not end when everything is translated. The documentation is a -moving target (new documents are added, bugs are fixed, paragraphs are -reorganized, ...). The translation team need to closely follow the English -repository and apply changes to the translated documents as soon as possible. - -.. caution:: - - Non maintained languages are removed from the official list of - repositories as obsolete documentation is dangerous. - -.. _`an ongoing discussion`: https://github.com/symfony/symfony-docs/issues/4078 +.. _`this blog post`: http://symfony.com/blog/discontinuing-the-symfony-community-translations diff --git a/contributing/map.rst.inc b/contributing/map.rst.inc index 22c759821e4..9ec7f507ab0 100644 --- a/contributing/map.rst.inc +++ b/contributing/map.rst.inc @@ -17,7 +17,6 @@ * :doc:`Overview ` * :doc:`Format ` * :doc:`Documentation Standards ` - * :doc:`Translations ` * :doc:`License ` * **Community** From 63f44e38bd82b497c64e969a5bd01c338a9d8288 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Fri, 9 Oct 2015 09:58:49 +0200 Subject: [PATCH 07/15] [#5771] remove another Response constant --- book/http_cache.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 1d5cb32132d..5cb66842ff5 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -912,7 +912,7 @@ Here is how you can configure the Symfony reverse proxy to support the if ('127.0.0.1' !== $request->getClientIp()) { return new Response( 'Invalid HTTP method', - Response::HTTP_BAD_REQUEST + 400 ); } From 98967bf6ab219f7c9e63d8fc408d245dd3d95ff9 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Fri, 9 Oct 2015 10:05:03 +0200 Subject: [PATCH 08/15] Revert "Remove not existing response constant" This reverts commit b38c36ce895a32cc9325ee826f63a79d092ed014. The `Response::HTTP_OK` constant was added in Symfony 2.4. Thus, removing it (as done in #5771 for the `2.3` branch) must be reverted for the documentation of the `2.7` branch. --- book/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/testing.rst b/book/testing.rst index 6368ac31422..9dc85d4cba8 100644 --- a/book/testing.rst +++ b/book/testing.rst @@ -277,7 +277,7 @@ document:: $this->assertTrue($client->getResponse()->isNotFound()); // Assert a specific 200 status code $this->assertEquals( - 200, + 200, // or Symfony\Component\HttpFoundation\Response::HTTP_OK $client->getResponse()->getStatusCode() ); From a6cbbb2644bce2827e4907692d6eb1e2bc5ce14b Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Fri, 9 Oct 2015 10:06:26 +0200 Subject: [PATCH 09/15] Revert "[#5771] remove another Response constant" This reverts commit 63f44e38bd82b497c64e969a5bd01c338a9d8288. The `Response::HTTP_BAD_REQUEST` constant was added in Symfony 2.4. Thus, removing it (as done it was done after #5771 for the `2.3` branch) must be reverted for the documentation of the `2.7` branch. --- book/http_cache.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 5cb66842ff5..1d5cb32132d 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -912,7 +912,7 @@ Here is how you can configure the Symfony reverse proxy to support the if ('127.0.0.1' !== $request->getClientIp()) { return new Response( 'Invalid HTTP method', - 400 + Response::HTTP_BAD_REQUEST ); } From 662bb01feb740d349cc2658c09ce0c2f2fab055c Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 31 Aug 2015 00:46:45 +0200 Subject: [PATCH 10/15] Info about implicit session start --- book/forms.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/book/forms.rst b/book/forms.rst index 49e9829433a..8aaf2848978 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -1783,6 +1783,11 @@ The ``_token`` field is a hidden field and will be automatically rendered if you include the ``form_end()`` function in your template, which ensures that all un-rendered fields are output. +.. caution:: + + Since the token is stored in the session, a session is started automatically + as soon as you render a form with CSRF protection. + The CSRF token can be customized on a form-by-form basis. For example:: use Symfony\Component\OptionsResolver\OptionsResolverInterface; From 1e1b036b1b30a01678d08b99ef667e0700f5a7b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Baptiste=20Clavi=C3=A9?= Date: Fri, 11 Sep 2015 11:36:20 +0200 Subject: [PATCH 11/15] [DI] Add some documentation for the deprecation feature --- components/dependency_injection/advanced.rst | 60 ++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/components/dependency_injection/advanced.rst b/components/dependency_injection/advanced.rst index 313dfbd1e44..7bef064c7ee 100644 --- a/components/dependency_injection/advanced.rst +++ b/components/dependency_injection/advanced.rst @@ -218,3 +218,63 @@ You can change the inner service name if you want to: ->addArgument(new Reference('bar.wooz')) ->setPublic(false) ->setDecoratedService('foo', 'bar.wooz'); + +Deprecating Services +-------------------- +.. versionadded:: 2.8 + The ``deprecated`` setting was introduced in Symfony 2.8 + +Once you have decided to deprecate the use of a service (because it is outdated +or you decided not to use and maintain it anymore), you can deprecate its +definition: + +.. configuration-block:: + + .. code-block:: yaml + + bar: + class: stdClass + deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0. + + .. code-block:: xml + + + The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0. + + + .. code-block:: php + + $container + ->register('bar', 'stdClass') + ->setDeprecated(true, 'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.'); + +Now, every time a service is created using this deprecated definition, a +deprecation warning will be triggered, advising you to stop or to change your +uses of that service. + +The message is actually a message template, which will replace occurrences +of the ``%service_id%`` by the service's id. You **must** have at least one +occurrence of the ``%service_id%`` placeholder in your template. + +.. note:: + + The deprecation message is optional. If not set, Symfony will show a default + message ``The "%service_id%" service is deprecated. You should stop using it, + as it will soon be removed.``. + +.. tip:: + + It is strongly recommended that you fill the message template, to avoid a + message that could be too generic such as the default one. A good message + informs when this service was deprecated, and until when it will be + maintained (look at the examples above). + +For service decorators (see above), if the definition does not modify the +deprecated status, it will inherit the status from the definition that is +decorated. + +.. caution:: + + The ability to "un-deprecate" a service is possible only when declaring the + definition in PHP. + From c9a4bbf40e6e6087010bacafe061f2d97cd9c5a4 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 11 Oct 2015 00:14:35 +0200 Subject: [PATCH 12/15] [#5689] Some minor syntax fixes --- components/dependency_injection/advanced.rst | 50 ++++++++++++-------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/components/dependency_injection/advanced.rst b/components/dependency_injection/advanced.rst index 7bef064c7ee..58fde9ba615 100644 --- a/components/dependency_injection/advanced.rst +++ b/components/dependency_injection/advanced.rst @@ -221,8 +221,9 @@ You can change the inner service name if you want to: Deprecating Services -------------------- + .. versionadded:: 2.8 - The ``deprecated`` setting was introduced in Symfony 2.8 + The ``deprecated`` setting was introduced in Symfony 2.8. Once you have decided to deprecate the use of a service (because it is outdated or you decided not to use and maintain it anymore), you can deprecate its @@ -232,21 +233,33 @@ definition: .. code-block:: yaml - bar: - class: stdClass - deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0. + acme.my_service: + class: ... + deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0. .. code-block:: xml - - The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0. - + + + + + + The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0. + + + .. code-block:: php $container - ->register('bar', 'stdClass') - ->setDeprecated(true, 'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.'); + ->register('acme.my_service', '...') + ->setDeprecated( + true, + 'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.' + ) + ; Now, every time a service is created using this deprecated definition, a deprecation warning will be triggered, advising you to stop or to change your @@ -258,16 +271,16 @@ occurrence of the ``%service_id%`` placeholder in your template. .. note:: - The deprecation message is optional. If not set, Symfony will show a default - message ``The "%service_id%" service is deprecated. You should stop using it, - as it will soon be removed.``. + The deprecation message is optional. If not set, Symfony will show a default + message ``The "%service_id%" service is deprecated. You should stop using it, + as it will soon be removed.``. .. tip:: - It is strongly recommended that you fill the message template, to avoid a - message that could be too generic such as the default one. A good message - informs when this service was deprecated, and until when it will be - maintained (look at the examples above). + It is strongly recommended that you fill the message template, to avoid a + message that could be too generic such as the default one. A good message + informs when this service was deprecated, and until when it will be + maintained (look at the examples above). For service decorators (see above), if the definition does not modify the deprecated status, it will inherit the status from the definition that is @@ -275,6 +288,5 @@ decorated. .. caution:: - The ability to "un-deprecate" a service is possible only when declaring the - definition in PHP. - + The ability to "un-deprecate" a service is possible only when declaring the + definition in PHP. From 7ce803c7c27aa84d9020d60e16ba51f5e8f5ccfc Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sun, 11 Oct 2015 14:12:44 +0200 Subject: [PATCH 13/15] Misspelling It should be "were" instead of "where". But I think it is even better to use the present tense here, so I changed it to "is" --- reference/constraints/UniqueEntity.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index 1f73e24ce34..3350cf263ca 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -120,7 +120,7 @@ fields This required option is the field (or list of fields) on which this entity should be unique. For example, if you specified both the ``email`` and ``name`` field in a single ``UniqueEntity`` constraint, then it would enforce that -the combination value where unique (e.g. two users could have the same email, +the combination value is unique (e.g. two users could have the same email, as long as they don't have the same name also). If you need to require two fields to be individually unique (e.g. a unique From 9926e039e41238b0100b9278446def3026eac6bc Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 11 Oct 2015 18:05:37 +0200 Subject: [PATCH 14/15] Added September changelog --- changelog.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/changelog.rst b/changelog.rst index 2a947a64612..62685220b1e 100644 --- a/changelog.rst +++ b/changelog.rst @@ -13,6 +13,56 @@ documentation. Do you also want to participate in the Symfony Documentation? Take a look at the ":doc:`/contributing/documentation/overview`" article. +September, 2015 +--------------- + +New Documentation +~~~~~~~~~~~~~~~~~ + +* `#5555 `_ added result yaml and xml from example code (OskarStark) +* `#5631 `_ Updated the Quick Tour to the latest changes introduced by Symfony (javiereguiluz) +* `#5497 `_ Simplified the Quick tour explanation about Symfony Installation (DQNEO) + +Fixed Documentation +~~~~~~~~~~~~~~~~~~~ + +* `#5629 `_ Fixing web user permission (BenoitLeveque) +* `#5673 `_ Update http_cache.rst (szyszka90) +* `#5666 `_ Fix EntityManager namespace (JhonnyL) +* `#5656 `_ Fix monolog line formatter in logging cookbook example. (vmarquez) +* `#5507 `_ Path fixed (carlosreig) + +Minor Documentation Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `#5719 `_ changed repo names to the new ones (fabpot) +* `#5227 `_ [Cookbook] Fix doc on Generic Form Type Extensions (lemoinem) +* `#5683 `_ Improve the demo-warning. (GuGuss) +* `#5690 `_ Updated the release process image (javiereguiluz) +* `#5188 `_ Updated Cookies & Caching section (lukey78) +* `#5710 `_ Fix grammar mistake in security.rst (zatikbalazs) +* `#5706 `_ Update assetic.rst (Acinonux) +* `#5705 `_ Update assetic.rst (Acinonux) +* `#5685 `_ Fix indentation in some annotations (iamdto) +* `#5704 `_ Fix typo in translation.rst (zatikbalazs) +* `#5701 `_ Update testing.rst (hansallis) +* `#5692 `_ Made a sentence slightly more english (GTheron) +* `#5715 `_ Add missing code tag (zatikbalazs) +* `#5714 `_ Remove unnecessary word from http_cache.rst (zatikbalazs) +* `#5680 `_ fix grammar mistake (greg0ire) +* `#5682 `_ Fix grammar and CS (iamdto) +* `#5652 `_ Do not use dynamic REQUEST_URI from $_SERVER as base url (senkal) +* `#5654 `_ Doc about new way of running tests (nicolas-grekas) +* `#5598 `_ [Cookbook][Security] proofread comments in voter article (xabbuh) +* `#5560 `_ [2.3] [Contributing] [CS] Added missing docblocks in code snippet (phansys) +* `#5674 `_ Update cookbook entries with best practices (JhonnyL) +* `#5675 `_ [Contributing] add a link to the testing section (xabbuh) +* `#5669 `_ Better explanation of implicit exception response status code (hvt) +* `#5619 `_ Remove a caution note about StringUtils::equals() which is no longer true (javiereguiluz) +* `#5571 `_ Some small fixes for upload files article (WouterJ) +* `#5660 `_ Improved "Community Reviews" page (webmozart) + + August, 2015 ------------ From 804e04cf21b7bda77dbb9aea0d67f797a3b9c68d Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 11 Oct 2015 18:06:02 +0200 Subject: [PATCH 15/15] Added September changelog --- changelog.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/changelog.rst b/changelog.rst index 50a2562af33..e87e474b21c 100644 --- a/changelog.rst +++ b/changelog.rst @@ -35,8 +35,10 @@ Fixed Documentation Minor Documentation Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `#5740 `_ Fix typo in PdoSessionHandler Documentation (tobemedia) * `#5719 `_ changed repo names to the new ones (fabpot) * `#5227 `_ [Cookbook] Fix doc on Generic Form Type Extensions (lemoinem) +* `#5703 `_ comment old logic (OskarStark) * `#5683 `_ Improve the demo-warning. (GuGuss) * `#5690 `_ Updated the release process image (javiereguiluz) * `#5188 `_ Updated Cookies & Caching section (lukey78) @@ -46,8 +48,10 @@ Minor Documentation Changes * `#5685 `_ Fix indentation in some annotations (iamdto) * `#5704 `_ Fix typo in translation.rst (zatikbalazs) * `#5701 `_ Update testing.rst (hansallis) +* `#5711 `_ removed service call from controller (sloba88) * `#5692 `_ Made a sentence slightly more english (GTheron) * `#5715 `_ Add missing code tag (zatikbalazs) +* `#5720 `_ adding closing tag (InfoTracer) * `#5714 `_ Remove unnecessary word from http_cache.rst (zatikbalazs) * `#5680 `_ fix grammar mistake (greg0ire) * `#5682 `_ Fix grammar and CS (iamdto) @@ -58,6 +62,9 @@ Minor Documentation Changes * `#5674 `_ Update cookbook entries with best practices (JhonnyL) * `#5675 `_ [Contributing] add a link to the testing section (xabbuh) * `#5669 `_ Better explanation of implicit exception response status code (hvt) +* `#5651 `_ [Reference][Constraints] follow best practices in the constraints reference (xabbuh) +* `#5648 `_ Minor fixes for the QuestionHelper documentation (javiereguiluz) +* `#5641 `_ Move important information out of versionadded (WouterJ) * `#5619 `_ Remove a caution note about StringUtils::equals() which is no longer true (javiereguiluz) * `#5571 `_ Some small fixes for upload files article (WouterJ) * `#5660 `_ Improved "Community Reviews" page (webmozart)