Merge branch '3.4' into 4.0

* 3.4: (25 commits)
  Fixed merge errors
  Client's history clear alternative
  Don't mention the abandoned JMSTranslationBundle
  Reworded the console verbosity article to explain SHELL_VERBOSITY too
  Added a tip about tests and BCrypt
  Document that Doctrine associations don't work across different entity managers
  Update entity_provider.rst
  Reword
  Make require as a dev dependency
  Fixed invalid form validation reference
  use a class based service ID
  Merged new example in older example, removing some text
  Fix typo
  Document typed arrays in optionsresolver
  Fixed a wrong reference
  Document that Doctrine associations don't work across different entity managers
  Don't use OutputInterface::VERBOSITY constants, use PHP methods instead
  Mention the new behavior of dump() which returns the passed value
  Mentioned APP_ENV for Flex apps
  Updated LDAP documentation for Symfony 3.1
  ...

Author: javiereguiluz

best_practices/i18n.rst

@@ -36,9 +36,8 @@ XLIFF notes allow you to define that context.
 
 .. tip::
 
-    The Apache-licensed `JMSTranslationBundle`_ offers you a web interface for
-    viewing and editing these translation files. It also has advanced extractors
-    that can read your project and automatically update the XLIFF files.
+    The `PHP Translation Bundle`_ includes advanced extractors that can read
+    your project and automatically update the XLIFF files.
 
 Translation Keys
 ----------------
@@ -80,4 +79,4 @@ English in the application would be:
 
 Next: :doc:`/best_practices/security`
 
-.. _`JMSTranslationBundle`: https://github.com/schmittjoh/JMSTranslationBundle
+.. _`PHP Translation Bundle`: https://github.com/php-translation/symfony-bundle

components/browser_kit.rst

@@ -226,7 +226,7 @@ also delete all the cookies::
     $client = new Client();
     $client->request('GET', '/');
 
-    // delete history
+    // reset the client (history and cookies are cleared too)
     $client->restart();
 
 Learn more

components/ldap.rst

@@ -73,6 +73,52 @@ LDAP server), you may query the LDAP server using the
 
     // ...
 
