Merge branch '4.0'

* 4.0: (36 commits)
  add note about same-state transitions
  Corrected recipes
  minor #8205 Move JavaScript to separate file (technetium, javiereguiluz)
  [Workflow] Document the new transition completed event
  [error_pages] Removing misleading  checker in code example
  Added the env vars in the nginx config too
  Commented the env vars and mentioned that they are optional
  fix syntax errors and add some more crosslinks
  Updated LDAP documentation for Symfony 3.1
  Updating example README to match note below it
  Update docs for setting custom response code in exception handler
  ...

Author: javiereguiluz

best_practices/security.rst

@@ -37,6 +37,13 @@ of ``bcrypt`` are the inclusion of a *salt* value to protect against rainbow
 table attacks, and its adaptive nature, which allows to make it slower to
 remain resistant to brute-force search attacks.
 
+.. note::
+
+    :ref:`Argon2i <reference-security-argon2i>` is the hashing algorithm as
+    recommended by industry standards, but this won't be available to you unless
+    you are using PHP 7.2+ or have the `libsodium`_ extension installed.
+    ``bcrypt`` is sufficient for most applications.
+
 With this in mind, here is the authentication setup from our application,
 which uses a login form to load users from the database:
 
@@ -408,3 +415,4 @@ Next: :doc:`/best_practices/web-assets`
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
+.. _`libsodium`: https://pecl.php.net/package/libsodium

bundles/best_practices.rst

@@ -220,7 +220,7 @@ following standardized instructions in your ``README.md`` file.
         following command to download the latest stable version of this bundle:
 
         ```console
-        $ composer require <package-name> "~1"
+        $ composer require <package-name>
         ```
 
         This command requires you to have Composer installed globally, as explained
@@ -278,7 +278,7 @@ following standardized instructions in your ``README.md`` file.
 
         .. code-block:: terminal
 
-            $ composer require <package-name> "~1"
+            $ composer require <package-name>
 
         This command requires you to have Composer installed globally, as explained
         in the `installation chapter`_ of the Composer documentation.

components/filesystem/lock_handler.rst

@@ -6,4 +6,4 @@ LockHandler
 .. caution::
 
     The ``LockHandler`` utility was removed in Symfony 4.0. Use the new Symfony
-    Lock component instead.
+    :doc:`Lock component </components/lock>` instead.

components/ldap.rst

@@ -25,8 +25,8 @@ and query against an LDAP server.
 
 The ``Ldap`` class uses an :class:`Symfony\\Component\\Ldap\\Adapter\\AdapterInterface`
 to communicate with an LDAP server. The :class:`adapter <Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Adapter>`
-for PHP's built-in LDAP extension, for example, can be configured
-using the following options:
+for PHP's built-in LDAP extension, for example, can be configured using the
+following options:
 
 ``host``
     IP or hostname of the LDAP server
@@ -38,31 +38,39 @@ using the following options:
     The version of the LDAP protocol to use
 
 ``encryption``
-    The encryption protocol : ``ssl``, ``tls`` or ``none`` (default)
+    The encryption protocol: ``ssl``, ``tls`` or ``none`` (default)
+
+``connection_string``
+    You may use this option instead of ``host`` and ``port`` to connect to the
+    LDAP server
+
+``optReferrals``
+    Specifies whether to automatically follow referrals returned by the LDAP server
 
 ``options``
-    LDAP server's options as defined in :class:`ConnectionOptions <Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\ConnectionOptions>`
+    LDAP server's options as defined in
+    :class:`ConnectionOptions <Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\ConnectionOptions>`
 
 For example, to connect to a start-TLS secured LDAP server::
 
-    use Symfony\Component\Ldap\Adapter\ExtLdap\Adapter;
     use Symfony\Component\Ldap\Ldap;
 
