Merge branch '2.3' into 2.7

Author: xabbuh

best_practices/forms.rst

@@ -49,11 +49,17 @@ form in its own PHP class::
         }
     }
 
+.. best-practice::
+
+    Put the form type classes in the ``AppBundle\Form`` namespace, unless you
+    use other custom form classes like data transformers.
+
 To use the class, use ``createForm`` and instantiate the new class::
 
-    use AppBundle\Form\PostType;
     // ...
+    use AppBundle\Form\PostType;
 
+    // ...
     public function newAction(Request $request)
     {
         $post = new Post();

book/validation.rst

@@ -644,7 +644,7 @@ this method must return ``true``:
         AppBundle\Entity\Author:
             getters:
                 passwordLegal:
-                    - 'True': { message: 'The password cannot match your first name' }
+                    - 'IsTrue': { message: 'The password cannot match your first name' }
 
     .. code-block:: xml
 
@@ -656,7 +656,7 @@ this method must return ``true``:
 
             <class name="AppBundle\Entity\Author">
                 <getter property="passwordLegal">
-                    <constraint name="True">
+                    <constraint name="IsTrue">
                         <option name="message">The password cannot match your first name</option>
                     </constraint>
                 </getter>
@@ -954,7 +954,7 @@ username and the password are different only if all other validation passes
                 - Strict
             getters:
                 passwordLegal:
-                    - 'True':
+                    - 'IsTrue':
                         message: 'The password cannot match your username'
                         groups: [Strict]
             properties:
@@ -981,7 +981,7 @@ username and the password are different only if all other validation passes
                 </property>
 
                 <getter property="passwordLegal">
-                    <constraint name="True">
+                    <constraint name="IsTrue">
                         <option name="message">The password cannot match your username</option>
                         <option name="groups">
                             <value>Strict</value>

contributing/code/_api_tagging.rst.inc

@@ -74,8 +74,6 @@ backwards compatibility promise:
 | Add a default value to an argument            | Yes                         |
 +-----------------------------------------------+-----------------------------+
 
-.. include:: _api_tagging.rst.inc
-
 Using our Classes
 ~~~~~~~~~~~~~~~~~
 
@@ -134,8 +132,6 @@ covered by our backwards compatibility promise:
 | Access a private property (via Reflection)    | No                          |
 +-----------------------------------------------+-----------------------------+
 
-.. include:: _api_tagging.rst.inc
-
 Working on Symfony Code
 -----------------------
 

contributing/code/bc.rst

@@ -50,6 +50,18 @@ example containing most features described below:
             $this->fooBar = $this->transformText($dummy);
         }
 
+        /**
+         * @return string
+         *
+         * @deprecated
+         */
+        public function someDeprecatedMethod()
+        {
+            @trigger_error(sprintf('The %s() method is deprecated since version 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
+
+            return Baz::someMethod();
+        }
+
         /**
          * Transforms the input given as first argument.
          *
@@ -151,7 +163,11 @@ Structure
 * Use parentheses when instantiating classes regardless of the number of
   arguments the constructor has;
 
-* Exception message strings should be concatenated using :phpfunction:`sprintf`.
+* Exception and error message strings should be concatenated using :phpfunction:`sprintf`.
+
+* Calls to :phpfunction:`trigger_error` with type ``E_USER_DEPRECATED`` should be
+  switched to opt-in via ``@`` operator.
+  Read more at :ref:`contributing-code-conventions-deprecations`;
 
 Naming Conventions
 ------------------

contributing/code/standards.rst

@@ -55,10 +55,17 @@ swiftmailer with the memory option, use the following configuration:
             'spool' => array('type' => 'memory')
         ));
 
-Spool Using a File
+.. _spool-using-a-file:
+
+Spool Using Files
 ------------------
 
-In order to use the spool with a file, use the following configuration:
+When you use the filesystem for spooling, Symfony creates a folder in the given 
+path for each mail service (e.g. "default" for the default service). This folder
+will contain files for each email in the spool. So make sure this directory is 
+writable by Symfony (or your webserver/php)!
+
+In order to use the spool with files, use the following configuration:
 
 .. configuration-block::
 
@@ -69,7 +76,7 @@ In order to use the spool with a file, use the following configuration:
             # ...
             spool:
                 type: file
-                path: /path/to/spool
+                path: /path/to/spooldir
 
     .. code-block:: xml
 
@@ -84,7 +91,7 @@ In order to use the spool with a file, use the following configuration:
             <swiftmailer:config>
                 <swiftmailer:spool
                     type="file"
-                    path="/path/to/spool"
+                    path="/path/to/spooldir"
                 />
             </swiftmailer:config>
         </container>
@@ -97,7 +104,7 @@ In order to use the spool with a file, use the following configuration:
 
             'spool' => array(
                 'type' => 'file',
-                'path' => '/path/to/spool',
+                'path' => '/path/to/spooldir',
             ),
         ));
 

cookbook/email/spool.rst

@@ -687,7 +687,7 @@ customize the ``name`` field only:
 
         <!-- app/Resources/views/Form/_product_name_widget.html.php -->
         <div class="text_widget">
-              echo $view['form']->block('form_widget_simple') ?>
+            <?php echo $view['form']->block('form_widget_simple') ?>
         </div>
 
 Here, the ``_product_name_widget`` fragment defines the template to use for the

cookbook/form/form_customization.rst

@@ -165,10 +165,10 @@ It often happens that you use some options that are added by
 :doc:`form extensions </cookbook/form/create_form_type_extension>`. One of the
 cases may be the ``ValidatorExtension`` with its ``invalid_message`` option.
 The ``TypeTestCase`` only loads the core form extension, which means an
-"Invalid option" exception will be raised if you try to test a class that
-depends on other extensions. The
-:method:`Symfony\\Component\\Form\\Test\\TypeTestCase::getExtensions` allows you to
-return a list of extensions to register::
++:class:`Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException`
++will be raised if you try to test a class that depends on other extensions.
++The :method:`Symfony\\Component\\Form\\Test\\TypeTestCase::getExtensions` method
++allows you to return a list of extensions to register::
 
     // src/AppBundle/Tests/Form/Type/TestedTypeTests.php
     namespace AppBundle\Tests\Form\Type;

cookbook/form/unit_testing.rst

@@ -135,6 +135,12 @@ For more details, read the article `Checking in front-end dependencies`_.
 But, it's very possible that Bower will add a lock feature in the future
 (e.g. `bower/bower#1748`_).
 
+If you don't care too much about having *exact* the same versions, you can only
+commit the ``bower.json`` file. Running ``bower install`` will give you the
+latest versions within the specified version range of each package in
+``bower.json``. Using strict version constraints (e.g. ``1.10.*``) is often
+enough to ensure only bringing in compatible versions.
+
 .. _Bower: http://bower.io
 .. _`Node.js`: https://nodejs.org
 .. _BowerPHP: http://bowerphp.org/