Merge branch '4.1'

javiereguiluz · javiereguiluz · commit 3ade0c82f526 · 2018-07-05T08:55:51.000+02:00
* 4.1:
  Use AbstractController in the main controller article
  Minor rewords
  Fix broken link to `vue-loader` documentation.
  Simplify Apache config with FallbackResource
  Made the code of a validation example more robust
  Tell about controllers in doc about service subscribers
diff --git a/controller.rst b/controller.rst
@@ -86,14 +86,14 @@ For more information on routing, see :doc:`/routing`.
    single: Controller; Base controller class
 
 .. _the-base-controller-class-services:
+.. _the-base-controller-classes-services:
 
-The Base Controller Classes & Services
---------------------------------------
+The Base Controller Class & Services
+------------------------------------
 
-To make life nicer, Symfony comes with two optional base
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` and
+To make life nicer, Symfony comes with an optional base controller class called
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`.
-You can extend either to get access to some `helper methods`_.
+You can extend it to get access to some `helper methods`_.
 
 Add the ``use`` statement atop your controller class and then modify
 ``LuckyController`` to extend it:
@@ -103,35 +103,24 @@ Add the ``use`` statement atop your controller class and then modify
     // src/Controller/LuckyController.php
     namespace App\Controller;
 
-    + use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    + use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
     - class LuckyController
-    + class LuckyController extends Controller
+    + class LuckyController extends AbstractController
     {
         // ...
     }
 
 That's it! You now have access to methods like :ref:`$this->render() <controller-rendering-templates>`
 and many others that you'll learn about next.
 
-.. _controller-abstract-versus-controller:
-
-.. tip::
-
-    What's the difference between ``Controller`` or ``AbstractController``? Not much:
-    both are identical, except that ``AbstractController`` is more restrictive: it
-    does not allow you to access services directly via ``$this->get()`` or
-    ``$this->container->get()``. This forces you to write more robust code to access
-    services. But if you *do* need direct access to the container, using ``Controller``
-    is fine.
-
 .. index::
    single: Controller; Redirecting
 
 Generating URLs
 ~~~~~~~~~~~~~~~
 
-The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::generateUrl`
+The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerTrait::generateUrl`
 method is just a helper method that generates the URL for a given route::
 
     $url = $this->generateUrl('app_lucky_number', array('max' => 10));
@@ -650,7 +639,7 @@ contains the logic for that page. In Symfony, this is called a controller,
 and it's a PHP function where you can do anything in order to return the
 final ``Response`` object that will be returned to the user.
 
-To make life easier, you'll probably extend the base ``Controller`` class because
+To make life easier, you'll probably extend the base ``AbstractController`` class because
 this gives access to shortcut methods (like ``render()`` and ``redirectToRoute()``).
 
 In other articles, you'll learn how to use specific services from inside your controller
diff --git a/controller/service.rst b/controller/service.rst
@@ -81,9 +81,9 @@ without the method (``App\Controller\HelloController`` for example).
 Alternatives to base Controller Methods
 ---------------------------------------
 
-When using a controller defined as a service, you can still extend any of the
-:ref:`normal base controller <the-base-controller-class-services>` classes and
-use their shortcuts. But, you don't need to! You can choose to extend *nothing*,
+When using a controller defined as a service, you can still extend the
+:ref:`AbstractController base controller <the-base-controller-class-services>`
+and use its shortcuts. But, you don't need to! You can choose to extend *nothing*,
 and use dependency injection to access different services.
 
 The base `Controller class source code`_ is a great way to see how to accomplish