-    $adapter = new Adapter(array(
+    $ldap = Ldap::create('ext_ldap', array(
         'host' => 'my-server',
-        'port' => 389,
-        'encryption' => 'tls',
-        'options' => array(
-            'protocol_version' => 3,
-            'referrals' => false,
-        ),
+        'encryption' => 'ssl',
     ));
-    $ldap = new Ldap($adapter);
+
+Or you could directly specify a connection string::
+
+    use Symfony\Component\Ldap\Ldap;
+
+    $ldap = Ldap::create('ext_ldap', array('connection_string' => 'ldaps://my-server:636'));
 
 The :method:`Symfony\\Component\\Ldap\\Ldap::bind` method
 authenticates a previously configured connection using both the
 distinguished name (DN) and the password of a user::
 
+    use Symfony\Component\Ldap\Ldap;
     // ...
 
     $ldap->bind($dn, $password);
@@ -71,6 +79,7 @@ Once bound (or if you enabled anonymous authentication on your
 LDAP server), you may query the LDAP server using the
 :method:`Symfony\\Component\\Ldap\\Ldap::query` method::
 
+    use Symfony\Component\Ldap\Ldap;
     // ...
 
     $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
@@ -85,19 +94,21 @@ all entries in a single call and do something with the results'
 array, you may use the
 :method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Collection::toArray` method::
 
+    use Symfony\Component\Ldap\Ldap;
     // ...
 
     $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
     $results = $query->execute()->toArray();
 
     // Do something with the results array
 
-Creating or updating entries
+Creating or Updating Entries
 ----------------------------
 
-Since version 3.1, The Ldap component provides means to create
-new LDAP entries, update or even delete existing ones::
+The Ldap component provides means to create new LDAP entries, update or even
+delete existing ones::
 
+    use Symfony\Component\Ldap\Ldap;
     use Symfony\Component\Ldap\Entry;
     // ...
 

console/lockable_trait.rst

@@ -2,8 +2,10 @@ Prevent Multiple Executions of a Console Command
 ================================================
 
 A simple but effective way to prevent multiple executions of the same command in
-a single server is to use **file locks**. The Lock component eases the creation
-and release of these locks.
+a single server is to use `locks`_. The :doc:`Lock component </components/lock>`
+provides multiple classes to create locks based on the filesystem (:ref:`FlockStore <lock-store-flock>`),
+shared memory (:ref:`SemaphoreStore <lock-store-semaphore>`) and even databases
+and Redis servers.
 
 In addition, the Console component provides a PHP trait called ``LockableTrait``
 that adds two convenient methods to lock and release commands::
@@ -35,3 +37,5 @@ that adds two convenient methods to lock and release commands::
             $this->release();
         }
     }
+
+.. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science)

controller/error_pages.rst

@@ -98,10 +98,6 @@ To override the 404 error template for HTML pages, create a new
     {% block body %}
         <h1>Page not found</h1>
 
-        {% if is_granted('IS_AUTHENTICATED_FULLY') %}
-            {# ... #}
-        {% endif %}
-
         <p>
             The requested page couldn't be located. Checkout for any URL
             misspelling or <a href="{{ path('homepage') }}">return to the homepage</a>.

doctrine/registration_form.rst

@@ -138,7 +138,7 @@ With some validation added, your class may look something like this::
 
         public function getSalt()
         {
-            // The bcrypt algorithm doesn't require a separate salt.
+            // The bcrypt and argon2i algorithms don't require a separate salt.
             // You *may* need a real salt if you choose a different encoder.
             return null;
         }

form/unit_testing.rst

@@ -115,7 +115,7 @@ To solve this, you have to mock the injected dependencies, instantiate your own
 form type and use the :class:`Symfony\\Component\\Form\\PreloadedExtension` to
 make sure the ``FormRegistry`` uses the created instance::
 
-    // tests/Form/Type/TestedTypeTests.php
+    // tests/Form/Type/TestedTypeTest.php
     namespace App\Tests\Form\Type;
 
     use App\Form\Type\TestedType;
@@ -169,7 +169,7 @@ will be raised if you try to test a class that depends on other extensions.
 The :method:`Symfony\\Component\\Form\\Test\\TypeTestCase::getExtensions` method
 allows you to return a list of extensions to register::
 
-    // tests/Form/Type/TestedTypeTests.php
+    // tests/Form/Type/TestedTypeTest.php
     namespace App\Tests\Form\Type;
 
     // ...
@@ -216,7 +216,7 @@ Testing against Different Sets of Data
 If you are not familiar yet with PHPUnit's `data providers`_, this might be
 a good opportunity to use them::
 
-    // tests/Form/Type/TestedTypeTests.php
+    // tests/Form/Type/TestedTypeTest.php
     namespace App\Tests\Form\Type;
 
     use App\Form\Type\TestedType;

page_creation.rst

@@ -20,7 +20,7 @@ simple two-step process:
 
 .. seealso::
 
-    Do you prefer video tutorials? Check out the `Joyful Development with Symfony`_
+    Do you prefer video tutorials? Check out the `Stellar Development with Symfony`_
     screencast series from KnpUniversity.
 
 .. seealso::
@@ -341,5 +341,5 @@ Go Deeper with HTTP & Framework Fundamentals
 
 .. _`Twig`: http://twig.sensiolabs.org
 .. _`Composer`: https://getcomposer.org
-.. _`Joyful Development with Symfony`: http://knpuniversity.com/screencast/symfony/first-page
+.. _`Stellar Development with Symfony`: https://knpuniversity.com/screencast/symfony/setup
 .. _`symfony.sh`: https://symfony.sh/

reference/configuration/security.rst

@@ -64,6 +64,10 @@ Each part will be explained in the next section.
                     algorithm:            plaintext
                     ignore_case:          false
 
+                # Argon2i encoder
+                Acme\DemoBundle\Entity\User6:
+                    algorithm:            argon2i
+
             providers:            # Required
                 # Examples:
                 my_in_memory_provider:
@@ -592,7 +596,7 @@ persisting the encoded password alone is enough.
 
 .. note::
 
-    All the encoded passwords are ``60`` characters long, so make sure to
+    BCrypt encoded passwords are ``60`` characters long, so make sure to
     allocate enough space for them to be persisted.
 
 .. tip::
@@ -601,7 +605,63 @@ persisting the encoded password alone is enough.
     the cost to ``4``, which is the minimum value allowed, in the ``test``
     environment configuration.
 
-    .. _reference-security-firewall-context:
+.. _reference-security-argon2i:
+
+Using the Argon2i Password Encoder
+----------------------------------
+
+.. caution::
+
+    To use this encoder, you either need to use PHP version 7.2 or install
+    the `libsodium`_ extension.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+
+            encoders:
+                Symfony\Component\Security\Core\User\User:
+                    algorithm: argon2i
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <config>
+            <!-- ... -->
+            <encoder
+                class="Symfony\Component\Security\Core\User\User"
+                algorithm="argon2i"
+            />
+        </config>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        use Symfony\Component\Security\Core\User\User;
+
+        $container->loadFromExtension('security', array(
+            // ...
+            'encoders' => array(
+                User::class => array(
+                    'algorithm' => 'argon2i',
+                ),
+            ),
+        ));
+
+A salt for each new password is generated automatically and need not be
+persisted. Since an encoded password contains the salt used to encode it,
+persisting the encoded password alone is enough.
+
+.. note::
+
+    Argon2i encoded passwords are ``96`` characters long, but due to the hashing
+    requirements saved in the resulting hash this may change in the future.
+
+.. _reference-security-firewall-context:
 
 Firewall Context
 ----------------
@@ -678,3 +738,4 @@ multiple firewalls, the "context" could actually be shared:
 
 .. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
 .. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat
+.. _`libsodium`: https://pecl.php.net/package/libsodium