Merge branch '2.8' into 3.4

* 2.8:
  Use gender-neutral language in the main Serializer article
  Removed the term "simple" from creating a new page
  Update datetime.rst
  components/phpunit_bridge.rst
  Add best practice note about version
  Use is_numeric()
  drop deprecated config value
  [Console] Fix SymfonyStyle::ask usage
  Update BC policy to tell about adding/removing return types

Author: javiereguiluz

components/phpunit_bridge.rst

@@ -28,12 +28,19 @@ Installation
 
 .. code-block:: terminal
 
-    $ composer require --dev symfony/phpunit-bridge
+    $ composer require --dev "symfony/phpunit-bridge:*"
 
 Alternatively, you can clone the `<https://github.com/symfony/phpunit-bridge>`_ repository.
 
 .. include:: /components/require_autoload.rst.inc
 
+.. note::
+
+    The PHPUnit bridge is designed to work with all maintained versions of
+    Symfony components, even across different major versions of them. You should
+    always use its very latest stable major version to get the most accurate
+    deprecation report.
+
 If you plan to :ref:`write-assertions-about-deprecations` and use the regular
 PHPUnit script (not the modified PHPUnit script provided by Symfony), you have
 to register a new `test listener`_ called ``SymfonyTestsListener``:

components/serializer.rst

@@ -13,9 +13,9 @@ simple schema.
 
 .. image:: /_images/components/serializer/serializer_workflow.png
 
-As you can see in the picture above, an array is used as a man in
-the middle. This way, Encoders will only deal with turning specific
-**formats** into **arrays** and vice versa. The same way, Normalizers
+As you can see in the picture above, an array is used as an intermediary between
+objects and serialized contents. This way, encoders will only deal with turning
+specific **formats** into **arrays** and vice versa. The same way, Normalizers
 will deal with turning specific **objects** into **arrays** and vice versa.
 
 Serialization is a complex topic. This component may not cover all your use cases out of the box,
@@ -63,13 +63,13 @@ Serializing an Object
 For the sake of this example, assume the following class already
 exists in your project::
 
-    namespace Acme;
+    namespace App\Model;
 
     class Person
     {
         private $age;
         private $name;
-        private $sportsman;
+        private $sportsperson;
         private $createdAt;
 
         // Getters
@@ -89,9 +89,9 @@ exists in your project::
         }
 
         // Issers
-        public function isSportsman()
+        public function isSportsperson()
         {
-            return $this->sportsman;
+            return $this->sportsperson;
         }
 
         // Setters
@@ -105,9 +105,9 @@ exists in your project::
             $this->age = $age;
         }
 
-        public function setSportsman($sportsman)
+        public function setSportsperson($sportsperson)
         {
-            $this->sportsman = $sportsman;
+            $this->sportsperson = $sportsperson;
         }
 
         public function setCreatedAt($createdAt)
@@ -119,14 +119,14 @@ exists in your project::
 Now, if you want to serialize this object into JSON, you only need to
 use the Serializer service created before::
 
-    $person = new Acme\Person();
+    $person = new App\Model\Person();
     $person->setName('foo');
     $person->setAge(99);
-    $person->setSportsman(false);
+    $person->setSportsperson(false);
 
     $jsonContent = $serializer->serialize($person, 'json');
 
-    // $jsonContent contains {"name":"foo","age":99,"sportsman":false}
+    // $jsonContent contains {"name":"foo","age":99,"sportsperson":false}
 
     echo $jsonContent; // or return it in a Response
 
@@ -140,13 +140,13 @@ Deserializing an Object
 You'll now learn how to do the exact opposite. This time, the information
 of the ``Person`` class would be encoded in XML format::
 
-    use Acme\Person;
+    use App\Model\Person;
 
     $data = <<<EOF
     <person>
         <name>foo</name>
         <age>99</age>
-        <sportsman>false</sportsman>
+        <sportsperson>false</sportsperson>
     </person>
     EOF;
 
@@ -191,7 +191,7 @@ The serializer can also be used to update an existing object::
     $person = new Person();
     $person->setName('bar');
     $person->setAge(99);
-    $person->setSportsman(true);
+    $person->setSportsperson(true);
 
     $data = <<<EOF
     <person>
@@ -201,7 +201,7 @@ The serializer can also be used to update an existing object::
     EOF;
 
     $serializer->deserialize($data, Person::class, 'xml', array('object_to_populate' => $person));
-    // $person = Acme\Person(name: 'foo', age: '69', sportsman: true)
+    // $person = App\Model\Person(name: 'foo', age: '69', sportsperson: true)
 
 This is a common need when working with an ORM.
 
@@ -404,7 +404,7 @@ method on the normalizer definition::
     $encoder = new JsonEncoder();
 
     $serializer = new Serializer(array($normalizer), array($encoder));
-    $serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsman":false}
+    $serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsperson":false}
 
 .. _component-serializer-converting-property-names-when-serializing-and-deserializing:
 
@@ -516,8 +516,8 @@ Serializing Boolean Attributes
 ------------------------------
 
 If you are using isser methods (methods prefixed by ``is``, like
-``Acme\Person::isSportsman()``), the Serializer component will automatically
-detect and use it to serialize related attributes.
+``App\Model\Person::isSportsperson()``), the Serializer component will
+automatically detect and use it to serialize related attributes.
 
 The ``ObjectNormalizer`` also takes care of methods starting with ``has``, ``add``
 and ``remove``.