diff --git a/frontend/encore/vuejs.rst b/frontend/encore/vuejs.rst
@@ -27,7 +27,7 @@ also configure the `vue-loader options`_ via a callback:
 .. code-block:: javascript
 
     .enableVueLoader(function(options) {
-        // https://vue-loader.vuejs.org/en/configurations/advanced.html
+        // https://vue-loader.vuejs.org/options.html
 
         options.preLoaders = {
             js: '/path/to/custom/loader'
@@ -53,4 +53,4 @@ See :doc:`/frontend/encore/dev-server` for more details.
 
 .. _`babel-preset-react`: https://babeljs.io/docs/plugins/preset-react/
 .. _`Vue.js`: https://vuejs.org/
-.. _`vue-loader options`: https://vue-loader.vuejs.org/en/configurations/advanced.html
+.. _`vue-loader options`: https://vue-loader.vuejs.org/options.html
diff --git a/service_container/3.3-di-changes.rst b/service_container/3.3-di-changes.rst
@@ -326,7 +326,7 @@ The third big change is that, in a new Symfony 3.3 project, your controllers are
         $this->registerClasses($definition, 'App\\Controller\\', '../src/Controller/*');
 
 But, you might not even notice this. First, your controllers *can* still extend
-the same base ``Controller`` class or a new :ref:`AbstractController <controller-abstract-versus-controller>`.
+the same base controller class (``AbstractController``).
 This means you have access to all of the same shortcuts as before. Additionally,
 the ``@Route`` annotation and ``_controller`` syntax (e.g. ``App:Default:homepage``)
 used in routing will automatically use your controller as a service (as long as its
diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst
@@ -13,7 +13,9 @@ instantiation of the services to be lazy. However, that's not possible using
 the explicit dependency injection since services are not all meant to
 be ``lazy`` (see :doc:`/service_container/lazy_services`).
 
-A real-world example are applications that implement the `Command pattern`_
+This can typically be the case in your controllers, where you may inject several
+services in the constructor, but the action executed only uses some of them.
+Another example are applications that implement the `Command pattern`_
 using a CommandBus to map command handlers by Command class names and use them
 to handle their respective command when it is asked for::
 
@@ -50,35 +52,12 @@ to handle their respective command when it is asked for::
 
 Considering that only one command is handled at a time, instantiating all the
 other command handlers is unnecessary. A possible solution to lazy-load the
-handlers could be to inject the whole dependency injection container::
-
-    // ...
-    use Symfony\Component\DependencyInjection\ContainerInterface;
-
-    class CommandBus
-    {
-        private $container;
-
-        public function __construct(ContainerInterface $container)
-        {
-            $this->container = $container;
-        }
-
-        public function handle(Command $command)
-        {
-            $commandClass = get_class($command);
-
-            if ($this->container->has($commandClass)) {
-                $handler = $this->container->get($commandClass);
-
-                return $handler->handle($command);
-            }
-        }
-    }
+handlers could be to inject the main dependency injection container.
 
 However, injecting the entire container is discouraged because it gives too
 broad access to existing services and it hides the actual dependencies of the
-services.
+services. Doing so also requires services to be made public, which isn't the
+case by default in Symfony applications.
 
 **Service Subscribers** are intended to solve this problem by giving access to a
 set of predefined services while instantiating them only when actually needed
@@ -139,8 +118,7 @@ The injected service is an instance of :class:`Symfony\\Component\\DependencyInj
 which implements the PSR-11 ``ContainerInterface``, but it is also a callable::
 
     // ...
-    $locateHandler = $this->locator;
-    $handler = $locateHandler($commandClass);
+    $handler = ($this->locator)($commandClass);
 
     return $handler->handle($command);
 
@@ -173,6 +151,24 @@ Service types can also be keyed by a service name for internal use::
         ];
     }
 
+When extending a class that also implements ``ServiceSubscriberInterface``,
+it's your responsibility to call the parent when overriding the method. This
+typically happens when extending ``AbstractController``::
+
+    use Psr\Log\LoggerInterface;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+
+    class MyController extends AbstractController
+    {
+        public static function getSubscribedServices()
+        {
+            return array_merge(parent::getSubscribedServices(), [
+                // ...
+                'logger' => LoggerInterface::class,
+            ]);
+        }
+    }
+
 Optional Services
 ~~~~~~~~~~~~~~~~~
 
diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst
@@ -97,12 +97,7 @@ and increase web server performance:
             Order Allow,Deny
             Allow from All
 
-            <IfModule mod_rewrite.c>
-                Options -MultiViews
-                RewriteEngine On
-                RewriteCond %{REQUEST_FILENAME} !-f
-                RewriteRule ^(.*)$ index.php [QSA,L]
-            </IfModule>
+            FallbackResource /index.php
         </Directory>
 
         # uncomment the following lines if you install assets as symlinks
@@ -111,13 +106,11 @@ and increase web server performance:
         #     Options FollowSymlinks
         # </Directory>
 
-        # optionally disable the RewriteEngine for the asset directories
-        # which will allow apache to simply reply with a 404 when files are
-        # not found instead of passing the request into the full symfony stack
+        # optionally disable the fallback resource for the asset directories
+        # which will allow Apache to return a 404 error when files are
+        # not found instead of passing the request to Symfony
         <Directory /var/www/project/public/bundles>
-            <IfModule mod_rewrite.c>
-                RewriteEngine Off
-            </IfModule>
+            FallbackResource disabled
         </Directory>
         ErrorLog /var/log/apache2/project_error.log
         CustomLog /var/log/apache2/project_access.log combined
diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst
@@ -59,11 +59,22 @@ The validator class is also simple, and only has one required method ``validate(
 
     use Symfony\Component\Validator\Constraint;
     use Symfony\Component\Validator\ConstraintValidator;
+    use Symfony\Component\Validator\Exception\UnexpectedTypeException;
 
     class ContainsAlphanumericValidator extends ConstraintValidator
     {
         public function validate($value, Constraint $constraint)
         {
+            // custom constraints should ignore null and empty values to allow
+            // other constraints (NotBlank, NotNull, etc.) take care of that
+            if (null === $value || '' === $value) {
+                return;
+            }
+
+            if (!is_string($value)) {
+                throw new UnexpectedTypeException($value, 'string');
+            }
+
             if (!preg_match('/^[a-zA-Z0-9]+$/', $value, $matches)) {
                 $this->context->buildViolation($constraint->message)
                     ->setParameter('{{ string }}', $value)
