Merge branch '4.0' into 4.1

* 4.0: (24 commits)
  updating the guard session migration details for Symfony 3.4 changes
  Avoiding authentication on every request with Guard
  Minor typo in csrf.rst
  [Filesystem] Improved the code of an example
  Removed another usage of mt_rand()
  Transition from mt_rand to random_int
  Update setup.rst
  remove not existent label_attr options from buttons
  Fixed some code indentation
  Added the versionadded directive
  add missing XML and PHP code examples
  Expanded the explanation a bit
  Minor fixes
  Update licence hint for JMS serializer
  Revert "minor #9507 Document the built in env var processors (mcfedr, javiereguiluz)"
  Minor rewords and formatting fixes
  Example of customer env var processor
  Add examples for parameter processors
  Add description of the built in envvar processors
  Mention that "exclude" option now accepts arrays too
  ...

Author: weaverryan

components/filesystem.rst

@@ -29,7 +29,7 @@ endpoint for filesystem operations::
     $fileSystem = new Filesystem();
 
     try {
-        $fileSystem->mkdir('/tmp/random/dir/'.mt_rand());
+        $fileSystem->mkdir(sys_get_temp_dir().'/'.random_int(0, 1000));
     } catch (IOExceptionInterface $exception) {
         echo "An error occurred while creating your directory at ".$exception->getPath();
     }

components/finder.rst

@@ -168,17 +168,27 @@ Sort the result by name or by type (directories first, then files)::
 
     $finder->sortByType();
 
-.. note::
+.. tip::
 
-    Notice that the ``sort*`` methods need to get all matching elements to do
-    their jobs. For large iterators, it is slow.
+    By default, the ``sortByName()`` method uses the :phpfunction:`strcmp` PHP
+    function (e.g. ``file1.txt``, ``file10.txt``, ``file2.txt``). Pass ``true``
+    as its argument to use PHP's `natural sort order`_ algorithm instead (e.g.
+    ``file1.txt``, ``file2.txt``, ``file10.txt``).
+
+    .. versionadded:: 4.2
+        The option to use the natural sort order was introduced in Symfony 4.2.
 
 You can also define your own sorting algorithm with ``sort()`` method::
 
     $finder->sort(function (\SplFileInfo $a, \SplFileInfo $b) {
         return strcmp($a->getRealPath(), $b->getRealPath());
     });
 
+.. note::
+
+    Notice that the ``sort*`` methods need to get all matching elements to do
+    their jobs. For large iterators, it is slow.
+
 File Name
 ~~~~~~~~~
 
@@ -320,8 +330,9 @@ The contents of returned files can be read with
         // ...
     }
 
-.. _strtotime:    https://php.net/manual/en/datetime.formats.php
-.. _protocol:     https://php.net/manual/en/wrappers.php
-.. _Streams:      https://php.net/streams
-.. _IEC standard: https://physics.nist.gov/cuu/Units/binary.html
-.. _Packagist:    https://packagist.org/packages/symfony/finder
+.. _strtotime:          https://php.net/manual/en/datetime.formats.php
+.. _protocol:           https://php.net/manual/en/wrappers.php
+.. _Streams:            https://php.net/streams
+.. _IEC standard:       https://physics.nist.gov/cuu/Units/binary.html
+.. _Packagist:          https://packagist.org/packages/symfony/finder
+.. _`natural sort order`: https://en.wikipedia.org/wiki/Natural_sort_order

components/ldap.rst

@@ -137,6 +137,38 @@ delete existing ones::
     // Removing an existing entry
     $entryManager->remove(new Entry('cn=Test User,dc=symfony,dc=com'));
 
