Merge branch '3.4'

* 3.4: (42 commits)
  [#8273] fix bundle registration code
  [#8273] minor rewording
  Reworded the built-in web server articles for Symfony 3.3
  fix diff code block highlighting
  [#8269] minor rewording
  [Console] Commands auto-registration is deprecated
  [#8231] fix reStructuredText syntax
  Specified import order of config files
  [#7981] revert some changes
  Update upload_file.rst
  Update usage.rst
  Update doctrine.rst
  Update usage.rst
  [#8260] add missing redirection map entry
  Delete use_virtuals_forms.rst
  Added a missing redirection
  Update validation_group_service_resolver.rst
  Update redirection_map
  Update button_based_validation.rst
  Delete group_service_resolver.rst
  ...

Author: xabbuh

_build/redirection_map

@@ -262,7 +262,7 @@
 /cookbook/upgrade/minor_version /setup/upgrade_major
 /cookbook/upgrade/patch_version /upgrade/bundles
 /cookbook/validation/custom_constraint /validation/custom_constraint
-/cookbook/validation/group_service_resolver /validation/group_service_resolver
+/cookbook/validation/group_service_resolver /form/validation_group_service_resolver
 /cookbook/validation/index /validation
 /cookbook/validation/severity /validation/severity
 /cookbook/web_server/built_in /setup/built_in_web_server
@@ -287,6 +287,7 @@
 /components/debug/introduction /components/debug
 /components/debug/index /components/debug
 /components/dependency_injection/advanced /service_container/alias_private
+/components/dependency_injection/autowiring /service_container/autowiring
 /components/dependency_injection/definitions /service_container/definitions
 /components/dependency_injection/introduction /components/dependency_injection
 /components/dependency_injection/index /components/dependency_injection
@@ -310,6 +311,7 @@
 /components/form/type_guesser /form/type_guesser
 /components/http_foundation/index /components/http_foundation
 /components/http_foundation/introduction /components/http_foundation
+/components/http_foundation/trusting_proxies /request/load_balancer_reverse_proxy
 /components/http_kernel/introduction /components/http_kernel
 /components/http_kernel/index /components/http_kernel
 /components/property_access/introduction /components/property_access
@@ -331,11 +333,11 @@
 /components/yaml/index /components/yaml
 /deployment/tools /deployment
 /install/bundles /setup/bundles
-/form /forms
-/testing/simulating_authentication /testing/http_authentication
-/components/dependency_injection/autowiring /service_container/autowiring
 /event_dispatcher/class_extension /event_dispatcher
+/form /forms
+/form/use_virtual_forms /form/inherit_data_option
 /security/target_path /security
 /service_container/third_party /service_container
 /templating/templating_service /templates
-/components/http_foundation/trusting_proxies /request/load_balancer_reverse_proxy
+/testing/simulating_authentication /testing/http_authentication
+/validation/group_service_resolver /form/validation_group_service_resolver

components/console/single_command_tool.rst

@@ -39,13 +39,8 @@ Of course, you can still register a command as usual::
   <?php
   require __DIR__.'/vendor/autoload.php';
 
-  use Symfony\Component\Console\Application;
-  use Symfony\Component\Console\Input\InputArgument;
-  use Symfony\Component\Console\Input\InputInterface;
-  use Symfony\Component\Console\Input\InputOption;
-  use Symfony\Component\Console\Output\OutputInterface;
-
   use Acme\Command\DefaultCommand;
+  use Symfony\Component\Console\Application;
 
   $application = new Application('echo', '1.0.0');
   $command = new DefaultCommand();

components/filesystem.rst

@@ -64,6 +64,13 @@ On POSIX filesystems, directories are created with a default mode value
 
     This function ignores already existing directories.
 
+.. note::
+
+    The directory permissions are affected by the current `umask`_.
+    Set the umask for your webserver, use PHP's :phpfunction:`umask`
+    function or use the :phpfunction:`chmod` function after the
+    directory has been created.
+
 exists
 ~~~~~~
 
@@ -320,3 +327,4 @@ Learn More
     filesystem/*
 
 .. _`Packagist`: https://packagist.org/packages/symfony/filesystem
+.. _`umask`: https://en.wikipedia.org/wiki/Umask

components/phpunit_bridge.rst

@@ -224,14 +224,14 @@ If you have this kind of time-related tests::
             sleep(10);
             $duration = $stopwatch->stop('event_name')->getDuration();
 
-            $this->assertEquals(10, $duration);
+            $this->assertEquals(10000, $duration);
         }
     }
 
 You used the :doc:`Symfony Stopwatch Component </components/stopwatch>` to
 calculate the duration time of your process, here 10 seconds. However, depending
 on the load of the server or the processes running on your local machine, the
-``$duration`` could for example be `10.000023s` instead of `10s`.
+``$duration`` could for example be ``10.000023s`` instead of ``10s``.
 
 This kind of tests are called transient tests: they are failing randomly
 depending on spurious and external circumstances. They are often cause trouble

components/serializer.rst

@@ -418,9 +418,9 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`::
     $obj->name = 'Acme Inc.';
     $obj->address = '123 Main Street, Big City';
 
-    $json = $serializer->serialize($obj);
+    $json = $serializer->serialize($obj, 'json');
     // {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"}
-    $objCopy = $serializer->deserialize($json);
+    $objCopy = $serializer->deserialize($json, Company::class, 'json');
     // Same data as $obj
 
 .. _using-camelized-method-names-for-underscored-attributes:

console.rst

@@ -12,11 +12,11 @@ use it to create your own commands.
 Creating a Command
 ------------------
 
-Commands are defined in classes which must be created in the ``Command`` namespace
-of your bundle (e.g. ``AppBundle\Command``) and their names must end with the
+Commands are defined in classes which should be created in the ``Command`` namespace
+of your bundle (e.g. ``AppBundle\Command``) and their names should end with the
 ``Command`` suffix.
 
-For example, a command called ``CreateUser`` must follow this structure::
+For example, you may want a command to create a user::
 
     // src/AppBundle/Command/CreateUserCommand.php
     namespace AppBundle\Command;
@@ -64,12 +64,28 @@ method. Then you can optionally define a help message and the
 Executing the Command
 ---------------------
 
-After configuring the command, you can execute it in the terminal:
+Symfony registers any PHP class extending :class:`Symfony\\Component\\Console\\Command\\Command`
+as a console command automatically. So you can now execute this command in the
+terminal:
 
 .. code-block:: terminal
 
     $ php bin/console app:create-user
 
+.. note::
+
+    If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
+    your command classes are automatically registered as services.
+
+    You can also manually register your command as a service by configuring the service
+    and :doc:`tagging it </service_container/tags>` with ``console.command``.
+
+.. caution::
+
+    Symfony also looks in the ``Command/`` directory of bundles for commands
+    that are not registered as a service. But this auto discovery is deprecated
+    since Symfony 3.4 and won't be supported anymore in Symfony 4.0.
+
 As you might expect, this command will do nothing as you didn't write any logic
 yet. Add your own logic inside the ``execute()`` method, which has access to the
 input stream (e.g. options and arguments) and the output stream (to write

console/commands_as_services.rst

@@ -5,9 +5,13 @@ How to Define Commands as Services
 ==================================
 
 If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
-your command classes are already registered as services. Great! This is the recommended
-setup, but it's not required. Symfony also looks in the ``Command/`` directory of
-each bundle and automatically registers those classes as commands.
+your command classes are already registered as services. Great! This is the
+recommended setup.
+
+Symfony also looks in the ``Command/`` directory of each bundle for commands
+non registered as a service and automatically registers those classes as
+commands. However this auto-registration was deprecated in Symfony 3.4. In
+Symfony 4.0, commands won't be auto-registered anymore.
 
 .. note::
 

controller/upload_file.rst

@@ -329,6 +329,7 @@ automatically upload the file when persisting the entity::
     class BrochureUploadListener
     {
         private $uploader;
+        private $fileName;
 
         public function __construct(FileUploader $uploader)
         {
@@ -359,11 +360,10 @@ automatically upload the file when persisting the entity::
             $file = $entity->getBrochure();
 
             // only upload new files
-            if (!$file instanceof UploadedFile) {
-                return;
+            if ($file instanceof UploadedFile) {
+                $fileName = $this->uploader->upload($file);
             }
 
-            $fileName = $this->uploader->upload($file);
             $entity->setBrochure($fileName);
         }
     }

deployment/platformsh.rst

@@ -126,12 +126,14 @@ following file (it's your role to add this file to your code base)::
     # Store session into /tmp.
     ini_set('session.save_path', '/tmp/sessions');
 
-Make sure this file is listed in your *imports*:
+Make sure this file is listed in your *imports* (after the default ``parameters.yml``
+file):
 
 .. code-block:: yaml
 
     # app/config/config.yml
     imports:
+        - { resource: parameters.yml }
         - { resource: parameters_platform.php }
 
 Deploy your Application

doctrine.rst

@@ -539,17 +539,17 @@ Take a look at the previous example in more detail:
 
 .. _doctrine-entity-manager:
 
-* **line 13** The ``$this->getDoctrine()->getManager()`` method gets Doctrine's
+* **line 12** The ``$this->getDoctrine()->getManager()`` method gets Doctrine's
   *entity manager* object, which is the most important object in Doctrine. It's
   responsible for saving objects to, and fetching objects from, the database.
 
-* **lines 15-18** In this section, you instantiate and work with the ``$product``
+* **lines 14-17** In this section, you instantiate and work with the ``$product``
   object like any other normal PHP object.
 
-* **line 21** The ``persist($product)`` call tells Doctrine to "manage" the
+* **line 20** The ``persist($product)`` call tells Doctrine to "manage" the
   ``$product`` object. This does **not** cause a query to be made to the database.
 
-* **line 24** When the ``flush()`` method is called, Doctrine looks through
+* **line 23** When the ``flush()`` method is called, Doctrine looks through
   all of the objects that it's managing to see if they need to be persisted
   to the database. In this example, the ``$product`` object's data doesn't
   exist in the database, so the entity manager executes an ``INSERT`` query,