Merge branch '4.1'

* 4.1:
  Updated the Symfony Flex server
  Updated some config for Symfony 4 practices
  Documented the findByCodes() validation method
  Fixed the type of the twig.cache config option
  Update the argument value resolver article
  Documented the catchExceptions() method
  Documented the enableExceptionOnInvalidIndex() method
  Added the missing attr option in TextType

Author: javiereguiluz

components/property_access.rst

@@ -47,7 +47,23 @@ method. This is done using the index notation that is used in PHP::
     var_dump($propertyAccessor->getValue($person, '[first_name]')); // 'Wouter'
     var_dump($propertyAccessor->getValue($person, '[age]')); // null
 
-As you can see, the method will return ``null`` if the index does not exists.
+As you can see, the method will return ``null`` if the index does not exist.
+But you can change this behavior with the
+:method:`Symfony\\Component\\PropertyAccess\\PropertyAccessorBuilder::enableExceptionOnInvalidIndex`
+method::
+
+    // ...
+    $propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
+        ->enableExceptionOnInvalidIndex()
+        ->getPropertyAccessor();
+
+    $person = array(
+        'first_name' => 'Wouter',
+    );
+
+    // instead of returning null, the code now throws an exception of type
+    // Symfony\Component\PropertyAccess\Exception\NoSuchIndexException
+    $value = $propertyAccessor->getValue($person, '[age]');
 
 You can also use multi dimensional arrays::
 

components/validator.rst

@@ -53,7 +53,19 @@ characters long::
         }
     }
 
-The validator returns the list of violations.
+The  ``validate()`` method returns the list of violations as an object that
+implements :class:`Symfony\\Component\\Validator\\ConstraintViolationListInterface`.
+If you have lots of validation errors, you can filter them by error code::
+
+    use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
+
+    $violations = $validator->validate(...);
+    if (count($violations->findByCodes(UniqueEntity::NOT_UNIQUE_ERROR))) {
+        // handle this specific error (display some message, send an email, etc.)
+    }
+
+.. versionadded:: 3.3
+    The ``findByCodes()`` method was introduced in Symfony 3.3.
 
 Retrieving a Validator Instance
 -------------------------------

controller/argument_value_resolver.rst

@@ -45,10 +45,9 @@ Symfony ships with five value resolvers in the HttpKernel component:
 Adding a Custom Value Resolver
 ------------------------------
 
-Adding a new value resolver requires creating one class and one service
-definition. In the next example, you'll create a value resolver to inject the
-``User`` object from the security system. Given you write the following
-controller::
+In the next example, you'll create a value resolver to inject the object that
+represents the current user whenever a controller method type-hints an argument
+with the ``User`` class::
 
     namespace App\Controller;
 
@@ -63,10 +62,30 @@ controller::
         }
     }
 
-Somehow you will have to get the ``User`` object and inject it into the controller.
-This can be done by implementing the
-:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`.
-This interface specifies that you have to implement two methods:
+Beware that this feature is already provided by the `@ParamConverter`_
+annotation from the SensioFrameworkExtraBundle. If you have that bundle
+installed in your project, add this config to disable the auto-conversion of
+type-hinted method arguments:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        sensio_framework_extra:
+            request:
+                converters: true
+                auto_convert: false
+
+    .. code-block:: xml
+
+        <sensio-framework-extra:config>
+            <request converters="true" auto-convert="true" />
+        </sensio-framework-extra:config>
+
+Adding a new value resolver requires creating a class that implements
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`
+and defining a service for it. The interface defines two methods:
 
 ``supports()``
     This method is used to check whether the value resolver supports the
@@ -193,4 +212,5 @@ subrequests.
     $user = null``). The ``DefaultValueResolver`` is executed as the last
     resolver and will use the default value if no value was already resolved.
 
+.. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`yield`: http://php.net/manual/en/language.generators.syntax.php

doctrine/multiple_entity_managers.rst

