diff --git a/book/forms.rst b/book/forms.rst index 7a296b6a308..e2767f72e56 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -1782,6 +1782,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\OptionsResolver; diff --git a/changelog.rst b/changelog.rst index 5a3d924e0af..96da734e60a 100644 --- a/changelog.rst +++ b/changelog.rst @@ -13,6 +13,63 @@ 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `#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) +* `#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) +* `#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) +* `#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) +* `#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) + + August, 2015 ------------ 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** diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 05343769443..47229033063 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. diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index 7974d3ac0fd..7606c44ac94 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -121,7 +121,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