Merge branch '3.3' into 3.4

* 3.3:
  Updated the console binary path
  Added minor clarification about what StudlyCaps is
  Update best_practices.rst
  add missing twig dump construct
  Removed the reference to specific Symfony files
  do not render the description as a blockquote
  Added a new section "Extracting Translation Contents and Updating Cat…
  Moved the note before the label
  PathPackage and asset with absolute path
  Path package in context aware
  moved the tips to an include fragment file
  added a tip to register annotations namespaces

Author: javiereguiluz

_includes/_annotation_loader_tip.rst.inc

@@ -0,0 +1,19 @@
+.. note::
+
+    In order to use the annotation loader, you should have installed the
+    ``doctrine/annotations`` and ``doctrine/cache`` packages with Composer.
+
+.. tip::
+
+    Annotation classes aren't loaded automatically, so you must load them
+    using a class loader like this::
+
+        use Composer\Autoload\ClassLoader;
+        use Doctrine\Common\Annotations\AnnotationRegistry;
+
+        /** @var ClassLoader $loader */
+        $loader = require __DIR__.'/../vendor/autoload.php';
+
+        AnnotationRegistry::registerLoader([$loader, 'loadClass']);
+
+        return $loader;

bundles/best_practices.rst

@@ -37,7 +37,7 @@ A namespace becomes a bundle as soon as you add a bundle class to it. The
 bundle class name must follow these simple rules:
 
 * Use only alphanumeric characters and underscores;
-* Use a CamelCased name;
+* Use a StudlyCaps name (i.e. camelCase with the first letter uppercased);
 * Use a descriptive and short name (no more than two words);
 * Prefix the name with the concatenation of the vendor (and optionally the
   category namespaces);

components/asset.rst

@@ -204,9 +204,13 @@ class can take into account the context of the current request::
         new StaticVersionStrategy('v1'),
         new RequestStackContext($requestStack)
     );
-
-    echo $package->getUrl('/logo.png');
+    
+    echo $package->getUrl('logo.png');
     // result: /somewhere/static/images/logo.png?v1
+    
+    // Both "base path" and "base url" are ignored when using absolute path for asset
+    echo $package->getUrl('/logo.png');
+    // result: /logo.png?v1
 
 Now that the request context is set, the ``PathPackage`` will prepend the
 current request base URL. So, for example, if your entire site is hosted under
@@ -335,7 +339,7 @@ document inside a template::
     echo $packages->getUrl('/logo.png', 'img');
     // result: http://img.example.com/logo.png?v1
 
-    echo $packages->getUrl('/resume.pdf', 'doc');
+    echo $packages->getUrl('resume.pdf', 'doc');
     // result: /somewhere/deep/for/documents/resume.pdf?v1
 
 Learn more

components/routing.rst

@@ -312,6 +312,8 @@ Last but not least there are
 route definitions from class annotations. The specific details are left
 out here.
 
+.. include:: /_includes/_rewrite_rule_tip.rst.inc
+
 The all-in-one Router
 ~~~~~~~~~~~~~~~~~~~~~
 

components/serializer.rst

@@ -326,6 +326,8 @@ You are now able to serialize only attributes in the groups you want::
     );
     // $obj2 = MyObj(foo: 'foo', bar: 'bar')
 
+.. include:: /_includes/_rewrite_rule_tip.rst.inc
+
 .. _ignoring-attributes-when-serializing:
 
 Selecting Specific Attributes

components/validator/resources.rst

@@ -119,10 +119,7 @@ method. It takes an optional annotation reader instance, which defaults to
 To disable the annotation loader after it was enabled, call
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
 
-.. note::
-
-    In order to use the annotation loader, you should have installed the
-    ``doctrine/annotations`` and ``doctrine/cache`` packages from `Packagist`_.
+.. include:: /_includes/_rewrite_rule_tip.rst.inc
 
 Using Multiple Loaders
 ----------------------

templating/debug.rst

@@ -33,14 +33,25 @@ for example, inside your controller::
     The output of the ``dump()`` function is then rendered in the web developer
     toolbar.
 