@@ -527,7 +527,7 @@ Using Callbacks to Serialize Properties with Object Instances
 
 When serializing, you can set a callback to format a specific object property::
 
-    use Acme\Person;
+    use App\Model\Person;
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
     use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
     use Symfony\Component\Serializer\Serializer;

console/style.rst

@@ -235,11 +235,11 @@ User Input Methods
     the third argument::
 
         $io->ask('Number of workers to start', 1, function ($number) {
-            if (!is_integer($number)) {
-                throw new \RuntimeException('You must type an integer.');
+            if (!is_numeric($number)) {
+                throw new \RuntimeException('You must type a number.');
             }
 
-            return $number;
+            return (int) $number;
         });
 
 :method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::askHidden`

contributing/code/bc.rst

@@ -82,6 +82,8 @@ backward compatibility promise:
 +-----------------------------------------------+-----------------------------+
 | Add a default value to an argument            | Yes                         |
 +-----------------------------------------------+-----------------------------+
+| Add a return type to an implemented method    | Yes                         |
++-----------------------------------------------+-----------------------------+
 
 Using our Classes
 ~~~~~~~~~~~~~~~~~
@@ -173,6 +175,8 @@ Remove default value of an argument             No
 Add type hint to an argument                    No
 Remove type hint of an argument                 No
 Change argument type                            No
+Add return type                                 No
+Remove return type                              No [9]_
 Change return type                              No
 **Constants**
 Add constant                                    Yes
@@ -229,6 +233,8 @@ Remove default value of an argument                 No
 Add type hint to an argument                        No [7]_ [8]_
 Remove type hint of an argument                     No [7]_ [8]_
 Change argument type                                No [7]_ [8]_
+Add return type                                     No [7]_ [8]_
+Remove return type                                  No [7]_ [8]_ [9]_
 Change return type                                  No [7]_ [8]_
 **Protected Methods**
 Add protected method                                Yes
@@ -244,6 +250,8 @@ Remove default value of an argument                 No [7]_
 Add type hint to an argument                        No [7]_ [8]_
 Remove type hint of an argument                     No [7]_ [8]_
 Change argument type                                No [7]_ [8]_
+Add return type                                     No [7]_ [8]_
+Remove return type                                  No [7]_ [8]_ [9]_
 Change return type                                  No [7]_ [8]_
 **Private Methods**
 Add private method                                  Yes
@@ -257,6 +265,8 @@ Remove default value of an argument                 Yes
 Add type hint to an argument                        Yes
 Remove type hint of an argument                     Yes
 Change argument type                                Yes
+Add return type                                     Yes
+Remove return type                                  Yes
 Change return type                                  Yes
 **Static Methods**
 Turn non static into static                         No [7]_ [8]_
@@ -300,6 +310,8 @@ Change value of a constant                          Yes [1]_ [5]_
        Changing an argument type is only possible with a parent type.
        Changing a return type is only possible with a child type.
 
+.. [9] Allowed for the ``void`` return type.
+
 .. _Semantic Versioning: https://semver.org/
 .. _scalar type: https://php.net/manual/en/function.is-scalar.php
 .. _boolean values: https://php.net/manual/en/function.boolval.php

contributing/code/core_team.rst

@@ -97,7 +97,7 @@ Active Core Members
   * **Tobias Nyholm** (`Nyholm`_) manages the official and contrib recipes
     repositories;
 
-  * **Samuel Rozé** (`sroze`_) can merge into Messenger_ component.
+  * **Samuel Rozé** (`sroze`_) can merge into the Messenger_ component.
 
 * **Deciders Team** (``@symfony/deciders`` on GitHub):
 

page_creation.rst

@@ -8,7 +8,7 @@ Create your First Page in Symfony
 =================================
 
 Creating a new page - whether it's an HTML page or a JSON endpoint - is a
-simple two-step process:
+two-step process:
 
 #. **Create a route**: A route is the URL (e.g. ``/about``) to your page and
    points to a controller;

reference/forms/types/collection.rst

@@ -347,7 +347,7 @@ type::
 entry_type
 ~~~~~~~~~~
 
-**type**: ``string`` or :class:`Symfony\\Component\\Form\\FormTypeInterface` **default**: ``Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType``
+**type**: ``string`` **default**: ``Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType``
 
 This is the field type for each item in this collection (e.g. ``TextType``,
 ``ChoiceType``, etc). For example, if you have an array of email addresses,

reference/forms/types/datetime.rst

@@ -109,7 +109,8 @@ If the ``widget`` option is set to ``single_text``, this option specifies
 the format of the input, i.e. how Symfony will interpret the given input
 as a datetime string. It defaults to the `RFC 3339`_ format which is used
 by the HTML5 ``datetime`` field. Keeping the default value will cause the
-field to be rendered as an ``input`` field with ``type="datetime"``.
+field to be rendered as an ``input`` field with ``type="datetime"``. For
+more information on valid formats, see `Date/Time Format Syntax`_.
 
 .. include:: /reference/forms/types/options/hours.rst.inc
 
@@ -214,3 +215,4 @@ Field Variables
 +----------+------------+----------------------------------------------------------------------+
 
 .. _`RFC 3339`: https://tools.ietf.org/html/rfc3339
+.. _`Date/Time Format Syntax`: http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax