Merge remote-tracking branch 'upstream/3.3' into 3.3

Author: javiereguiluz

_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/logger.rst

@@ -9,7 +9,7 @@ The Console component comes with a standalone logger complying with the
 be sent to the :class:`Symfony\\Component\\Console\\Output\\OutputInterface`
 instance passed as a parameter to the constructor.
 
-The logger does not have any external dependency except ``php-fig/log``.
+The logger does not have any external dependency except ``psr/log``.
 This is useful for console applications and commands needing a lightweight
 PSR-3 compliant logger::
 

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

@@ -37,15 +37,11 @@ using the following options:
 ``version``
     The version of the LDAP protocol to use
 
-``useSsl``
-    Whether or not to secure the connection using SSL
+``encryption``
+    The encryption protocol : ``ssl``, ``tls`` or ``none`` (default)
 
-``useStartTls``
-    Whether or not to secure the connection using StartTLS
-
-``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>`
 
 For example, to connect to a start-TLS secured LDAP server::
 
@@ -73,10 +69,10 @@ distinguished name (DN) and the password of a user::
 
 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::find` method::
+:method:`Symfony\\Component\\Ldap\\Ldap::query` method::
 
     // ...
 
-    $ldap->find('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
 
 .. _Packagist: https://packagist.org/packages/symfony/ldap

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

@@ -405,7 +405,7 @@ class extending :class:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNorm
 including :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
 and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`::
 
-    use Symfony\Component\Serializer\Encoder\JsonEncoder
+    use Symfony\Component\Serializer\Encoder\JsonEncoder;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     use Symfony\Component\Serializer\Serializer;
 
@@ -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:

components/validator/resources.rst

@@ -173,14 +173,14 @@ Using a Custom MetadataFactory
 ------------------------------
 
 All the loaders and the cache are passed to an instance of
-:class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadataFactory`. This
-class is responsible for creating a ``ClassMetadata`` instance from all the
+:class:`Symfony\\Component\\Validator\\Mapping\\Factory\\LazyLoadingMetadataFactory`. 
+This class is responsible for creating a ``ClassMetadata`` instance from all the
 configured resources.
 
 You can also use a custom metadata factory implementation by creating a class
 which implements
-:class:`Symfony\\Component\\Validator\\MetadataFactoryInterface`. You can set
-this custom implementation using
+:class:`Symfony\\Component\\Validator\\Mapping\\Factory\\MetadataFactoryInterface`. 
+You can set this custom implementation using
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMetadataFactory`::
 
     use Acme\Validation\CustomMetadataFactory;

components/var_dumper.rst

@@ -101,7 +101,7 @@ Choosing between both is mostly a matter of personal taste, still:
   be suited to your use case (e.g. you shouldn't use it in an HTML
   attribute or a ``<script>`` tag).
 
-This behavior can be changed by configuring the ``dump.dump_destination``
+This behavior can be changed by configuring the ``debug.dump_destination``
 option. Read more about this and other options in
 :doc:`the DebugBundle configuration reference </reference/configuration/debug>`.
 

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);
         }
     }

debug/debugging.rst

@@ -75,6 +75,9 @@ that can help you visualize and find the information.
 ``debug:config``
     Shows all configured bundles, their class and their alias.
 
+``debug:event-dispatcher``
+    Displays information about all the registered listeners in the event dispatcher.
+
 ``debug:router``
     Displays information about all configured routes in the application as a
     table with the name, method, scheme, host and path for each route.

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,

doctrine/associations.rst

@@ -273,7 +273,7 @@ When you need to fetch associated objects, your workflow looks just like it
 did before. First, fetch a ``$product`` object and then access its related
 ``Category`` object::
 
-    use AppBundle\Entity\Post;
+    use AppBundle\Entity\Product;
     // ...
 
     public function showAction($productId)
@@ -368,8 +368,7 @@ following method to the ``ProductRepository`` class::
     // src/AppBundle/Repository/ProductRepository.php
     public function findOneByIdJoinedToCategory($productId)
     {
-        $query = $this->getDoctrine()
-            ->getManager()
+        $query = $this->getEntityManager()
             ->createQuery(
             'SELECT p, c FROM AppBundle:Product p
             JOIN p.category c

doctrine/event_listeners_subscribers.rst

@@ -165,7 +165,7 @@ interface and have an event method for each event it subscribes to::
 
         public function index(LifecycleEventArgs $args)
         {
-            $entity = $args->getEntity();
+            $entity = $args->getObject();
 
             // perhaps you only want to act on some "Product" entity
             if ($entity instanceof Product) {

form/button_based_validation.rst

@@ -36,4 +36,4 @@ large or whether you tried to submit text in a number field.
 .. seealso::
 
     To see how to use a service to resolve ``validation_groups`` dynamically
-    read the :doc:`/validation/group_service_resolver` article.
+    read the :doc:`/form/validation_group_service_resolver` article.

form/create_custom_field_type.rst

@@ -251,7 +251,7 @@ Using the Field Type
 You can now use your custom field type immediately, simply by creating a
 new instance of the type in one of your forms::
 
-    // src/AppBundle/Form/Type/AuthorType.php
+    // src/AppBundle/Form/Type/OrderType.php
     namespace AppBundle\Form\Type;
 
     use Symfony\Component\Form\AbstractType;

form/data_transformers.rst

@@ -23,7 +23,7 @@ Simple Example: Transforming String Tags from User Input to an Array
 
 Suppose you have a Task form with a tags ``text`` type::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Entity\Task;
@@ -56,7 +56,7 @@ This is a *perfect* time to attach a custom data transformer to the ``tags``
 field. The easiest way to do this is with the :class:`Symfony\\Component\\Form\\CallbackTransformer`
 class::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use Symfony\Component\Form\CallbackTransformer;
@@ -120,7 +120,7 @@ issue number.
 
 Start by setting up the text field like normal::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Entity\Task;
@@ -250,7 +250,7 @@ Next, you need to use the ``IssueToNumberTransformer`` object inside if ``TaskTy
 and add it to the ``issue`` field. No problem! Just add a ``__construct()`` method
 and type-hint the new class::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Form\DataTransformer\IssueToNumberTransformer;
@@ -374,7 +374,7 @@ have the data transformer *and* a nice default value for the ``invalid_message``
 As long as you're using :ref:`autowire <services-autowire>` and
 :ref:`autoconfigure <services-autoconfigure>`, you can start using the form immediately::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Form\DataTransformer\IssueToNumberTransformer;

form/dynamic_form_modification.rst

@@ -260,7 +260,7 @@ Customizing the Form Type
 Now that you have all the basics in place you can take advantage of the ``TokenStorageInterface``
 and fill in the listener logic::
 
-    // src/AppBundle/FormType/FriendMessageFormType.php
+    // src/AppBundle/Form/Type/FriendMessageFormType.php
 
     use AppBundle\Entity\User;
     use Doctrine\ORM\EntityRepository;
@@ -412,7 +412,6 @@ sport like this::
                         'class' => 'AppBundle:Position',
                         'placeholder' => '',
                         'choices' => $positions,
-                        'choices_as_values' => true,
                     ));
                 }
             );
@@ -469,7 +468,6 @@ The type would now look like::
                     'class' => 'AppBundle:Position',
                     'placeholder' => '',
                     'choices' => $positions,
-                    'choices_as_values' => true,
                 ));
             };
 

form/events.rst

@@ -84,8 +84,8 @@ View data        ``null``
 
 .. sidebar:: ``FormEvents::PRE_SET_DATA`` in the Form component
 
-    The ``collection`` form type relies on the
-    ``Symfony\Component\Form\Extension\Core\EventListener\ResizeFormListener``
+    The ``Symfony\Component\Form\Extension\Core\Type\CollectionType`` form type relies
+    on the ``Symfony\Component\Form\Extension\Core\EventListener\ResizeFormListener``
     subscriber, listening to the ``FormEvents::PRE_SET_DATA`` event in order
     to reorder the form's fields depending on the data from the pre-populated
     object, by removing and adding all form rows.
@@ -304,6 +304,7 @@ callback for better readability::
 
     use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+    use Symfony\Component\Form\FormEvent;
     use Symfony\Component\Form\FormEvents;
 
     // ...
@@ -391,9 +392,9 @@ Event subscribers have different uses:
 
 To register the event subscriber, use the ``addEventSubscriber()`` method::
 
+    use AppBundle\Form\EventListener\AddEmailFieldListener;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
-        use AppBundle\Form\EventListener\AddEmailFieldListener;
 
     // ...