Merge branch '5.1' into 5.x

* 5.1:
  Update doctrine.rst
  Update multiple_kernels.rst
  Fixed DOCtor
  [Cache] Custom pool namespaces
  [#12802] Updated XML and PHP examples
  Security: How to Build a Login Form: sync with recent Maker Bundle changes
  Added PHP typehints to getting started guides
  Update deployment docs with new .env loading
  Update typehints
  Missing format parameter in a serialize call

Author: javiereguiluz

cache.rst

@@ -330,6 +330,53 @@ with either :class:`Symfony\\Contracts\\Cache\\CacheInterface` or
         // ...
     }
 
+.. tip::
+
+    If you need the namespace to be interoperable with a third-party app,
+    you can take control over auto-generation by setting the ``namespace``
+    attribute of the ``cache.pool`` service tag. For example, you can
+    override the service definition of the adapter:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/services.yaml
+            services:
+                app.cache.adapter.redis:
+                    parent: 'cache.adapter.redis'
+                    tags:
+                        - { name: 'cache.pool', namespace: 'my_custom_namespace' }
+
+        .. 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
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <services>
+                    <service id="app.cache.adapter.redis" parent="cache.adapter.redis">
+                        <tag name="cache.pool" namespace="my_custom_namespace"/>
+                    </service>
+                </services>
+            </container>
+
+        .. code-block:: php
+
+            // config/services.php
+            namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+            return function(ContainerConfigurator $configurator) {
+                $services = $configurator->services();
+
+                $services->set('app.cace.adapter.redis')
+                    ->parent('cache.adapter.redis')
+                    ->tag('cache.pool', ['namespace' => 'my_custom_namespace'])
+            };
+
 Custom Provider Options
 -----------------------
 

components/asset.rst

@@ -200,12 +200,12 @@ every day::
             $this->version = date('Ymd');
         }
 
-        public function getVersion($path)
+        public function getVersion(string $path)
         {
             return $this->version;
         }
 
-        public function applyVersion($path)
+        public function applyVersion(string $path)
         {
             return sprintf('%s?v=%s', $path, $this->getVersion($path));
         }

components/serializer.rst

@@ -681,7 +681,7 @@ defines a ``Person`` entity with a ``firstName`` property:
 This custom mapping is used to convert property names when serializing and
 deserializing objects::
 
-    $serialized = $serializer->serialize(new Person("Kévin"));
+    $serialized = $serializer->serialize(new Person("Kévin"), 'json');
     // {"customer_name": "Kévin"}
 
 Serializing Boolean Attributes
@@ -1537,7 +1537,7 @@ and ``BitBucketCodeRepository`` classes:
 
 Once configured, the serializer uses the mapping to pick the correct class::
 
-    $serialized = $serializer->serialize(new GitHubCodeRepository());
+    $serialized = $serializer->serialize(new GitHubCodeRepository(), 'json');
     // {"type": "github"}
 
     $repository = $serializer->deserialize($serialized, CodeRepository::class, 'json');

configuration.rst