-    $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $results = $query->execute();
+
+    foreach ($results as $entry) {
+        // Do something with the results
+    }
+
+By default, LDAP entries are lazy-loaded. If you wish to fetch
+all entries in a single call and do something with the results'
+array, you may use the
+:method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Collection::toArray` method::
+
+    // ...
+
+    $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $results = $query->execute()->toArray();
+
+    // Do something with the results array
+
+Creating or updating entries
+----------------------------
+
+Since version 3.1, The Ldap component provides means to create
+new LDAP entries, update or even delete existing ones::
+
+    use Symfony\Component\Ldap\Entry;
+    // ...
+
+    $entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', array(
+        'sn' => array('fabpot'),
+        'objectClass' => array('inetOrgPerson'),
+    ));
+
+    $em = $ldap->getEntryManager();
+
+    // Creating a new entry
+    $em->add($entry);
+
+    // Finding and updating an existing entry
+    $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))');
+    $result = $query->execute();
+    $entry = $result[0];
+    $entry->addAttribute('email', array('fabpot@symfony.com'));
+    $em->update($entry);
+
+    // Removing an existing entry
+    $em->remove(new Entry('cn=Test User,dc=symfony,dc=com'));
 
 .. _Packagist: https://packagist.org/packages/symfony/ldap

components/options_resolver.rst

@@ -317,14 +317,27 @@ correctly. To validate the types of the options, call
         public function configureOptions(OptionsResolver $resolver)
         {
             // ...
+
+            // specify one allowed type
             $resolver->setAllowedTypes('host', 'string');
+
+            // specify multiple allowed types
             $resolver->setAllowedTypes('port', array('null', 'int'));
+
+            // check all items in an array recursively for a type
+            $resolver->setAllowedTypes('dates', 'DateTime[]');
+            $resolver->setAllowedtypes('ports', 'int[]');
         }
     }
 
-For each option, you can define either just one type or an array of acceptable
-types. You can pass any type for which an ``is_<type>()`` function is defined
-in PHP. Additionally, you may pass fully qualified class or interface names.
+You can pass any type for which an ``is_<type>()`` function is defined in PHP.
+You may also pass fully qualified class or interface names (which is checked
+using ``instanceof``). Additionally, you can validate all items in an array
+recursively by suffixing the type with ``[]``.
+
+.. versionadded:: 3.4
+    Validating types of array items recursively was introduced in Symfony 3.4.
+    Prior to Symfony 3.4, only scalar values could be validated.
 
 If you pass an invalid option now, an
 :class:`Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException`

components/phpunit_bridge.rst

@@ -113,8 +113,25 @@ in the **Unsilenced** section of the deprecation report.
 Mark Tests as Legacy
 --------------------
 
-Add the ``@group legacy`` annotation to a test class or method to mark it
-as legacy.
+There are three ways to mark a test as legacy:
+
+* (**Recommended**) Add the ``@group legacy`` annotation to its class or method;
+
+* Make its class name start with the ``Legacy`` prefix;
+
+* Make its method name start with ``testLegacy*()`` instead of ``test*()``.
+
+.. note::
+
+    If your data provider calls code that would usually trigger a deprecation,
+    you can prefix its name with ``provideLegacy`` or ``getLegacy`` to silent
+    these deprecations. If your data provider does not execute deprecated
+    code, it is not required to choose a special naming just because the
+    test being fed by the data provider is marked as legacy.
+
+    Also be aware that choosing one of the two legacy prefixes will not mark
+    tests as legacy that make use of this data provider. You still have to
+    mark them as legacy tests explicitly.
 
 Configuration
 -------------

components/var_dumper.rst

@@ -50,6 +50,9 @@ For example::
 
     dump($someVar);
 
+    // dump() returns the passed value, so you can dump an object and keep using it
+    dump($someObject)->someMethod();
+
 By default, the output format and destination are selected based on your
 current PHP SAPI:
 

console/verbosity.rst

@@ -1,18 +1,41 @@
 Verbosity Levels
 ================
 
-The console has five verbosity levels. These are defined in the
-:class:`Symfony\\Component\\Console\\Output\\OutputInterface`:
-
-===========================================  ==================================  =====================
-Value                                        Meaning                             Console option
-===========================================  ==================================  =====================
-``OutputInterface::VERBOSITY_QUIET``         Do not output any messages          ``-q`` or ``--quiet``
-``OutputInterface::VERBOSITY_NORMAL``        The default verbosity level         (none)
-``OutputInterface::VERBOSITY_VERBOSE``       Increased verbosity of messages     ``-v``
-``OutputInterface::VERBOSITY_VERY_VERBOSE``  Informative non essential messages  ``-vv``
-``OutputInterface::VERBOSITY_DEBUG``         Debug messages                      ``-vvv``
-===========================================  ==================================  =====================
+Console commands have different verbosity levels, which determine the messages
+displayed in their output. By default, commands display only the most useful
+messages, but you can control their verbosity with the ``-q`` and ``-v`` options:
+
+.. code-block:: terminal
+
+    # do not output any message (not even the command result messages)
+    $ php bin/console some-command -q
+    $ php bin/console some-command --quiet
+
+    # normal behavior, no option required (display only the useful messages)
+    $ php bin/console some-command
+
+    # increase verbosity of messages
+    $ php bin/console some-command -v
+
+    # display also the informative non essential messages
+    $ php bin/console some-command -vv
+
+    # display all messages (useful to debug errors)
+    $ php bin/console some-command -vvv
+
+The verbosity level can also be controlled globally for all commands with the
+``SHELL_VERBOSITY`` environment variable (the ``-q`` and ``-v`` options still
+have more precedence over the value of ``SHELL_VERBOSITY``):
+
+=====================  =========================  ===========================================
+Console option         ``SHELL_VERBOSITY`` value  Equivalent PHP constant
+=====================  =========================  ===========================================
+``-q`` or ``--quiet``  ``-1``                     ``OutputInterface::VERBOSITY_QUIET``
+(none)                 ``0``                      ``OutputInterface::VERBOSITY_NORMAL``
+``-v``                 ``1``                      ``OutputInterface::VERBOSITY_VERBOSE``
+``-vv``                ``2``                      ``OutputInterface::VERBOSITY_VERY_VERBOSE``
+``-vvv``               ``3``                      ``OutputInterface::VERBOSITY_DEBUG``
+=====================  =========================  ===========================================
 
 It is possible to print a message in a command for only a specific verbosity
 level. For example::
@@ -31,38 +54,19 @@ level. For example::
                 'Password: '.$input->getArgument('password'),
             ));
 
-            // the user class is only printed when the verbose verbosity level is used
-            if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
+            // available methods: ->isQuiet(), ->isVerbose(), ->isVeryVerbose(), ->isDebug()
+            if ($output->isVerbose()) {
                 $output->writeln('User class: '.get_class($user));
             }
 
-            // alternatively you can pass the verbosity level to writeln()
+            // alternatively you can pass the verbosity level PHP constant to writeln()
             $output->writeln(
                 'Will only be printed in verbose mode or higher',
                 OutputInterface::VERBOSITY_VERBOSE
             );
         }
     }
 
-There are also more semantic methods you can use to test for each of the
-verbosity levels::
-
-    if ($output->isQuiet()) {
-        // ...
-    }
-
-    if ($output->isVerbose()) {
-        // ...
-    }
-
-    if ($output->isVeryVerbose()) {
-        // ...
-    }
-
-    if ($output->isDebug()) {
-        // ...
-    }
-
 When the quiet level is used, all output is suppressed as the default
 :method:`Symfony\\Component\\Console\\Output\\Output::write` method returns
 without actually printing.

deployment.rst

@@ -156,8 +156,9 @@ as you normally do:
 .. caution::
 
     If you get a "class not found" error during this step, you may need to
-    run ``export SYMFONY_ENV=prod`` before running this command so that
-    the ``post-install-cmd`` scripts run in the ``prod`` environment.
+    run ``export SYMFONY_ENV=prod`` (or ``export APP_ENV=prod`` if you're
+    using :doc:`Symfony Flex </setup/flex>`) before running this command so
+    that the ``post-install-cmd`` scripts run in the ``prod`` environment.
 
 D) Clear your Symfony Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doctrine/multiple_entity_managers.rst

@@ -16,6 +16,12 @@ entity manager that connects to another database might handle the rest.
     usually required. Be sure you actually need multiple entity managers before
     adding in this layer of complexity.
 
+.. caution::
+
+    Entities cannot define associations across different entity managers. If you
+    need that, there are `several alternatives <https://stackoverflow.com/a/11494543/2804294>`_
+    that require some custom setup.
+
 The following configuration code shows how you can configure two entity managers:
 
 .. configuration-block::

