symfony · clemens-tolboom · Nov 2, 2013 · Dec 8, 2013 · Dec 12, 2013 · Dec 17, 2013
diff --git a/book/forms.rst b/book/forms.rst
@@ -709,8 +709,8 @@ the correct values of a number of field options.
   (i.e. is the field ``nullable``). This is very useful, as your client-side
   validation will automatically match your validation rules.
 
-* ``max_length``: If the field is some sort of text field, then the ``max_length``
-  option can be guessed from the validation constraints (if ``Length`` or
+* ``maxlength``: If the field is some sort of text field, then the ``maxlength``
+  option attribute can be guessed from the validation constraints (if ``Length`` or
   ``Range`` is used) or from the Doctrine metadata (via the field's length).
 
 .. note::
@@ -721,7 +721,7 @@ the correct values of a number of field options.
 If you'd like to change one of the guessed values, you can override it by
 passing the option in the options field array::
 
-    ->add('task', null, array('max_length' => 4))
+    ->add('task', null, array('attr' => array('maxlength' => 4)))
 
 .. index::
    single: Forms; Rendering in a template
@@ -1899,7 +1899,7 @@ Learn more from the Cookbook
 
 .. _`Symfony2 Form component`: https://github.com/symfony/Form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php
-.. _`Twig Bridge`: https://github.com/symfony/symfony/tree/2.3/src/Symfony/Bridge/Twig
-.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/2.3/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+.. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig
+.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
 .. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery
-.. _`view on GitHub`: https://github.com/symfony/symfony/tree/2.3/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form
+.. _`view on GitHub`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form
diff --git a/book/installation.rst b/book/installation.rst
@@ -57,7 +57,7 @@ Distribution:
 
 .. code-block:: bash
 
-    $ php composer.phar create-project symfony/framework-standard-edition /path/to/webroot/Symfony 2.4.*
+    $ php composer.phar create-project symfony/framework-standard-edition /path/to/webroot/Symfony dev-master
 
 .. tip::
 

diff --git a/book/routing.rst b/book/routing.rst
@@ -68,10 +68,6 @@ The route is simple:
 
         return $collection;
 
-.. versionadded:: 2.2
-    The ``path`` option was introduced in Symfony 2.2, ``pattern`` is used
-    in older versions.
-
 The path defined by the ``blog_show`` route acts like ``/blog/*`` where
 the wildcard is given the name ``slug``. For the URL ``/blog/my-blog-post``,
 the ``slug`` variable gets a value of ``my-blog-post``, which is available
@@ -706,10 +702,6 @@ be accomplished with the following route configuration:
 
         return $collection;
 
-.. versionadded:: 2.2
-    The ``methods`` option was introduced in Symfony 2.2. Use the ``_method``
-    requirement in older versions.
-
 Despite the fact that these two routes have identical paths (``/contact``),
 the first route will match only GET requests and the second route will match
 only POST requests. This means that you can display the form and submit the
@@ -722,9 +714,6 @@ form via the same URL, while using distinct controllers for the two actions.
 Adding a Host Requirement
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 2.2
-    Host matching support was introduced in Symfony 2.2
-
 You can also match on the HTTP *host* of the incoming request. For more
 information, see :doc:`/components/routing/hostname_pattern` in the Routing
 component documentation.
@@ -1166,9 +1155,6 @@ from the new routing resource.
 Adding a Host Requirement to Imported Routes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 2.2
-    Host matching support was introduced in Symfony 2.2
-
 You can set the host regex on imported routes. For more information, see
 :ref:`component-routing-host-imported`.
 

diff --git a/book/security.rst b/book/security.rst
@@ -183,8 +183,9 @@ can access ``/foo`` without being prompted to authenticate.
 
 .. tip::
 
-    You can also match a request against other details of the request (e.g. host).
-    For more information and examples read :doc:`/cookbook/security/firewall_restriction`.
+    You can also match a request against other details of the request (e.g.
+    host, method). For more information and examples read
+    :doc:`/cookbook/security/firewall_restriction`.
 
 .. image:: /images/book/security_anonymous_user_access.png
    :align: center
@@ -1088,19 +1089,25 @@ fine-grained enough in certain cases. When necessary, you can easily force
 authorization from inside a controller::
 
     // ...
-    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 
     public function helloAction($name)
     {
         if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
-            throw new AccessDeniedException();
+            throw $this->createAccessDeniedException('Unable to access this page!');
         }
 
         // ...
     }
 
 .. _book-security-securing-controller-annotations:
 
+.. versionadded:: 2.5
+    The ``createAccessDeniedException`` method was introduced in Symfony 2.5.
+
+The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAccessDeniedException`
+method creates a special :class:`Symfony\\Component\\Security\\Core\Exception\\AccessDeniedException`
+object, which ultimately triggers a 403 HTTP response inside Symfony.
+
 Thanks to the SensioFrameworkExtraBundle, you can also secure your controller using annotations::
 
     // ...
@@ -1444,9 +1451,10 @@ or via some online tool.
 Supported algorithms for this method depend on your PHP version. A full list
 is available by calling the PHP function :phpfunction:`hash_algos`.
 
-.. versionadded:: 2.2
-    As of Symfony 2.2 you can also use the :ref:`PBKDF2 <reference-security-pbkdf2>`
-    password encoder.
+.. tip::
+
+    It's also possible to use different hashing algorithms on a user-by-user
+    basis. See :doc:`/cookbook/security/named_encoders` for more details.
 
 Determining the Hashed Password
 ...............................
@@ -2065,10 +2073,6 @@ cookie will be ever created by Symfony2):
 Utilities
 ---------
 
-.. versionadded:: 2.2
-    The ``StringUtils`` and ``SecureRandom`` classes were introduced in Symfony
-    2.2
-
 The Symfony Security component comes with a collection of nice utilities related
 to security. These utilities are used by Symfony, but you should also use
 them if you want to solve the problem they address.

diff --git a/book/templating.rst b/book/templating.rst
@@ -373,11 +373,6 @@ When working with template inheritance, here are some tips to keep in mind:
 Template Naming and Locations
 -----------------------------
 
-.. versionadded:: 2.2
-    Namespaced path support was introduced in 2.2, allowing for template names
-    like ``@AcmeDemo/layout.html.twig``. See :doc:`/cookbook/templating/namespaced_paths`
-    for more details.
-
 By default, templates can live in two different locations:
 
 * ``app/Resources/views/``: The applications ``views`` directory can contain
@@ -570,10 +565,6 @@ you set `with_context`_ to false).
     maps (i.e. an array with named keys). If you needed to pass in multiple
     elements, it would look like this: ``{'foo': foo, 'bar': bar}``.
 
-.. versionadded:: 2.2
-    The `include() function`_ is a new Twig feature that's available in Symfony
-    2.2. Prior, the `{% include %} tag`_ tag was used.
-
 .. index::
    single: Templating; Embedding action
 
@@ -780,9 +771,6 @@ in your application configuration:
             ),
         ));
 
-.. versionadded:: 2.2
-    Default templates per render function was introduced in Symfony 2.2
-
 You can define default templates per ``render`` function (which will override
 any global default template that is defined):
 
@@ -1001,6 +989,44 @@ assets won't be cached when deployed. For example, ``/images/logo.png`` might
 look like ``/images/logo.png?v2``. For more information, see the :ref:`ref-framework-assets-version`
 configuration option.
 
+.. _`book-templating-version-by-asset`:
+
+.. versionadded:: 2.5
+    Setting versioned URLs on an asset-by-asset basis was introduced in Symfony 2.5.
+
+If you need to set a version for a specific asset, you can set the fourth
+argument (or the ``version`` argument) to the desired version:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        <img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
+
+    .. code-block:: html+php
+
+        <img src="<?php echo $view['assets']->getUrl('images/logo.png', null, false, '3.0') ?>" alt="Symfony!" />
+
+If you dont give a version or pass ``null``, the default package version
+(from :ref:`ref-framework-assets-version`) will be used. If you pass ``false``,
+versioned URL will be deactivated for this asset.
+
+.. versionadded:: 2.5
+    Absolute URLs for assets were introduced in Symfony 2.5.
+
+If you need absolute URLs for assets, you can set the third argument (or the
+``absolute`` argument) to ``true``:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        <img src="{{ asset('images/logo.png', absolute=true) }}" alt="Symfony!" />
+
+    .. code-block:: html+php
+
+        <img src="<?php echo $view['assets']->getUrl('images/logo.png', null, true) ?>" alt="Symfony!" />
+
 .. index::
    single: Templating; Including stylesheets and JavaScripts
    single: Stylesheets; Including stylesheets

diff --git a/book/translation.rst b/book/translation.rst
@@ -649,6 +649,173 @@ The translation of database content should be handled by Doctrine through
 the `Translatable Extension`_ or the `Translatable Behavior`_ (PHP 5.4+).
 For more information, see the documentation for thes libraries.
 
+Debugging Translations
+----------------------
+
+.. versionadded:: 2.5
+    The ``translation:debug`` command was introduced in Symfony 2.5.
+
+When maintaining a bundle, you may use or remove the usage of a translation
+message without updating all message catalogues. The ``translation:debug``
+command helps you to find these missing or unused translation messages for a
+given locale. It shows you a table with the result when translating the
+message in the given locale and the result when the fallback would be used.
+On top of that, it also shows you when the translation is the same as the
+fallback translation (this could indicate that the message was not correctly
+translated).
+
+Thanks to the messages extractors, the command will detect the translation
+tag or filter usages in Twig templates:
+
+.. code-block:: jinja
+
+    {% trans %}Symfony2 is great{% endtrans %}
+
+    {{ 'Symfony2 is great'|trans }}
+
+    {{ 'Symfony2 is great'|transchoice(1) }}
+
+    {% transchoice 1 %}Symfony2 is great{% endtranschoice %}
+
+It will also detect the following translator usages in PHP templates:
+
+.. code-block:: php
+
+    $view['translator']->trans("Symfony2 is great");
+
+    $view['translator']->trans('Symfony2 is great');
+
+.. caution::
+
+    The extractors are not able to inspect the messages translated outside templates which means
+    that translator usages in form labels or inside your controllers won't be detected.
+    Dynamic translations involving variables or expressions are not detected in templates,
+    which means this example won't be analyzed:
+
+    .. code-block:: jinja
+
+        {% set message = 'Symfony2 is great' %}
+        {{ message|trans }}
+
+Suppose your application's default_locale is ``fr`` and you have configured ``en`` as the fallback locale
+(see :ref:`book-translation-configuration` and :ref:`book-translation-fallback` for how to configure these).
+And suppose you've already setup some translations for the ``fr`` locale inside an AcmeDemoBundle:
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.xliff -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="1">
+                        <source>Symfony2 is great</source>
+                        <target>J'aime Symfony2</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.php
+        return array(
+            'Symfony2 is great' => 'J\'aime Symfony2',
+        );
+
+    .. code-block:: yaml
+
+        # src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.yml
+        Symfony2 is great: J'aime Symfony2
+
+and for the ``en`` locale:
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- src/Acme/AcmeDemoBundle/Resources/translations/messages.en.xliff -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="1">
+                        <source>Symfony2 is great</source>
+                        <target>Symfony2 is great</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // src/Acme/AcmeDemoBundle/Resources/translations/messages.en.php
+        return array(
+            'Symfony2 is great' => 'Symfony2 is great',
+        );
+
+    .. code-block:: yaml
+
+        # src/Acme/AcmeDemoBundle/Resources/translations/messages.en.yml
+        Symfony2 is great: Symfony2 is great
+
+To inspect all messages in the ``fr`` locale for the AcmeDemoBundle, run:
+
+.. code-block:: bash
+
+    $ php app/console translation:debug fr AcmeDemoBundle
+
+You will get this output:
+
+.. image:: /images/book/translation/debug_1.png
+    :align: center
+
+It indicates that the message ``Symfony2 is great`` is unused because it is translated,
+but you haven't used it anywhere yet.
+
+Now, if you translate the message in one of your templates, you will get this output:
+
+.. image:: /images/book/translation/debug_2.png
+    :align: center
+
+The state is empty which means the message is translated in the ``fr`` locale and used in one or more templates.
+
+If you delete the message ``Symfony2 is great`` from your translation file for the ``fr`` locale
+and run the command, you will get:
+
+.. image:: /images/book/translation/debug_3.png
+    :align: center
+
+The state indicates the message is missing because it is not translated in the ``fr`` locale
+but it is still used in the template.
+Moreover, the message in the ``fr`` locale equals to the message in the ``en`` locale.
+This is a special case because the untranslated message id equals its translation in the ``en`` locale.
+
+If you copy the content of the translation file in the ``en`` locale, to the translation file
+in the ``fr`` locale and run the command, you will get:
+
+.. image:: /images/book/translation/debug_4.png
+    :align: center
+
+You can see that the translations of the message are identical in the ``fr`` and ``en`` locales
+which means this message was probably copied from French to English and maybe you forgot to translate it.
+
+By default all domains are inspected, but it is possible to specify a single domain:
+
+.. code-block:: bash
+
+    $ php app/console translation:debug en AcmeDemoBundle --domain=messages
+
+When bundles have a lot of messages, it is useful to display only the unused
+or only the missing messages, by using the ``--only-unused`` or ``--only-missing`` switches:
+
+.. code-block:: bash
+
+    $ php app/console translation:debug en AcmeDemoBundle --only-unused
+    $ php app/console translation:debug en AcmeDemoBundle --only-missing
+
 Summary
 -------