Merge branch '4.0' into 4.1

* 4.0: (27 commits)
  Added a caution note about env vars and the profiler
  Use gender-neutral language in the main Serializer article
  Fix error on @MaxDepth property for annotation, yaml and xml. Change property according to documentation
  Link to the asset component documentation
  New section about JSON file manifest strategy
  Removed the term "simple" from creating a new page
  classname typo fixed
  Update datetime.rst
  components/phpunit_bridge.rst
  Add best practice note about version
  Fixed formatting
  Autowiring - Rephrase aliasing when multiple classes implement same interface
  ...

Author: javiereguiluz

best_practices/i18n.rst

@@ -3,7 +3,7 @@ Internationalization
 
 Internationalization and localization adapt the applications and their contents
 to the specific region or language of the users. In Symfony this is an opt-in
-feature that needs to be installed before using it (``composer require translation``).
+feature that needs to be installed before using it (``composer require symfony/translation``).
 
 Translation Source File Location
 --------------------------------

bundles/best_practices.rst

@@ -239,7 +239,7 @@ of Symfony and the latest beta release:
         # it helps with testing legacy code and deprecations (composer require symfony/phpunit-bridge)
         - ./vendor/bin/simple-phpunit $PHPUNIT_FLAGS
 
-Consider using `Travis cron`_ too to make sure your project is built even if
+Consider using the `Travis cron`_ tool to make sure your project is built even if
 there are no new pull requests or commits.
 
 Installation

components/asset.rst

@@ -139,6 +139,33 @@ string as the second argument of the ``StaticVersionStrategy`` constructor::
     echo $package->getUrl('image.png');
     // result: v1/image.png
 
+JSON File Manifest
+..................
+
+A popular strategy to manage asset versioning, which is used by tools such as
+`Webpack`_, is to generate a JSON file mapping all source file names to their
+corresponding output file:
+
+.. code-block:: json
+
+    // rev-manifest.json
+    {
+        "css/app.css": "build/css/app.b916426ea1d10021f3f17ce8031f93c2.css",
+        "js/app.js": "build/js/app.13630905267b809161e71d0f8a0c017b.js",
+        "...": "..."
+    }
+
+In those cases, use the 
+:class:`Symfony\\Component\\Asset\\VersionStrategy\\JsonManifestVersionStrategy`::
+
+    use Symfony\Component\Asset\Package;
+    use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
+
+    $package = new Package(new JsonManifestVersionStrategy(__DIR__'./rev-manifest.json'));
+
+    echo $package->getUrl('css/app.css');
+    // result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css
+
 Custom Version Strategies
 .........................
 
@@ -349,3 +376,4 @@ Learn more
 ----------
 
 .. _Packagist: https://packagist.org/packages/symfony/asset
+.. _`Webpack`: https://webpack.js.org/

components/console/events.rst

@@ -95,7 +95,7 @@ can wrap or change the exception or do anything useful before the exception is
 thrown by the application.
 
 Listeners receive a
-:class:`Symfony\\Component\\Console\\Event\\ConsoleExceptionEvent` event::
+:class:`Symfony\\Component\\Console\\Event\\ConsoleErrorEvent` event::
 
     use Symfony\Component\Console\Event\ConsoleErrorEvent;
     use Symfony\Component\Console\ConsoleEvents;

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;
 
@@ -187,7 +187,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>
@@ -197,7 +197,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.
 
@@ -400,7 +400,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:
 
@@ -512,8 +512,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``.
@@ -523,7 +523,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;
@@ -860,7 +860,7 @@ Here, we set it to 2 for the ``$child`` property:
             /**
              * @MaxDepth(2)
              */
-            public $foo;
+            public $child;
 
             // ...
         }
@@ -869,7 +869,7 @@ Here, we set it to 2 for the ``$child`` property:
 
         Acme\MyObj:
             attributes:
-                foo:
+                child:
                     max_depth: 2
 
     .. code-block:: xml
@@ -881,7 +881,7 @@ Here, we set it to 2 for the ``$child`` property:
                 http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
         >
             <class name="Acme\MyObj">
-                <attribute name="foo" max-depth="2" />
+                <attribute name="child" max-depth="2" />
             </class>
         </serializer>
 

components/var_dumper.rst

@@ -23,7 +23,7 @@ Alternatively, you can clone the `<https://github.com/symfony/var-dumper>`_ repo
 .. note::
 
     If using it inside a Symfony application, make sure that the DebugBundle has
-    been installed (or run ``composer require debug`` to install it).
+    been installed (or run ``composer require symfony/debug-bundle`` to install it).
 
 .. _components-var-dumper-dump:
 

configuration/external_parameters.rst

@@ -130,6 +130,10 @@ the following:
     environment variables, exposing sensitive information such as the database
     credentials.
 
+    The values of the env vars are also exposed in the web interface of the
+    :doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
+    problem because the web profiler must **never** be enabled in production.
+
 Constants
 ---------
 

console/lazy_commands.rst

@@ -18,7 +18,7 @@ which will be responsible for returning ``Command`` instances::
     use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;
 
     $commandLoader = new FactoryCommandLoader(array(
-        'app:heavy' => function () { return new HeavyCommand() },
+        'app:heavy' => function () { return new HeavyCommand(); },
     ));
 
     $application = new Application();
@@ -48,7 +48,7 @@ array of ``Command`` factories as its only constructor argument::
     use Symfony\Component\Console\CommandLoader\FactoryCommandLoader;
 
     $commandLoader = new FactoryCommandLoader(array(
-        'app:foo' => function () { return new FooCommand() },
+        'app:foo' => function () { return new FooCommand(); },
         'app:bar' => array(BarCommand::class, 'create'),
     ));
 

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`