@@ -753,12 +753,13 @@ use the ``getParameter()`` helper::
     namespace App\Controller;
 
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
 
     class UserController extends AbstractController
     {
         // ...
 
-        public function index()
+        public function index(): Response
         {
             $projectDir = $this->getParameter('kernel.project_dir');
             $adminEmail = $this->getParameter('app.admin_email');

configuration/env_var_processors.rst

@@ -631,7 +631,7 @@ create a class that implements
 
     class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
     {
-        public function getEnv($prefix, $name, \Closure $getEnv)
+        public function getEnv(string $prefix, string $name, \Closure $getEnv)
         {
             $env = $getEnv($name);
 

configuration/multiple_kernels.rst

@@ -88,31 +88,50 @@ files so they don't collide with the files from ``src/Kernel.php``::
 
     class ApiKernel extends Kernel
     {
-        // ...
+        use MicroKernelTrait;
 
         public function registerBundles()
         {
-            // load only the bundles strictly needed for the API...
+            // load only the bundles strictly needed for the API
+            $contents = require $this->getProjectDir().'/config/api_bundles.php';
+            foreach ($contents as $class => $envs) {
+                if ($envs[$this->environment] ?? $envs['all'] ?? false) {
+                    yield new $class();
+                }
+            }
+        }
+
+        public function getProjectDir(): string
+        {
+            return \dirname(__DIR__);
         }
 
-        public function getCacheDir()
+        public function getCacheDir(): string
         {
-            return dirname(__DIR__).'/var/cache/api/'.$this->getEnvironment();
+            return $this->getProjectDir().'/var/cache/api/'.$this->getEnvironment();
         }
 
-        public function getLogDir()
+        public function getLogDir(): string
         {
-            return dirname(__DIR__).'/var/log/api';
+            return $this->getProjectDir().'/var/log/api';
         }
 
         public function configureContainer(ContainerBuilder $container, LoaderInterface $loader)
         {
-            // load only the config files strictly needed for the API
-            $confDir = $this->getProjectDir().'/config';
-            $loader->load($confDir.'/api/*'.self::CONFIG_EXTS, 'glob');
-            if (is_dir($confDir.'/api/'.$this->environment)) {
-                $loader->load($confDir.'/api/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob');
-            }
+            $container->addResource(new FileResource($this->getProjectDir().'/config/api_bundles.php'));
+            $container->setParameter('container.dumper.inline_factories', true);
+            $confDir = $this->getProjectDir().'/config/api';
+
+            $loader->load($confDir.'/{packages}/*'.self::CONFIG_EXTS, 'glob');
+            $loader->load($confDir.'/{packages}/'.$this->environment.'/*'.self::CONFIG_EXTS, 'glob');
+            $loader->load($confDir.'/{services}'.self::CONFIG_EXTS, 'glob');
+            $loader->load($confDir.'/{services}_'.$this->environment.self::CONFIG_EXTS, 'glob');
+        }
+
+        protected function configureRoutes(RouteCollectionBuilder $routes): void
+        {
+            $confDir = $this->getProjectDir().'/config/api';
+            // ... load only the config routes strictly needed for the API
         }
     }
 

controller.rst

@@ -36,7 +36,7 @@ class::
         /**
          * @Route("/lucky/number/{max}", name="app_lucky_number")
          */
-        public function number($max)
+        public function number(int $max): Response
         {
             $number = random_int(0, $max);
 
@@ -134,7 +134,7 @@ and ``redirect()`` methods::
     use Symfony\Component\HttpFoundation\RedirectResponse;
 
     // ...
-    public function index()
+    public function index(): RedirectResponse
     {
         // redirects to the "homepage" route
         return $this->redirectToRoute('homepage');
@@ -196,12 +196,13 @@ If you need a service in a controller, type-hint an argument with its class
 (or interface) name. Symfony will automatically pass you the service you need::
 
     use Psr\Log\LoggerInterface;
+    use Symfony\Component\HttpFoundation\Response;
     // ...
 
     /**
      * @Route("/lucky/number/{max}")
      */
-    public function number($max, LoggerInterface $logger)
+    public function number(int $max, LoggerInterface $logger): Response
     {
         $logger->info('We are logging!');
         // ...
@@ -322,10 +323,11 @@ Managing Errors and 404 Pages
 When things are not found, you should return a 404 response. To do this, throw a
 special type of exception::
 
+    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 
     // ...
-    public function index()
+    public function index(): Response
     {
         // retrieve the object from database
         $product = ...;
@@ -370,8 +372,10 @@ object. To access it in your controller, add it as an argument and
 **type-hint it with the Request class**::
 
     use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
+    // ...
 
-    public function index(Request $request, $firstName, $lastName)
+    public function index(Request $request, string $firstName, string $lastName): Response
     {
         $page = $request->query->get('page', 1);
 
@@ -401,9 +405,11 @@ Session storage and other configuration can be controlled under the
 To get the session, add an argument and type-hint it with
 :class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface`::
 
+    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\HttpFoundation\Session\SessionInterface;
+    // ...
 
-    public function index(SessionInterface $session)
+    public function index(SessionInterface $session): Response
     {
         // stores an attribute for reuse during a later user request
         $session->set('foo', 'bar');
@@ -413,6 +419,8 @@ To get the session, add an argument and type-hint it with
 
         // uses a default value if the attribute doesn't exist
         $filters = $session->get('filters', []);
+
+        // ...
     }
 
 Stored attributes remain in the session for the remainder of that user's session.
@@ -435,8 +443,10 @@ from the session automatically as soon as you retrieve them. This feature makes
 For example, imagine you're processing a :doc:`form </forms>` submission::
 
     use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
+    // ...
 
-    public function update(Request $request)
+    public function update(Request $request): Response
     {
         // ...
 
@@ -515,8 +525,9 @@ pass the ``Request`` object to any controller argument that is type-hinted with
 the ``Request`` class::
 
     use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
 
-    public function index(Request $request)
+    public function index(Request $request): Response
     {
         $request->isXmlHttpRequest(); // is it an Ajax request?
 
@@ -572,7 +583,7 @@ To get the value of any :ref:`configuration parameter <configuration-parameters>
 from a controller, use the ``getParameter()`` helper method::
 
     // ...
-    public function index()
+    public function index(): Response
     {
         $contentsDir = $this->getParameter('kernel.project_dir').'/contents';
         // ...
@@ -584,8 +595,10 @@ Returning JSON Response
 To return JSON from a controller, use the ``json()`` helper method. This returns a
 ``JsonResponse`` object that encodes the data automatically::
 
+    use Symfony\Component\HttpFoundation\Response;
     // ...
-    public function index()
+
+    public function index(): Response
     {
         // returns '{"username":"jane.doe"}' and sets the proper Content-Type header
         return $this->json(['username' => 'jane.doe']);
@@ -604,7 +617,10 @@ Streaming File Responses
 You can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController::file`
 helper to serve a file from inside a controller::
 
-    public function download()
+    use Symfony\Component\HttpFoundation\Response;
+    // ...
+
+    public function download(): Response
     {
         // send the file contents and force the browser to download it
         return $this->file('/path/to/some_file.pdf');
@@ -614,8 +630,9 @@ The ``file()`` helper provides some arguments to configure its behavior::
 
     use Symfony\Component\HttpFoundation\File\File;
     use Symfony\Component\HttpFoundation\ResponseHeaderBag;
+    // ...
 
-    public function download()
+    public function download(): Response
     {
         // load the file from the filesystem
         $file = new File('/path/to/some_file.pdf');

deployment.rst

@@ -126,21 +126,29 @@ While developing locally, you'll usually store these in ``.env`` and ``.env.loca
 
 1. Create "real" environment variables. How you set environment variables, depends
    on your setup: they can be set at the command line, in your Nginx configuration,
-   or via other methods provided by your hosting service.
+   or via other methods provided by your hosting service;
 
-2. Or, create a ``.env.local`` file like your local development (see note below)
+2. Or, create a ``.env.local`` file like your local development.
 
 There is no significant advantage to either of the two options: use whatever is
 most natural in your hosting environment.
 
-.. note::
+.. tip::
+
+    You might not want your application to process the ``.env.*`` files on
+    every request. You can generate an optimized ``.env.local.php`` which
+    overrides all other configuration files:
+
+    .. code-block:: terminal
+
+        $ composer dump-env prod
 
-    If you use the ``.env.*`` files on production, you may need to move your
-    ``symfony/dotenv`` dependency from ``require-dev`` to ``require`` in ``composer.json``:
+    The generated file will contain all the configuration stored in ``.env``. If you
+    want to rely only on environment variables, generate one without any values using:
 
     .. code-block:: terminal
 
-        $ composer require symfony/dotenv
+        $ composer dump-env prod --empty
 
 C) Install/Update your Vendors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doctrine.rst

@@ -875,4 +875,4 @@ Learn more
 .. _`API Platform`: https://api-platform.com/docs/core/validation/
 .. _`PDO`: https://www.php.net/pdo
 .. _`available Doctrine extensions`: https://github.com/Atlantic18/DoctrineExtensions
-.. _`StofDoctrineExtensionsBundle`: https://github.com/antishov/StofDoctrineExtensionsBundle
+.. _`StofDoctrineExtensionsBundle`: https://github.com/stof/StofDoctrineExtensionsBundle

form/data_mappers.rst

@@ -98,7 +98,7 @@ in your form type::
         /**
          * @param Color|null $viewData
          */
-        public function mapDataToForms($viewData, $forms)
+        public function mapDataToForms($viewData, iterable $forms)
         {
             // there is no data yet, so nothing to prepopulate
             if (null === $viewData) {
@@ -119,7 +119,7 @@ in your form type::
             $forms['blue']->setData($viewData->getBlue());
         }
 
-        public function mapFormsToData($forms, &$viewData)
+        public function mapFormsToData(iterable $forms, &$viewData)
         {
             /** @var FormInterface[] $forms */
             $forms = iterator_to_array($forms);