Merge branch '2.8' into 3.0

* 2.8:
  [#6597] some tweaks
  [Validator] Add shorter examples using the default option
  Typo fix
  Add missing parameter
  Updated the CS rule about return null; and return;
  [#6690] fix syntax error
  Update date.rst - Fixes typo
  [#6690] add versionadded directive
  Added an example for a different method of verbosity level usage.
  NullOutput should be passed to $command->run()
  Hard values for the driver option
  Fix ldap security examples

Author: xabbuh

book/doctrine.rst

@@ -43,7 +43,6 @@ information. By convention, this information is usually configured in an
 
     # app/config/parameters.yml
     parameters:
-        database_driver:    pdo_mysql
         database_host:      localhost
         database_name:      test_project
         database_user:      root
@@ -64,7 +63,7 @@ information. By convention, this information is usually configured in an
             # app/config/config.yml
             doctrine:
                 dbal:
-                    driver:   '%database_driver%'
+                    driver:   pdo_mysql
                     host:     '%database_host%'
                     dbname:   '%database_name%'
                     user:     '%database_user%'
@@ -84,7 +83,7 @@ information. By convention, this information is usually configured in an
 
                 <doctrine:config>
                     <doctrine:dbal
-                        driver="%database_driver%"
+                        driver="pdo_mysql"
                         host="%database_host%"
                         dbname="%database_name%"
                         user="%database_user%"
@@ -97,7 +96,7 @@ information. By convention, this information is usually configured in an
             // app/config/config.php
             $configuration->loadFromExtension('doctrine', array(
                 'dbal' => array(
-                    'driver'   => '%database_driver%',
+                    'driver'   => 'pdo_mysql',
                     'host'     => '%database_host%',
                     'dbname'   => '%database_name%',
                     'user'     => '%database_user%',

components/console/introduction.rst

@@ -225,6 +225,13 @@ level. For example::
         $output->writeln(...);
     }
 
+    // alternatively you can pass the verbosity level to writeln()
+    $output->writeln('...', OutputInterface::VERBOSITY_VERBOSE);
+
+.. versionadded:: 2.8
+    The ability to pass the verbosity level to the ``writeln()`` method was
+    introduced in Symfony 2.8.
+
 There are also more semantic methods you can use to test for each of the
 verbosity levels::
 
@@ -548,7 +555,7 @@ returns the returned code from the command (return value from command's
 
     If you want to suppress the output of the executed command, pass a
     :class:`Symfony\\Component\\Console\\Output\\NullOutput` as the second
-    argument to ``$command->execute()``.
+    argument to ``$command->run()``.
 
 .. caution::
 

contributing/code/standards.rst

@@ -91,7 +91,7 @@ example containing most features described below:
             );
 
             if (true === $dummy) {
-                return;
+                return null;
             }
 
             if ('string' === $dummy) {
@@ -109,7 +109,7 @@ example containing most features described below:
          * @param mixed $value     Some value to check against
          * @param bool  $theSwitch Some switch to control the method's flow
          *
-         * @return bool|null The resultant check if $theSwitch isn't false, null otherwise
+         * @return bool|void The resultant check if $theSwitch isn't false, void otherwise
          */
         private function reverseBoolean($value = null, $theSwitch = false)
         {
@@ -143,8 +143,8 @@ Structure
 * Add a blank line before ``return`` statements, unless the return is alone
   inside a statement-group (like an ``if`` statement);
 
-* Use just ``return;`` instead of ``return null;`` when a function must return
-  void early;
+* Use ``return null;`` when a function explicitly returns ``null`` values and
+  use ``return;`` when the function returns ``void`` values;
 
 * Use braces to indicate control structure body regardless of the number of
   statements it contains;

cookbook/configuration/micro-kernel-trait.rst

@@ -195,7 +195,7 @@ to hold the kernel. Now it looks like this::
             // load the annotation routes
             $routes->mount(
                 '/',
-                $routes->import(__DIR__.'/../src/App/Controller/', 'annotation')
+                $routes->import(__DIR__.'/../src/App/Controller/', '/', 'annotation')
             );
         }
     }

cookbook/doctrine/multiple_entity_managers.rst

@@ -27,15 +27,15 @@ The following configuration code shows how you can configure two entity managers
                 default_connection: default
                 connections:
                     default:
-                        driver:   '%database_driver%'
+                        driver:   pdo_mysql
                         host:     '%database_host%'
                         port:     '%database_port%'
                         dbname:   '%database_name%'
                         user:     '%database_user%'
                         password: '%database_password%'
                         charset:  UTF8
                     customer:
-                        driver:   '%database_driver2%'
+                        driver:   pdo_mysql
                         host:     '%database_host2%'
                         port:     '%database_port2%'
                         dbname:   '%database_name2%'
@@ -68,7 +68,7 @@ The following configuration code shows how you can configure two entity managers
             <config>
                 <dbal default-connection="default">
                     <connection name="default"
-                        driver="%database_driver%"
+                        driver="pdo_mysql"
                         host="%database_host%"
                         port="%database_port%"
                         dbname="%database_name%"
@@ -78,7 +78,7 @@ The following configuration code shows how you can configure two entity managers
                     />
 
                     <connection name="customer"
-                        driver="%database_driver2%"
+                        driver="pdo_mysql"
                         host="%database_host2%"
                         port="%database_port2%"
                         dbname="%database_name2%"
@@ -108,7 +108,7 @@ The following configuration code shows how you can configure two entity managers
                 'default_connection' => 'default',
                 'connections' => array(
                     'default' => array(
-                        'driver'   => '%database_driver%',
+                        'driver'   => 'pdo_mysql',
                         'host'     => '%database_host%',
                         'port'     => '%database_port%',
                         'dbname'   => '%database_name%',
@@ -117,7 +117,7 @@ The following configuration code shows how you can configure two entity managers
                         'charset'  => 'UTF8',
                     ),
                     'customer' => array(
-                        'driver'   => '%database_driver2%',
+                        'driver'   => 'pdo_mysql',
                         'host'     => '%database_host2%',
                         'port'     => '%database_port2%',
                         'dbname'   => '%database_name2%',

cookbook/security/ldap.rst

@@ -287,7 +287,7 @@ Configuration example for form login
                     # ...
                     form_login_ldap:
                         login_path: login
-                        login_check: login_check
+                        check_path: login_check
                         # ...
                         service: ldap
                         dn_string: 'uid={username},dc=example,dc=com'
@@ -306,7 +306,7 @@ Configuration example for form login
                 <firewall name="main">
                     <form-login-ldap
                             login-path="login"
-                            login-check="login_check"
+                            check-path="login_check"
                             service="ldap"
                             dn-string="uid={username},dc=example,dc=com" />
                 </firewall>
@@ -320,7 +320,7 @@ Configuration example for form login
                 'main' => array(
                     'form_login_ldap' => array(
                         'login_path' => 'login',
-                        'login_check' => 'login_check',
+                        'check_path' => 'login_check',
                         'service' => 'ldap',
                         'dn_string' => 'uid={username},dc=example,dc=com',
                         // ...

cookbook/session/php_bridge.rst

@@ -8,7 +8,7 @@ If you're integrating the Symfony full-stack Framework into a legacy application
 that starts the session with ``session_start()``, you may still be able to
 use Symfony's session management by using the PHP Bridge session.
 
-If the application has sets it's own PHP save handler, you can specify null
+If the application has it's own PHP save handler, you can specify null
 for the ``handler_id``:
 
 .. configuration-block::

reference/constraints/Choice.rst

@@ -46,6 +46,11 @@ If your valid choice list is simple, you can pass them in directly via the
 
         class Author
         {
+            /**
+             * @Assert\Choice({"New York", "Berlin", "Tokyo"})
+             */
+            protected $city;
+
             /**
              * @Assert\Choice(choices = {"male", "female"}, message = "Choose a valid gender.")
              */
@@ -57,6 +62,7 @@ If your valid choice list is simple, you can pass them in directly via the
         # src/AppBundle/Resources/config/validation.yml
         AppBundle\Entity\Author:
             properties:
+                city: [New York, Berlin, Tokyo]
                 gender:
                     - Choice:
                         choices:  [male, female]
@@ -71,6 +77,13 @@ If your valid choice list is simple, you can pass them in directly via the
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="AppBundle\Entity\Author">
+                <property name="city">
+                    <constraint name="Choice">
+                        <value>New York</value>
+                        <value>Berlin</value>
+                        <value>Tokyo</value>
+                    </constraint>
+                </property>
                 <property name="gender">
                     <constraint name="Choice">
                         <option name="choices">
@@ -97,6 +110,11 @@ If your valid choice list is simple, you can pass them in directly via the
 
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
+                $metadata->addPropertyConstraint(
+                    'gender',
+                     new Assert\Choice(array('New York', 'Berlin', 'Tokyo'))
+                 );
+
                 $metadata->addPropertyConstraint('gender', new Assert\Choice(array(
                     'choices' => array('male', 'female'),
                     'message' => 'Choose a valid gender.',

reference/constraints/EqualTo.rst

@@ -25,8 +25,8 @@ To force that a value is *not* equal, see :doc:`/reference/constraints/NotEqualT
 Basic Usage
 -----------
 
-If you want to ensure that the ``age`` of a ``Person`` class is equal to
-``20``, you could do the following:
+If you want to ensure that the ``firstName`` of a ``Person`` class is equal to ``Mary``
+and that the ``age`` is ``20``, you could do the following:
 
 .. configuration-block::
 
@@ -39,6 +39,11 @@ If you want to ensure that the ``age`` of a ``Person`` class is equal to
 
         class Person
         {
+            /**
+             * @Assert\EqualTo("Mary")
+             */
+            protected $firstName;
+
             /**
              * @Assert\EqualTo(
              *     value = 20
@@ -52,6 +57,8 @@ If you want to ensure that the ``age`` of a ``Person`` class is equal to
         # src/AppBundle/Resources/config/validation.yml
         AppBundle\Entity\Person:
             properties:
+                firstName:
+                    - EqualTo: Mary
                 age:
                     - EqualTo:
                         value: 20
@@ -65,6 +72,11 @@ If you want to ensure that the ``age`` of a ``Person`` class is equal to
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="AppBundle\Entity\Person">
+                <property name="firstName">
+                    <constraint name="EqualTo">
+                        <value>Mary</value>
+                    </constraint>
+                </property>
                 <property name="age">
                     <constraint name="EqualTo">
                         <option name="value">20</option>
@@ -85,6 +97,8 @@ If you want to ensure that the ``age`` of a ``Person`` class is equal to
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
+                $metadata->addPropertyConstraint('firstName', new Assert\EqualTo('Mary'));
+
                 $metadata->addPropertyConstraint('age', new Assert\EqualTo(array(
                     'value' => 20,
                 )));

reference/constraints/GreaterThan.rst

@@ -21,8 +21,10 @@ than another value, see :doc:`/reference/constraints/LessThan`.
 Basic Usage
 -----------
 
-If you want to ensure that the ``age`` of a ``Person`` class is greater than
-``18``, you could do the following:
+The following constraints ensure that:
+
+* the number of ``siblings`` of a ``Person`` is greater than ``5``
+* the ``age`` of a ``Person`` class is greater than ``18``
 
 .. configuration-block::
 
@@ -35,6 +37,12 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than
 
         class Person
         {
+
+            /**
+             * @Assert\GreaterThan(5)
+             */
+            protected $siblings;
+
             /**
              * @Assert\GreaterThan(
              *     value = 18
@@ -48,6 +56,8 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than
         # src/AppBundle/Resources/config/validation.yml
         AppBundle\Entity\Person:
             properties:
+                siblings:
+                    - GreaterThan: 5
                 age:
                     - GreaterThan:
                         value: 18
@@ -61,6 +71,11 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="AppBundle\Entity\Person">
+                <property name="siblings">
+                    <constraint name="GreaterThan">
+                        <value>5</value>
+                    </constraint>
+                </property>
                 <property name="age">
                     <constraint name="GreaterThan">
                         <option name="value">18</option>
@@ -81,6 +96,8 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
+                $metadata->addPropertyConstraint('siblings', new Assert\GreaterThan(5));
+
                 $metadata->addPropertyConstraint('age', new Assert\GreaterThan(array(
                     'value' => 18,
                 )));

reference/constraints/GreaterThanOrEqual.rst

@@ -20,8 +20,10 @@ the options. To force that a value is greater than another value, see
 Basic Usage
 -----------
 
-If you want to ensure that the ``age`` of a ``Person`` class is greater than
-or equal to ``18``, you could do the following:
+The following constraints ensure that:
+
+* the number of ``siblings`` of a ``Person`` is greater than or equal to ``5``
+* the ``age`` of a ``Person`` class is greater than or equal to ``18``
 
 .. configuration-block::
 
@@ -34,6 +36,11 @@ or equal to ``18``, you could do the following:
 
         class Person
         {
+            /**
+             * @Assert\GreaterThanOrEqual(5)
+             */
+            protected $siblings;
+
             /**
              * @Assert\GreaterThanOrEqual(
              *     value = 18
@@ -47,6 +54,8 @@ or equal to ``18``, you could do the following:
         # src/AppBundle/Resources/config/validation.yml
         AppBundle\Entity\Person:
             properties:
+                siblings:
+                    - GreaterThanOrEqual: 5
                 age:
                     - GreaterThanOrEqual:
                         value: 18
@@ -60,6 +69,11 @@ or equal to ``18``, you could do the following:
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="AppBundle\Entity\Person">
+                <property name="siblings">
+                    <constraint name="GreaterThanOrEqual">
+                        <value>5</value>
+                    </constraint>
+                </property>
                 <property name="age">
                     <constraint name="GreaterThanOrEqual">
                         <option name="value">18</option>
@@ -80,6 +94,8 @@ or equal to ``18``, you could do the following:
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
+                $metadata->addPropertyConstraint('siblings', new Assert\GreaterThanOrEqual(5));
+
                 $metadata->addPropertyConstraint('age', new Assert\GreaterThanOrEqual(array(
                     'value' => 18,
                 )));