form/disabling_validation.rst

@@ -18,5 +18,10 @@ these cases you can set the ``validation_groups`` option to ``false``::
 
 Note that when you do that, the form will still run basic integrity checks,
 for example whether an uploaded file was too large or whether non-existing
-fields were submitted. If you want to suppress validation, you can use the
-:ref:`POST_SUBMIT event <form-dynamic-form-modification-suppressing-form-validation>`.
+fields were submitted.
+
+The submission of extra form fields can be controlled with the
+`allow_extra_fields config option`_ and the maximum upload file size should be
+handled via your PHP and web server configuration.
+
+.. _`allow_extra_fields config option`: https://symfony.com/doc/current/reference/forms/types/form.html#allow-extra-fields

form/dynamic_form_modification.rst

@@ -613,11 +613,3 @@ field according to the current selection in the ``sport`` field:
 The major benefit of submitting the whole form to just extract the updated
 ``position`` field is that no additional server-side code is needed; all the
 code from above to generate the submitted form can be reused.
-
-.. _form-dynamic-form-modification-suppressing-form-validation:
-
-Suppressing Form Validation
----------------------------
-
-To suppress form validation, set ``validation_groups`` to ``false`` or an empty
-array.

logging/monolog_console.rst

@@ -11,19 +11,18 @@ is passed when a command gets executed.
 
 When a lot of logging has to happen, it's cumbersome to print information
 depending on the verbosity settings (``-v``, ``-vv``, ``-vvv``) because the
-calls need to be wrapped in conditions. The code quickly gets verbose or dirty.
-For example::
+calls need to be wrapped in conditions. For example::
 
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
 
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        if ($output->getVerbosity() >= OutputInterface::VERBOSITY_DEBUG) {
+        if ($output->isDebug()) {
             $output->writeln('Some info');
         }
 
-        if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
+        if ($output->isVerbose()) {
             $output->writeln('Some more info');
         }
     }

reference/configuration/security.rst

@@ -595,6 +595,12 @@ persisting the encoded password alone is enough.
     All the encoded passwords are ``60`` characters long, so make sure to
     allocate enough space for them to be persisted.
 
+.. tip::
+
+    A simple technique to make tests much faster when using BCrypt is to set
+    the cost to ``4``, which is the minimum value allowed, in the ``test``
+    environment configuration.
+
     .. _reference-security-firewall-context:
 
 Firewall Context

service_container/3.3-di-changes.rst

@@ -618,8 +618,13 @@ Start by updating the service ids to class names:
 
     Services associated with global PHP classes (i.e. not using PHP namespaces)
     must maintain the ``class`` parameter. For example, when using the old Twig
+<<<<<<< HEAD
+    classes (e.g. ``Twig_Extensions_Extension_Intl`` instead of ``Twig\Extensions\IntlExtension``)
+    you can't redefine the service as `Twig_Extensions_Extension_Intl: ~` and
+=======
     classes (e.g. ``Twig_Extensions_Extension_Intl`` instead of ``Twig\Extensions\IntlExtension``),
     you can't redefine the service as ``Twig_Extensions_Extension_Intl: ~`` and
+>>>>>>> upstream/3.3
     you must keep the original ``class`` parameter.
 
 But, this change will break our app! The old service ids (e.g. ``app.github_notifier``)

service_container/compiler_passes.rst

@@ -8,7 +8,7 @@ How to Work with Compiler Passes
 Compiler passes give you an opportunity to manipulate other service
 definitions that have been registered with the service container. You
 can read about how to create them in the components section
-":ref:`components-di-compiler-pass`".
+":ref:`components-di-separate-compiler-passes`".
 
 Compiler passes are registered in the ``build()`` method of the application kernel::
 

service_container/factories.rst

@@ -146,8 +146,7 @@ Configuration of the service container then looks like this:
     .. code-block:: yaml
 
         # config/services.yaml
-        app.newsletter_manager:
-            class: App\Email\NewsletterManager
+        AppBundle\Email\NewsletterManager:
             # new syntax
             factory: 'App\Email\NewsletterManagerFactory:createNewsletterManager'
             # old syntax

setup/built_in_web_server.rst

@@ -27,7 +27,7 @@ First, execute this command:
 .. code-block:: terminal
 
     $ cd your-project/
-    $ composer require symfony/web-server-bundle
+    $ composer require --dev symfony/web-server-bundle
 
 Then, enable the bundle in the kernel of the application::