Merge branch '3.4' into 4.0

* 3.4: (21 commits)
  added Sam in the core team
  minor #9494 [Console] Change use statement for Process Helper (krizon)
  Specify how provide a high availability
  Use FQCN as service ID
  [#8847] fix another directive
  [#8847] fix tip directive
  Describe reliability in Lock
  Propose identical comparison
  [#9195] fix a minor typo
  Fixed some variable names
  fix some security config examples
  Made explicit testing dependencies
  No more ambiguity on prod mode
  Mention the adder/remover support of PropertyInfo
  ...

Author: javiereguiluz

best_practices/security.rst

@@ -181,7 +181,7 @@ to the ``Post`` entity that checks if a given user is its author::
          */
         public function isAuthor(User $user = null)
         {
-            return $user && $user->getEmail() == $this->getAuthorEmail();
+            return $user && $user->getEmail() === $this->getAuthorEmail();
         }
     }
 

components/console/helpers/processhelper.rst

@@ -11,7 +11,7 @@ To display process details, use the :class:`Symfony\\Component\\Console\\Helper\
 and run your command with verbosity. For example, running the following code with
 a very verbose verbosity (e.g. -vv)::
 
-    use Symfony\Component\Process\ProcessBuilder;
+    use Symfony\Component\Process\Process;
 
     $helper = $this->getHelper('process');
     $process = new Process(array('figlet', 'Symfony'));
@@ -52,7 +52,7 @@ There are three ways to use the process helper:
 
 * Passing a :class:`Symfony\\Component\\Process\\Process` instance::
 
-    use Symfony\Component\Process\ProcessBuilder;
+    use Symfony\Component\Process\Process;
 
     // ...
     $process = new Process(array('figlet', 'Symfony'));

components/lock.rst

@@ -257,6 +257,233 @@ Instead of the simple majority strategy (``ConsensusStrategy``) an
 ``UnanimousStrategy`` can be used to require the lock to be acquired in all
 the stores.
 
+.. caution::
+
+    In order to get high availability when using the ``ConsensusStrategy``, the
+    minimum cluster size must be three servers. This allows the cluster to keep
+    working when a single server fails (because this strategy requires that the
+    lock is acquired in more than half of the servers).
+
+Reliability
+-----------
+
+The component guarantees that the same resource can't be lock twice as long as
+the component is used in the following way.
+
+Remote Stores
+~~~~~~~~~~~~~
+
+Remote stores (:ref:`MemcachedStore <lock-store-memcached>` and
+:ref:`RedisStore <lock-store-redis>`) use an unique token to recognize the true
+owner of the lock. This token is stored in the
+:class:`Symfony\\Component\\Lock\\Key` object and is used internally by the
+``Lock``, therefore this key must not be shared between processes (session,
+caching, fork, ...).
+
+.. caution::
+
+    Do not share a key between processes.
+
+Every concurrent process must store the ``Lock`` in the same server. Otherwise two
+different machines may allow two different processes to acquire the same ``Lock``.
+
+.. caution::
+
+    To guarantee that the same server will always be safe, do not use Memcached
+    behind a LoadBalancer, a cluster or round-robin DNS. Even if the main server
+    is down, the calls must not be forwarded to a backup or failover server.
+
+Expiring Stores
+~~~~~~~~~~~~~~~
+
+Expiring stores (:ref:`MemcachedStore <lock-store-memcached>` and
+:ref:`RedisStore <lock-store-redis>`) guarantee that the lock is acquired
+only for the defined duration of time. If the task takes longer to be
+accomplished, then the lock can be released by the store and acquired by
+someone else.
+
+The ``Lock`` provides several methods to check its health. The ``isExpired()``
+method checks whether or not it lifetime is over and the ``getRemainingLifetime()``
+method returns its time to live in seconds.
+
+Using the above methods, a more robust code would be::
+
+    // ...
+    $lock = $factory->createLock('invoice-publication', 30);
+
+    $lock->acquire();
+    while (!$finished) {
+        if ($lock->getRemainingLifetime() <= 5) {
+            if ($lock->isExpired()) {
+                // lock was lost, perform a rollback or send a notification
+                throw new \RuntimeException('Lock lost during the overall process');
+            }
+
+            $lock->refresh();
+        }
+
+        // Perform the task whose duration MUST be less than 5 minutes
+    }
+
+.. caution::
+
+    Choose wisely the lifetime of the ``Lock`` and check whether its remaining
+    time to leave is enough to perform the task.
+
+.. caution::
+
+    Storing a ``Lock`` usually takes a few milliseconds, but network conditions
+    may increase that time a lot (up to a few seconds). Take that into account
+    when choosing the right TTL.
+
+By design, locks are stored in servers with a defined lifetime. If the date or
+time of the machine changes, a lock could be released sooner than expected.
+
+.. caution::
+
+    To guarantee that date won't change, the NTP service should be disabled
+    and the date should be updated when the service is stopped.
+
+FlockStore
+~~~~~~~~~~
+
+By using the file system, this ``Store`` is reliable as long as concurrent
+processes use the same physical directory to stores locks.
+
+Processes must run on the same machine, virtual machine or container.
+Be careful when updating a Kubernetes or Swarm service because for a short
+period of time, there can be two running containers in parallel.
+
+The absolute path to the directory must remain the same. Be careful of symlinks
+that could change at anytime: Capistrano and blue/green deployment often use
+that trick. Be careful when the path to that directory changes between two
+deployments.
+
+Some file systems (such as some types of NFS) do not support locking.
+
+.. caution::
+
+    All concurrent processes must use the same physical file system by running
+    on the same machine and using the same absolute path to locks directory.
+
+    By definition, usage of ``FlockStore`` in an HTTP context is incompatible
+    with multiple front servers, unless to ensure that the same resource will
+    always be locked on the same machine or to use a well configured shared file
+    system.
+
+Files on file system can be removed during a maintenance operation. For instance
+to cleanup the ``/tmp`` directory or after a reboot of the machine when directory
+uses tmpfs. It's not an issue if the lock is released when the process ended, but
+it is in case of ``Lock`` reused between requests.
+
+.. caution::
+
+    Do not store locks on a volatile file system if they have to be reused in
+    several requests.
+
+MemcachedStore
+~~~~~~~~~~~~~~
+
+The way Memcached works is to store items in memory. That means that by using
+the :ref:`MemcachedStore <lock-store-memcached>` the locks are not persisted
+and may disappear by mistake at anytime.
+
+If the Memcached service or the machine hosting it restarts, every lock would
+be lost without notifying the running processes.
+
+.. caution::
+
+    To avoid that someone else acquires a lock after a restart, it's recommended
+    to delay service start and wait at least as long as the longest lock TTL.
+
+By default Memcached uses a LRU mechanism to remove old entries when the service
+needs space to add new items.
+
+.. caution::
+
+    Number of items stored in the Memcached must be under control. If it's not
+    possible, LRU should be disabled and Lock should be stored in a dedicated
+    Memcached service away from Cache.
+
+When the Memcached service is shared and used for multiple usage, Locks could be
+removed by mistake. For instance some implementation of the PSR-6 ``clear()``
+method uses the Memcached's ``flush()`` method which purges and removes everything.
+
+.. caution::
+
+    The method ``flush()`` must not be called, or locks should be stored in a
+    dedicated Memcached service away from Cache.
+
+RedisStore
+~~~~~~~~~~
+
+The way Redis works is to store items in memory. That means that by using
+the :ref:`RedisStore <lock-store-redis>` the locks are not persisted
+and may disappear by mistake at anytime.
+
+If the Redis service or the machine hosting it restarts, every locks would
+be lost without notifying the running processes.
+
+.. caution::
+
+    To avoid that someone else acquires a lock after a restart, it's recommended
+    to delay service start and wait at least as long as the longest lock TTL.
+
+.. tip::
+
+    Redis can be configured to persist items on disk, but this option would
+    slow down writes on the service. This could go against other uses of the
+    server.
+
+When the Redis service is shared and used for multiple usages, locks could be
+removed by mistake.
+
+.. caution::
+
+    The command ``FLUSHDB`` must not be called, or locks should be stored in a
+    dedicated Redis service away from Cache.
+
+CombinedStore
+~~~~~~~~~~~~~
+
+Combined stores allow to store locks across several backends. It's a common
+mistake to think that the lock mechanism will be more reliable. This is wrong
+The ``CombinedStore`` will be, at best, as reliable as the least reliable of
+all managed stores. As soon as one managed store returns erroneous information,
+the ``CombinedStore`` won't be reliable.
+
+.. caution::
+
+    All concurrent processes must use the same configuration, with the same
+    amount of managed stored and the same endpoint.
+
+.. tip::
+
+    Instead of using a cluster of Redis or Memcached servers, it's better to use
+    a ``CombinedStore`` with a single server per managed store.
+
+SemaphoreStore
+~~~~~~~~~~~~~~
+
+Semaphores are handled by the Kernel level. In order to be reliable, processes
+must run on the same machine, virtual machine or container. Be careful when
+updating a Kubernetes or Swarm service because for a short period of time, there
+can be two running containers in parallel.
+
+.. caution::
+
+    All concurrent processes must use the same machine. Before starting a
+    concurrent process on a new machine, check that other process are stopped
+    on the old one.
+
+Overall
+~~~~~~~
+
+Changing the configuration of stores should be done very carefully. For
+instance, during the deployment of a new version. Processes with new
+configuration must not be started while old processes with old configuration
+are still running.
+
 .. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science)
 .. _Packagist: https://packagist.org/packages/symfony/lock
 .. _`PHP semaphore functions`: http://php.net/manual/en/book.sem.php

components/property_info.rst

@@ -237,8 +237,44 @@ provide whether properties are readable or writable as booleans.
 
 The :class:`Symfony\\Component\\PropertyInfo\\Extractor\\ReflectionExtractor` looks
 for getter/isser/setter method in addition to whether or not a property is public
-to determine if it's accessible. This based on how the :doc:`PropertyAccess </components/property_access>`
-works.
+to determine if it's accessible.
+
+This is based on how :doc:`PropertyAccess </components/property_access>` works,
+so it even looks for adder/remover methods and can transform between singular
+and plural property names::
+
+    class SomeClass
+    {
+        private $analyses;
+        private $feet;
+
+        public function addAnalyse(Dummy $analyse)
+        {
+            // ...
+        }
+
+        public function removeAnalyse(Dummy $analyse)
+        {
+            // ...
+        }
+
+        public function addFoot(Dummy $foot)
+        {
+            // ...
+        }
+
+        public function removeFoot(Dummy $foot)
+        {
+            // ...
+        }
+    }
+
+    // to be writable, both the adder and the remover methods must be defined
+    $propertyInfo->isWritable(SomeClass::class, 'analyses'); // returns true
+    $propertyInfo->isWritable(SomeClass::class, 'feet');     // returns true
+
+.. versionadded:: 3.2
+    The support of adder/remover methods was introduced in Symfony 3.2.
 
 .. tip::
 

contributing/code/core_team.rst

@@ -84,7 +84,9 @@ Active Core Members
     Form_, Serializer_, DependencyInjection_, and HttpKernel_ components;
 
   * **Tobias Nyholm** (`Nyholm`) manages the official and contrib recipes
-    repositories.
+    repositories;
+
+  * **Samuel Rozé** (`sroze`_) can merge into Messenger_ component.
 
 * **Deciders** (``@symfony/deciders`` on GitHub):
 
@@ -192,6 +194,7 @@ discretion of the **Project Leader**.
 .. _Intl: https://github.com/symfony/intl
 .. _LDAP: https://github.com/symfony/ldap
 .. _Locale: https://github.com/symfony/locale
+.. _Messenger: https://github.com/symfony/messenger
 .. _MonologBridge: https://github.com/symfony/monolog-bridge
 .. _OptionsResolver: https://github.com/symfony/options-resolver
 .. _Process: https://github.com/symfony/process
@@ -227,3 +230,4 @@ discretion of the **Project Leader**.
 .. _`chalasr`: https://github.com/chalasr/
 .. _`ogizanagi`: https://github.com/ogizanagi/
 .. _`Nyholm`: https://github.com/Nyholm
+.. _`sroze`: https://github.com/sroze

controller/upload_file.rst

@@ -294,7 +294,7 @@ Then, define a service for this class:
         use App\Service\FileUploader;
 
         $container->autowire(FileUploader::class)
-            ->setArgument('$targetDir', '%brochures_directory%');
+            ->setArgument('$targetDirectory', '%brochures_directory%');
 
 Now you're ready to use this service in the controller::
 
@@ -454,7 +454,7 @@ controller.
                 }
 
                 if ($fileName = $entity->getBrochure()) {
-                    $entity->setBrochure(new File($this->uploader->getTargetDir().'/'.$fileName));
+                    $entity->setBrochure(new File($this->uploader->getTargetDirectory().'/'.$fileName));
                 }
             }
         }

deployment.rst

@@ -135,6 +135,11 @@ 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.
 
+At the very least you need to define the ``SYMFONY_ENV=prod`` (or
+``APP_ENV=prod`` if you're using :doc:`Symfony Flex </setup/flex>`) to run the
+application in ``prod`` mode, but depending on your application you may need to
+define other env vars too.
+
 C) Install/Update your Vendors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

reference/forms/types/options/compound.rst.inc

@@ -3,6 +3,22 @@ compound
 
 **type**: ``boolean`` **default**: ``true``
 
-This option specifies if a form is compound. This is independent of whether
-the form actually has children. A form can be compound but not have any
-children at all (e.g. an empty collection form).
+If ``true`` this option creates the form as "compound", meaning that it
+can contain children and be a parent of other forms.
+
+Most of the time you won't need to override this option.
+You might want to control for it when creating a custom form type
+with advanced rendering logic.
+
+In a view a compound form is rendered as a ``<div>`` container or
+a ``<form>`` element (the whole form is obviously a compound form).
+
+Non-compound forms are always leaves in a form tree, they cannot have children.
+
+A non-compound form is rendered as one of the html form elements: ``<input>``
+(``TextType``, ``FileType``, ``HiddenType``), ``<textarea>`` (``TextareaType``)
+or ``<select>`` (``ChoiceType``).
+
+An interesting case is the ``ChoiceType``. With ``expanded=false`` it is a non-compound form
+and is rendered as a ``<select>`` tag. With ``expanded=true`` the ``ChoiceType`` becomes a
+compound form and is rendered as a set of radios or checkboxes.