@@ -34,21 +34,17 @@ The following configuration code shows how you can configure two entity managers
                 default_connection: default
                 connections:
                     default:
-                        driver:   pdo_mysql
-                        host:     '%database_host%'
-                        port:     '%database_port%'
-                        dbname:   '%database_name%'
-                        user:     '%database_user%'
-                        password: '%database_password%'
-                        charset:  UTF8
+                        # configure these for your database server
+                        url: '%env(DATABASE_URL)%'
+                        driver: 'pdo_mysql'
+                        server_version: '5.7'
+                        charset: utf8mb4
                     customer:
-                        driver:   pdo_mysql
-                        host:     '%database_host2%'
-                        port:     '%database_port2%'
-                        dbname:   '%database_name2%'
-                        user:     '%database_user2%'
-                        password: '%database_password2%'
-                        charset:  UTF8
+                        # configure these for your database server
+                        url: '%env(DATABASE_CUSTOMER_URL)%'
+                        driver: 'pdo_mysql'
+                        server_version: '5.7'
+                        charset: utf8mb4
 
             orm:
                 default_entity_manager: default
@@ -86,24 +82,20 @@ The following configuration code shows how you can configure two entity managers
 
             <doctrine:config>
                 <doctrine:dbal default-connection="default">
+                    <!-- configure these for your database server -->
                     <doctrine:connection name="default"
+                        url="%env(DATABASE_URL)%"
                         driver="pdo_mysql"
-                        host="%database_host%"
-                        port="%database_port%"
-                        dbname="%database_name%"
-                        user="%database_user%"
-                        password="%database_password%"
-                        charset="UTF8"
+                        server_version="5.7"
+                        charset="utf8mb4"
                     />
 
+                    <!-- configure these for your database server -->
                     <doctrine:connection name="customer"
+                        url="%env(DATABASE_CUSTOMER_URL)%"
                         driver="pdo_mysql"
-                        host="%database_host2%"
-                        port="%database_port2%"
-                        dbname="%database_name2%"
-                        user="%database_user2%"
-                        password="%database_password2%"
-                        charset="UTF8"
+                        server_version="5.7"
+                        charset="utf8mb4"
                     />
                 </doctrine:dbal>
 
@@ -140,23 +132,19 @@ The following configuration code shows how you can configure two entity managers
             'dbal' => array(
                 'default_connection' => 'default',
                 'connections' => array(
+                    // configure these for your database server
                     'default' => array(
-                        'driver'   => 'pdo_mysql',
-                        'host'     => '%database_host%',
-                        'port'     => '%database_port%',
-                        'dbname'   => '%database_name%',
-                        'user'     => '%database_user%',
-                        'password' => '%database_password%',
-                        'charset'  => 'UTF8',
+                        'url'            => '%env(DATABASE_URL)%',
+                        'driver'         => 'pdo_mysql',
+                        'server_version' => '5.7',
+                        'charset'        => 'utf8mb4',
                     ),
+                    // configure these for your database server
                     'customer' => array(
-                        'driver'   => 'pdo_mysql',
-                        'host'     => '%database_host2%',
-                        'port'     => '%database_port2%',
-                        'dbname'   => '%database_name2%',
-                        'user'     => '%database_user2%',
-                        'password' => '%database_password2%',
-                        'charset'  => 'UTF8',
+                        'url'            => '%env(DATABASE_CUSTOMER_URL)%',
+                        'driver'         => 'pdo_mysql',
+                        'server_version' => '5.7',
+                        'charset'        => 'utf8mb4',
                     ),
                 ),
             ),

page_creation.rst

@@ -147,7 +147,7 @@ that Flex resolves to ``sensio/framework-extra-bundle``.
 
 Second, after this package was downloaded, Flex executed a *recipe*, which is a
 set of automated instructions that tell Symfony how to integrate an external
