Merge branch '4.0'

* 4.0: (24 commits)
  added Sam in the core team
  minor #9494 [Console] Change use statement for Process Helper (krizon)
  Specify how provide a high availability
  fixing format + language
  Documenting make:controller and make:crud
  Use FQCN as service ID
  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
  ...

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/lock.rst

@@ -274,6 +274,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

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

contributing/community/review-comments.rst

@@ -166,8 +166,8 @@ Final Words
 -----------
 
 Don't feel bad if you "failed" to follow these tips. As long as your
-intentions were good and you didn't really offended or insult anyone;
-you can explain you misunderstood, you didn't meant to marginalize or
+intentions were good and you didn't really offend or insult anyone;
+you can explain you misunderstood, you didn't mean to marginalize or
 simply failed.
 
 But don't say it "just because", if your apology is not really meant

controller.rst

@@ -290,6 +290,27 @@ in your controllers.
 
 For more information about services, see the :doc:`/service_container` article.
 
+Generating Controllers
+----------------------
+
+To save time, you can also tell Symfony to generate a new controller class:
+
+.. code-block:: terminal
+
+    $ php bin/console make:controller BrandNewController
+
+    created: src/Controller/BrandNewController.php
+
+If you want to generate an entire CRUD from a Doctrine :doc:`entity </doctrine>`,
+use:
+
+.. code-block:: terminal
+
+    $ php bin/console make:crud Product
+
+.. versionadded::
+    The ``make:crud`` command was introduced in MakerBundle 1.2.
+
 .. index::
    single: Controller; Managing errors
    single: Controller; 404 pages

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

page_creation.rst

@@ -125,6 +125,14 @@ You can now add your route directly *above* the controller:
 That's it! The page - ``http://localhost:8000/lucky/number`` will work exactly
 like before! Annotations are the recommended way to configure routes.
 
+.. tip::
+
+    To create controllers faster, let Symfony generate it for you:
+
+    .. code-block:: terminal
+
+        $ php bin/console make:controller
+
 .. _flex-quick-intro:
 
 Auto-Installing Recipes with Symfony Flex

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.