-The same mechanism can be used in Twig templates thanks to ``dump()`` function:
+In a Twig template, you can use the ``dump`` utility as a function or a tag:
+
+* ``{% dump foo.bar %}`` is the way to go when the original template output
+  shall not be modified: variables are not dumped inline, but in the web
+  debug toolbar;
+* on the contrary, ``{{ dump(foo.bar) }}`` dumps inline and thus may or not
+  be suited to your use case (e.g. you shouldn't use it in an HTML
+  attribute or a ``<script>`` tag).
 
 .. code-block:: html+twig
 
     {# app/Resources/views/article/recent_list.html.twig #}
-    {{ dump(articles) }}
+    {# the contents of this variable are sent to the Web Debug Toolbar #}
+    {% dump articles %}
 
     {% for article in articles %}
+        {# the contents of this variable are display on the web page #}
+        {{ dump(article) }}
+
         <a href="/article/{{ article.slug }}">
             {{ article.title }}
         </a>

translation.rst

@@ -107,13 +107,12 @@ of text (called a *message*), use the
 for example, that you're translating a simple message from inside a controller::
 
     // ...
-    use Symfony\Component\HttpFoundation\Response;
 
     public function indexAction()
     {
         $translated = $this->get('translator')->trans('Symfony is great');
 
-        return new Response($translated);
+        // ...
     }
 
 .. _translation-resources:
@@ -185,13 +184,11 @@ Message Placeholders
 
 Sometimes, a message containing a variable needs to be translated::
 
-    use Symfony\Component\HttpFoundation\Response;
-
     public function indexAction($name)
     {
         $translated = $this->get('translator')->trans('Hello '.$name);
 
-        return new Response($translated);
+        // ...
     }
 
 However, creating a translation for this string is impossible since the translator
@@ -258,11 +255,11 @@ You can also specify the message domain and pass some additional variables:
 
 .. code-block:: twig
 
-    {% trans with {'%name%': 'Fabien'} from "app" %}Hello %name%{% endtrans %}
+    {% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
 
-    {% trans with {'%name%': 'Fabien'} from "app" into "fr" %}Hello %name%{% endtrans %}
+    {% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
 
-    {% transchoice count with {'%name%': 'Fabien'} from "app" %}
+    {% transchoice count with {'%name%': 'Fabien'} from 'app' %}
         {0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
     {% endtranschoice %}
 
@@ -277,7 +274,7 @@ texts* and complex expressions:
 
     {{ message|transchoice(5) }}
 
-    {{ message|trans({'%name%': 'Fabien'}, "app") }}
+    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
 
     {{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
 
@@ -308,7 +305,7 @@ texts* and complex expressions:
 
     .. code-block:: twig
 
-           {% trans_default_domain "app" %}
+           {% trans_default_domain 'app' %}
 
     Note that this only influences the current template, not any "included"
     template (in order to avoid side effects).
@@ -329,6 +326,33 @@ The translator service is accessible in PHP templates through the
         array('%count%' => 10)
     ) ?>
 
+Extracting Translation Contents and Updating Catalogs Automatically
+-------------------------------------------------------------------
+
+The most time-consuming tasks when translating an application is to extract all
+the template contents to be translated and to keep all the translation files in
+sync. Symfony includes a command called ``translation:update`` that helps you
+with these tasks:
+
+.. code-block:: terminal
+
+    # updates the French translation file with the missing strings found in app/Resources/ templates
+    $ ./bin/console translation:update --dump-messages --force fr
+
+    # updates the English translation file with the missing strings found in AppBundle
+    $ ./bin/console translation:update --dump-messages --force en AppBundle
+
+.. note::
+
+    If you want to see the missing translation strings without actually updating
+    the translation files, remove the ``--force`` option from the command above.
+
+.. tip::
+
+    If you need to extract translation strings from other sources, such as
+    controllers, forms and flash messages, consider using the more advanced
+    third-party `TranslationBundle`_.
+
 .. _translation-resource-locations:
 
 Translation Resource/File Names and Locations
@@ -513,3 +537,4 @@ Learn more
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`Translatable Extension`: http://atlantic18.github.io/DoctrineExtensions/doc/translatable.html
 .. _`Translatable Behavior`: https://github.com/KnpLabs/DoctrineBehaviors
+.. _`TranslationBundle`: https://github.com/php-translation/symfony-bundle

workflow/usage.rst

@@ -231,7 +231,6 @@ order:
     * ``workflow.[workflow name].enter.[place name]``
 
 ``workflow.entered``
-
     Similar to ``workflow.enter``, except the marking store is updated before this
     event (making it a good place to flush data in Doctrine).