-package. Flex recipes exist for many packages (see `symfony.sh`_) and have the ability
+package. `Flex recipes`_ exist for many packages and have the ability
 to do a lot, like adding configuration files, creating directories, updating ``.gitignore``
 and adding new config to your ``.env`` file. Flex *automates* the installation of
 packages so you can get back to coding.
@@ -355,4 +355,4 @@ Go Deeper with HTTP & Framework Fundamentals
 .. _`Twig`: https://twig.symfony.com
 .. _`Composer`: https://getcomposer.org
 .. _`Stellar Development with Symfony`: https://knpuniversity.com/screencast/symfony/setup
-.. _`symfony.sh`: https://symfony.sh/
+.. _`Flex recipes`: https://flex.symfony.com

quick_tour/flex_recipes.rst

@@ -53,7 +53,7 @@ It's a way for a library to automatically configure itself by adding and modifyi
 files. Thanks to recipes, adding features is seamless and automated: install a package
 and you're done!
 
-You can find a full list of recipes and aliases by going to `https://symfony.sh`_.
+You can find a full list of recipes and aliases by going to `https://flex.symfony.com`_.
 
 What did this recipe do? In addition to automatically enabling the feature in
 ``config/bundles.php``, it added 3 things:
@@ -258,6 +258,6 @@ and it's the most important yet. I want to show you how Symfony empowers you to
 build features *without* sacrificing code quality or performance. It's all about
 the service container, and it's Symfony's super power. Read on: about :doc:`/quick_tour/the_architecture`.
 
-.. _`https://symfony.sh`: https://symfony.sh
+.. _`https://flex.symfony.com`: https://flex.symfony.com
 .. _`Api Platform`: https://api-platform.com/
 .. _`Twig`: https://twig.symfony.com/

reference/configuration/twig.rst

@@ -121,13 +121,13 @@ application harder to maintain.
 cache
 ~~~~~
 
-**type**: ``string`` **default**: ``'%kernel.cache_dir%/twig'``
+**type**: ``string`` | ``false`` | ``Twig\Cache\CacheInterface`` **default**: ``'%kernel.cache_dir%/twig'``
 
 Before using the Twig templates to render some contents, they are compiled into
 regular PHP code. Compilation is a costly process, so the result is cached in
 the directory defined by this configuration option.
 
-Set this option to ``null`` to disable Twig template compilation. However, this
+Set this option to ``false`` to disable Twig template compilation. However, this
 is not recommended; not even in the ``dev`` environment, because the
 ``auto_reload`` option ensures that cached templates which have changed get
 compiled again.

reference/forms/types/text.rst

@@ -9,8 +9,9 @@ The TextType field represents the most basic input text field.
 +-------------+--------------------------------------------------------------------+
 | Rendered as | ``input`` ``text`` field                                           |
 +-------------+--------------------------------------------------------------------+
-| Inherited   | - `data`_                                                          |
-| options     | - `disabled`_                                                      |
+| Inherited   | - `attr`_                                                          |
+| options     | - `data`_                                                          |
+|             | - `disabled`_                                                      |
 |             | - `empty_data`_                                                    |
 |             | - `error_bubbling`_                                                |
 |             | - `error_mapping`_                                                 |
@@ -35,6 +36,8 @@ Inherited Options
 
 These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
+.. include:: /reference/forms/types/options/attr.rst.inc
+
 .. include:: /reference/forms/types/options/data.rst.inc
 
 .. include:: /reference/forms/types/options/disabled.rst.inc

testing.rst

@@ -571,6 +571,19 @@ will no longer be followed::
 
     $client->followRedirects(false);
 
+Reporting Exceptions
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+    The ``catchExceptions()`` method was introduced in Symfony 3.4.
+
+Debugging exceptions in functional tests may be difficult because by default
+they are caught and you need to look at the logs to see which exception was
+thrown. Disabling catching of exceptions in the test client allows the exception
+to be reported by PHPUnit::
+
+    $client->catchExceptions(false);
+
 .. index::
    single: Tests; Crawler