+
+Batch Updating
+______________
+
+Use the entry manager's :method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\EntryManager::applyOperations`
+method to update multiple attributes at once::
+
+    use Symfony\Component\Ldap\Ldap;
+    use Symfony\Component\Ldap\Entry;
+    // ...
+
+    $entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', array(
+        'sn' => array('fabpot'),
+        'objectClass' => array('inetOrgPerson'),
+    ));
+
+    $entryManager = $ldap->getEntryManager();
+
+    // Adding multiple email adresses at once
+    $entryManager->applyOperations($entry->getDn(), array(
+        new UpdateOpteration(LDAP_MODIFY_BATCH_ADD, 'mail', 'new1@example.com'),
+        new UpdateOpteration(LDAP_MODIFY_BATCH_ADD, 'mail', 'new2@example.com'),
+    ));
+
+Possible operation types are ``LDAP_MODIFY_BATCH_ADD``, ``LDAP_MODIFY_BATCH_REMOVE``,
+``LDAP_MODIFY_BATCH_REMOVE_ALL``, ``LDAP_MODIFY_BATCH_REPLACE``. Parameter
+``$values`` must be ``NULL`` when using ``LDAP_MODIFY_BATCH_REMOVE_ALL``
+operation type.
+
+.. versionadded:: 4.2
+    The ``applyOperations()`` method was introduced in Symfony 4.2.
+    
 .. versionadded:: 4.1
     The ``addAttributeValues()`` and ``removeAttributeValues()`` methods
     were introduced in Symfony 4.1.

components/messenger.rst

@@ -41,7 +41,7 @@ Concepts
 Bus
 ---
 
-The bus is used to dispatch messages. The behaviour of the bus is in its ordered
+The bus is used to dispatch messages. The behavior of the bus is in its ordered
 middleware stack. The component comes with a set of middleware that you can use.
 
 When using the message bus with Symfony's FrameworkBundle, the following middleware
@@ -66,9 +66,9 @@ Example::
 
     $result = $bus->dispatch(new MyMessage(/* ... */));
 
-.. note:
+.. note::
 
-    Every middleware needs to implement the ``MiddlewareInterface`` interface.
+    Every middleware needs to implement the ``MiddlewareInterface``.
 
 Handlers
 --------
@@ -92,16 +92,16 @@ that will do the required processing for your message::
 Transports
 ----------
 
-In order to send and receive messages, you will have to configure a transport. An
-transport will be responsible of communicating with your message broker or 3rd parties.
+In order to send and receive messages, you will have to configure a transport. A
+transport will be responsible for communicating with your message broker or 3rd parties.
 
-Your own sender
+Your own Sender
 ~~~~~~~~~~~~~~~
 
 Using the ``SenderInterface``, you can easily create your own message sender.
-Let's say you already have an ``ImportantAction`` message going through the
-message bus and handled by a handler. Now, you also want to send this message as
-an email.
+Imagine that you already have an ``ImportantAction`` message going through the
+message bus and being handled by a handler. Now, you also want to send this
+message as an email.
 
 First, create your sender::
 
@@ -138,13 +138,13 @@ First, create your sender::
        }
     }
 
-Your own receiver
+Your own Receiver
 ~~~~~~~~~~~~~~~~~
 
 A receiver is responsible for receiving messages from a source and dispatching
 them to the application.
 
-Let's say you already processed some "orders" in your application using a
+Imagine you already processed some "orders" in your application using a
 ``NewOrder`` message. Now you want to integrate with a 3rd party or a legacy
 application but you can't use an API and need to use a shared CSV file with new
 orders.
@@ -186,10 +186,10 @@ First, create your receiver::
        }
     }
 
-Receiver and Sender on the same bus
+Receiver and Sender on the same Bus
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To allow us to receive and send messages on the same bus and prevent an infinite
+To allow sending and receiving messages on the same bus and prevent an infinite
 loop, the message bus is equipped with the ``WrapIntoReceivedMessage`` middleware.
 It will wrap the received messages into ``ReceivedMessage`` objects and the
 ``SendMessageMiddleware`` middleware will know it should not route these

components/serializer.rst

@@ -1261,7 +1261,8 @@ Learn more
 .. seealso::
 
     A popular alternative to the Symfony Serializer Component is the third-party
-    library, `JMS serializer`_ (released under the Apache license, so incompatible with GPLv2 projects).
+    library, `JMS serializer`_ (versions before ``v1.12.0`` were released under
+    the Apache license, so incompatible with GPLv2 projects).
 
 .. _`PSR-1 standard`: https://www.php-fig.org/psr/psr-1/
 .. _`JMS serializer`: https://github.com/schmittjoh/serializer