javiereguiluz
diff --git a/‎best_practices/security.rst
Lines changed: 8 additions & 0 deletions b/‎best_practices/security.rst
Lines changed: 8 additions & 0 deletions
diff --git a/‎bundles/best_practices.rst
Lines changed: 2 additions & 2 deletions b/‎bundles/best_practices.rst
Lines changed: 2 additions & 2 deletions
diff --git a/‎components/filesystem/lock_handler.rst
Lines changed: 1 addition & 1 deletion b/‎components/filesystem/lock_handler.rst
Lines changed: 1 addition & 1 deletion
diff --git a/‎components/ldap.rst
Lines changed: 27 additions & 16 deletions b/‎components/ldap.rst
Lines changed: 27 additions & 16 deletions
diff --git a/‎console/lockable_trait.rst
Lines changed: 6 additions & 2 deletions b/‎console/lockable_trait.rst
Lines changed: 6 additions & 2 deletions
diff --git a/‎controller/error_pages.rst
Lines changed: 0 additions & 4 deletions b/‎controller/error_pages.rst
Lines changed: 0 additions & 4 deletions
diff --git a/‎doctrine/registration_form.rst
Lines changed: 1 addition & 1 deletion b/‎doctrine/registration_form.rst
Lines changed: 1 addition & 1 deletion
diff --git a/‎form/unit_testing.rst
Lines changed: 3 additions & 3 deletions b/‎form/unit_testing.rst
Lines changed: 3 additions & 3 deletions
diff --git a/‎reference/configuration/security.rst
Lines changed: 63 additions & 2 deletions b/‎reference/configuration/security.rst
Lines changed: 63 additions & 2 deletions
diff --git a/‎reference/events.rst
Lines changed: 25 additions & 12 deletions b/‎reference/events.rst
Lines changed: 25 additions & 12 deletions
@@ -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
@@ -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.
 
@@ -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.
@@ -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;
     // ...
 
 
@@ -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)
@@ -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>.
 
@@ -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;
         }
 
@@ -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;
 
@@ -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
@@ -217,22 +217,35 @@ sent as response::
     that forwards the ``Request`` to a given controller defined by the
     ``exception_listener.controller`` parameter.
 
-.. note::
+Symfony uses the following logic to determine the HTTP status code of the
+response:
+
+* If :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`,
+  :method:`Symfony\\Component\\HttpFoundation\\Response::isServerError` or
+  :method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect` is true,
+  then the status code on your ``Response`` object is used;
+
+* If the original exception implements
+  :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`,
+  then ``getStatusCode()`` is called on the exception and used (the headers
+  from ``getHeaders()`` are also added);
 
-    Symfony uses the following logic to determine the HTTP status code of the
-    response:
+* If both of the above aren't true, then a 500 status code is used.
 
-    * If :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`,
-      :method:`Symfony\\Component\\HttpFoundation\\Response::isServerError` or
-      :method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect` is true,
-      then the status code on your ``Response`` object is used;
+.. note::
+
+    If you want to overwrite the status code of the exception response, which
+    you should not without a good reason, call
+    ``GetResponseForExceptionEvent::allowSuccessfulResponse()`` first and then
+    set the status code on the response::
 
-    * If the original exception implements
-      :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`,
-      then ``getStatusCode()`` is called on the exception and used (the headers
-      from ``getHeaders()`` are also added);
+        $event->allowSuccessfulResponse();
+        $response = new Response('No Content', 204);
+        $event->setResponse($response);
 
-    * If both of the above aren't true, then a 500 status code is used.
+    The status code sent to the client in the above example will be ``204``. If
+    ``$event->allowSuccessfulResponse()`` is omitted, then the kernel will set
+    an appropriate status code based on the type of exception thrown.
 
 .. seealso::
Original file line number	Diff line number	Diff line change
`@@ -138,7 +138,7 @@ With some validation added, your class may look something like this::`
`138`	`138`
`139`	`139`	`public function getSalt()`
`140`	`140`	`{`
`141`		`- // The bcrypt algorithm doesn't require a separate salt.`
	`141`	`+ // The bcrypt and argon2i algorithms don't require a separate salt.`
`142`	`142`	`// You may need a real salt if you choose a different encoder.`
`143`	`143`	`return null;`
`144`	`144`	`}`