Merge branch '4.0'

* 4.0:
  Added minor clarification about what StudlyCaps is
  Update best_practices.rst
  add missing twig dump construct
  Removed the reference to specific Symfony files
  [Workflow] fix event name for completed event
  do not render the description as a blockquote
  Stop to recommend FOSUser for Symfony 4
  Mention the official Twig extensions
  Added a new section "Extracting Translation Contents and Updating Cat…
  add filter argument to assertDumpEquals()
  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

@@ -26,7 +26,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

@@ -322,6 +322,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
 ----------------------

components/var_dumper/advanced.rst

@@ -196,9 +196,13 @@ The output format of a dumper can be fine tuned by the two flags
 ``DUMP_STRING_LENGTH`` and ``DUMP_LIGHT_ARRAY`` which are passed as a bitmap
 in the third constructor argument. They can also be set via environment
 variables when using
-:method:`assertDumpEquals($dump, $data, $message) <Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpEquals>`
+:method:`assertDumpEquals($dump, $data, $filter, $message) <Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpEquals>`
 during unit testing.
 
+The ``$filter`` argument of ``assertDumpEquals()`` can be used to pass a
+bit field of ``Caster::EXCLUDE_*`` constants and influences the expected
+output produced by the different casters.
+
 If ``DUMP_STRING_LENGTH`` is set, then the length of a string is displayed
 next to its content:
 

security/entity_provider.rst

@@ -12,15 +12,6 @@ you how to load your users from the database via a Doctrine entity.
 Introduction
 ------------
 
-.. tip::
-
-    Before you start, you should check out `FOSUserBundle`_. This external
-    bundle allows you to load users from the database (like you'll learn here)
-    *and* gives you built-in routes & controllers for things like login,
-    registration and forgot password. But, if you need to heavily customize
-    your user system *or* if you want to learn how things work, this tutorial
-    is even better.
-
 Loading users via a Doctrine entity has 2 basic steps:
 
 #. :ref:`Create your User entity <security-crete-user-entity>`

templating/debug.rst

@@ -39,14 +39,25 @@ This is useful, 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
 
     {# templates/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>

templating/twig_extension.rst

@@ -8,6 +8,17 @@ If you need to create custom Twig functions, filters, tests or more, you'll need
 to create a Twig extension. You can read more about `Twig Extensions`_ in the Twig
 documentation.
 
+.. tip::
+
+    Before writing your own Twig extension, check if the filter/function that
+    you need is already implemented in the :doc:`Symfony Twig extensions </reference/twig_reference>`.
+    Check also the `official Twig extensions`_, which can be installed in your
+    application as follows:
+
+    .. code-block:: terminal
+
+        $ composer require twig/extensions
+
 Create the Extension Class
 --------------------------
 
@@ -62,6 +73,7 @@ you're done! Symfony will automatically know about your new service and add the
 
 You can now start using your filter in any Twig template.
 
+.. _`official Twig extensions`: https://github.com/twigphp/Twig-extensions
 .. _`Twig extensions documentation`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
 .. _`global variables`: http://twig.sensiolabs.org/doc/advanced.html#id1
 .. _`functions`: http://twig.sensiolabs.org/doc/advanced.html#id2