Merge branch '4.1'

* 4.1:
  Updated the command to run the Docker image
  [Doctrine Bridge] document priority for doctrine.event_listener tag
  Improved the docs of the instanceof config
  Add details on how the ClockMock::register works
  Add Dockerfile
  [Messenger] Register a handler for a specific bus
  Fix function name in expression
  [Routing] Fix path ressource
  Add missing semicolon in doc

Author: javiereguiluz

Dockerfile

@@ -0,0 +1,16 @@
+FROM  python:2-stretch as builder
+
+WORKDIR /www
+
+COPY ./_build/.requirements.txt _build/
+
+RUN pip install  pip==9.0.1 wheel==0.29.0 \
+    && pip install -r _build/.requirements.txt
+
+COPY . /www
+
+RUN make -C _build html
+
+FROM  nginx:latest
+
+COPY --from=builder /www/_build/html /usr/share/nginx/html

README.markdown

@@ -19,3 +19,17 @@ Platform.sh
 -----------
 
 Pull requests are automatically built by [Platform.sh](https://platform.sh).
+
+Docker
+------
+
+You can build the doc locally with these commands:
+
+```bash
+# build the image...
+$ docker build . -t symfony-docs
+
+# ...and serve it locally on http//:127.0.0.1:8080
+# (if it's already in use, change the '8080' port by any other port)
+$ docker run --rm -p 8080:80 symfony-docs
+```

components/phpunit_bridge.rst

@@ -352,6 +352,48 @@ test::
 
 And that's all!
 
+.. caution::
+
+    Time-based function mocking follows the `PHP namespace resolutions rules`_
+    so "fully qualified function calls" (e.g ``\time()``) cannot be mocked.
+
+The ``@group time-sensitive`` annotation is equivalent to calling
+``ClockMock::register(MyTest::class)``. If you want to mock a function used in a
+different class, do it explicitly using ``ClockMock::register(MyClass::class)``::
+
+    // the class that uses the time() function to be mocked
+    namespace App;
+
+    class MyClass
+    {
+        public function getTimeInHours()
+        {
+            return time() / 3600;
+        }
+    }
+
+    // the test that mocks the external time() function explicitly
+    namespace App\Tests;
+
+    use App\MyClass;
+    use PHPUnit\Framework\TestCase;
+
+    /**
+     * @group time-sensitive
+     */
+    class MyTest extends TestCase
+    {
+        public function testGetTimeInHours()
+        {
+            ClockMock::register(MyClass::class);
+
+            $my = new MyClass();
+            $result = $my->getTimeInHours();
+
+            $this->assertEquals(time() / 3600, $result);
+        }
+    }
+
 .. tip::
 
     An added bonus of using the ``ClockMock`` class is that time passes
@@ -633,3 +675,4 @@ not find the SUT:
 .. _`Travis CI`: https://travis-ci.org/
 .. _`test listener`: https://phpunit.de/manual/current/en/appendixes.configuration.html#appendixes.configuration.test-listeners
 .. _`@covers`: https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.covers
+.. _`PHP namespace resolutions rules`: https://php.net/manual/en/language.namespaces.rules.php

doctrine/event_listeners_subscribers.rst

@@ -204,3 +204,57 @@ whenever possible.
 
 .. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
 .. _`the Doctrine Documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html
+
+Priorities for Event Listeners
+------------------------------
+
+In case you have multiple listeners for the same event you can control the order
+in which they are invoked using the ``priority`` attribute on the tag.
+Listeners with a higher priority are invoked first.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\EventListener\MyHighPriorityListener:
+                tags:
+                    - { name: doctrine.event_listener, event: postPersist, priority: 10 }
+
+            App\EventListener\MyLowPriorityListener:
+                tags:
+                    - { name: doctrine.event_listener, event: postPersist, priority: 1 }
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
+
+            <services>
+                <service id="App\EventListener\MyHighPriorityListener" autowire="true">
+                    <tag name="doctrine.event_listener" event="postPersist" priority="10" />
+                </service>
+                <service id="App\EventListener\MyLowPriorityListener" autowire="true">
+                    <tag name="doctrine.event_listener" event="postPersist" priority="1" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use AppBundle\EventListener\MyHighPriorityListener;
+        use AppBundle\EventListener\MyLowPriorityListener;
+
+        $container
+            ->autowire(MyHighPriorityListener::class)
+            ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'priority' => 10))
+        ;
+
+        $container
+            ->autowire(MyLowPriorityListener::class)
+            ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'priority' => 1))
+        ;

messenger.rst

@@ -449,6 +449,12 @@ this:
 This will generate the ``messenger.bus.commands`` and ``messenger.bus.events`` services
 that you can inject in your services.
 
+.. note::
+
+    To register a handler only for a specific bus, add a ``bus`` attribute to
+    the handler's service tag (``messenger.message_handler``) and use the bus
+    name as its value.
+
 Type-hints and Auto-wiring
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

routing.rst

@@ -234,7 +234,7 @@ with a locale. This can be done by defining a different prefix for each locale
 
         # config/routes/annotations.yaml
         controllers:
-            resource: '../src/Controller/'
+            resource: '../../src/Controller/'
             type: annotation
             prefix:
                 en: '' # don't prefix URLs for English, the default locale

security.rst

@@ -869,7 +869,7 @@ You can easily deny access from inside a controller::
     :ref:`base controller provided by Symfony <the-base-controller-class-services>`.
     It's equivalent to the following code::
 
-        use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface
+        use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
         use Symfony\Component\Security\Core\Exception\AccessDeniedException;
         // ...
 

security/expressions.rst

@@ -69,7 +69,7 @@ Additionally, you have access to a number of functions inside the expression:
 
 .. sidebar:: ``is_remember_me`` is different than checking ``IS_AUTHENTICATED_REMEMBERED``
 
-    The ``is_remember_me()`` and ``is_authenticated_fully()`` functions are *similar*
+    The ``is_remember_me()`` and ``is_fully_authenticated()`` functions are *similar*
     to using ``IS_AUTHENTICATED_REMEMBERED`` and ``IS_AUTHENTICATED_FULLY``
     with the ``isGranted()`` function - but they are **not** the same. The
     following controller snippet shows the difference::

service_container/tags.rst

@@ -63,24 +63,63 @@ automatically applied for you. That's true for the ``twig.extension`` tag: the
 container sees that your class extends ``AbstractExtension`` (or more accurately,
 that it implements ``ExtensionInterface``) and adds the tag for you.
 
-.. tip::
+If you want to apply tags automatically for your own services, use the
+``_instanceof`` option::
 
-    To apply a tag to all your autoconfigured services extending a class or implementing an
-    interface, call the :method:`Symfony\\Component\\DependencyInjection\\ContainerBuilder::registerForAutoconfiguration`
-    method in an :doc:`extension </bundles/extension>` or from your kernel::
+.. configuration-block::
 
-        // src/Kernel.php
-        class Kernel extends Kernel
-        {
-            // ...
+    .. code-block:: yaml
 
-            protected function build(ContainerBuilder $container)
-            {
-                $container->registerForAutoconfiguration(CustomInterface::class)
-                    ->addTag('app.custom_tag')
-                ;
-            }
+        # config/services.yaml
+        services:
+            # this config only applies to the services created by this file
+            _instanceof:
+                # services whose classes are instances of CustomInterface will be tagged automatically
+                App\Security\CustomInterface:
+                    tags: ['app.custom_tag']
+            # ...
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="utf-8"?>
+        <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            <services>
+                <!-- this config only applies to the services created by this file -->
+                <instanceof id="App\Security\CustomInterface" autowire="true">
+                    <!-- services whose classes are instances of CustomInterface will be tagged automatically -->
+                    <tag name="app.custom_tag" />
+                </instanceof>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\Security\CustomInterface;
+        // ...
+
+        // services whose classes are instances of CustomInterface will be tagged automatically
+        $container->registerForAutoconfiguration(CustomInterface::class)
+            ->addTag('app.custom_tag')
+            ->setAutowired(true);
+
+For more advanced needs, you can define the automatic tags using the
+:method:`Symfony\\Component\\DependencyInjection\\ContainerBuilder::registerForAutoconfiguration`
+method in an :doc:`extension </bundles/extension>` or from your kernel::
+
+    // src/Kernel.php
+    class Kernel extends BaseKernel
+    {
+        // ...
+
+        protected function build(ContainerBuilder $container)
+        {
+            $container->registerForAutoconfiguration(CustomInterface::class)
+                ->addTag('app.custom_tag')
+            ;
         }
+    }
 
 Creating custom Tags
 --------------------