Merge branch '4.0'

* 4.0:
  Fixed a typo
  Improved the guide about upgrading apps to Flex
  Recommend to use PHPUnitBridge instead of PHPUnit
  Fixes and simplifications
  Improve routing debug page
  Improved the example to generate URLs in the console
  Minor typo
  minor symfony#8704 Client's history clear alternative (takman1)
  [Serializer] Add new default normalizers
  use the ref role instead of URLs
  Update timezone.rst
  Update timezone.rst

Author: javiereguiluz

console/request_context.rst

@@ -85,6 +85,7 @@ router service and override its settings::
             $context->setScheme('https');
             $context->setBaseUrl('my/path');
 
-            // ... your code here
+            $url = $this->router->generate('route-name', array('param-name' => 'param-value'));
+            // ...
         }
     }

form/disabling_validation.rst

@@ -21,7 +21,6 @@ for example whether an uploaded file was too large or whether non-existing
 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
+:ref:`allow_extra_fields config option <form-option-allow-extra-fields>` and
+the maximum upload file size should be handled via your PHP and web server
+configuration.

reference/forms/types/form.rst

@@ -50,6 +50,8 @@ Field Options
 
 .. include:: /reference/forms/types/options/action.rst.inc
 
+.. _form-option-allow-extra-fields:
+
 allow_extra_fields
 ~~~~~~~~~~~~~~~~~~
 

reference/forms/types/timezone.rst

@@ -17,6 +17,9 @@ manually, but then you should just use the ``ChoiceType`` directly.
 +-------------+------------------------------------------------------------------------+
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)           |
 +-------------+------------------------------------------------------------------------+
+| Options     | - `input`_                                                             |
+|             | - `regions`_                                                           |
++-------------+------------------------------------------------------------------------+
 | Overridden  | - `choices`_                                                           |
 | options     |                                                                        |
 +-------------+------------------------------------------------------------------------+
@@ -45,6 +48,27 @@ manually, but then you should just use the ``ChoiceType`` directly.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TimezoneType` |
 +-------------+------------------------------------------------------------------------+
 
+Field Options
+-------------
+
+input
+~~~~~
+
+**type**: ``string`` **default**: ``string``
+
+The format of the *input* data - i.e. the format that the timezone is stored
+on your underlying object. Valid values are:
+
+* ``string`` (e.g. ``America/New_York``)
+* ``datetimezone`` (a ``DateTimeZone`` object)
+
+regions
+~~~~~~~
+
+**type**: ``int`` **default**: ``\DateTimeZone::ALL``
+
+The available regions in the timezone choice list. For example: ``DateTimeZone::AMERICA | DateTimeZone::EUROPE``
+
 Overridden Options
 ------------------
 

routing/debug.rst

@@ -18,12 +18,16 @@ your application:
 
 .. code-block:: text
 
-    homepage              ANY       /
-    contact               GET       /contact
-    contact_process       POST      /contact
-    article_show          ANY       /articles/{_locale}/{year}/{title}.{_format}
-    blog                  ANY       /blog/{page}
-    blog_show             ANY       /blog/{slug}
+    ------------------ -------- -------- ------ ----------------------------------------------
+     Name               Method   Scheme   Host   Path
+    ------------------ -------- -------- ------ ----------------------------------------------
+     homepage           ANY      ANY      ANY    /
+     contact            GET      ANY      ANY    /contact
+     contact_process    POST     ANY      ANY    /contact
+     article_show       ANY      ANY      ANY    /articles/{_locale}/{year}/{title}.{_format}
+     blog               ANY      ANY      ANY    /blog/{page}
+     blog_show          ANY      ANY      ANY    /blog/{slug}
+    ------------------ -------- -------- ------ ----------------------------------------------
 
 You can also get very specific information on a single route by including
 the route name after the command:

serializer.rst

@@ -44,21 +44,37 @@ you need it or it can be used in a controller::
 Adding Normalizers and Encoders
 -------------------------------
 
-Once enabled, the serializer service will be available in the container
-and will be loaded with four :ref:`encoders <component-serializer-encoders>`
-(:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`,
-:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`,
-:class:`Symfony\\Component\\Serializer\\Encoder\\YamlEncoder`, and
-:class:`Symfony\\Component\\Serializer\\Encoder\\CsvEncoder`) and the
-:ref:`ObjectNormalizer normalizer <component-serializer-normalizers>`.
-
-You can load normalizers and/or encoders by tagging them as
+Once enabled, the ``serializer`` service will be available in the container.
+It comes with a set of useful :ref:`encoders <component-serializer-encoders>`
+and :ref:`normalizers <component-serializer-normalizers>`.
+
+Encoders supporting the following formats are enabled:
+
+* JSON: :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`
+* XML: :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`
+
+As well as the following normalizers:
+
+* :class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer` to
+  handle typical data objects
+* :class:`Symfony\\Component\\Serializer\\Normalizer\\DateTimeNormalizer` for
+  objects implementing the :class:`DateTimeInterface` interface
+* :class:`Symfony\\Component\\Serializer\\Normalizer\\DataUriNormalizer` to
+  transform :class:`SplFileInfo` objects in `Data URIs`_
+* :class:`Symfony\\Component\\Serializer\\Normalizer\\JsonSerializableNormalizer`
+  to deal with objects implementing the :class:`JsonSerializable` interface
+* :class:`Symfony\\Component\\Serializer\\Normalizer\\ArrayDenormalizer` to
+  denormalize arrays of objects using a format like `MyObject[]` (note the `[]` suffix)
+
+Custom normalizers and/or encoders can also be loaded by tagging them as
 :ref:`serializer.normalizer <reference-dic-tags-serializer-normalizer>` and
 :ref:`serializer.encoder <reference-dic-tags-serializer-encoder>`. It's also
 possible to set the priority of the tag in order to decide the matching order.
 
 Here is an example on how to load the
-:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`:
+:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`, a
+faster alternative to the `ObjectNormalizer` when data objects always use
+getters and setters:
 
 .. configuration-block::
 
@@ -193,3 +209,4 @@ take a look at how this bundle works.
 .. _`ApiPlatform`: https://github.com/api-platform/core
 .. _`JSON-LD`: http://json-ld.org
 .. _`Hydra Core Vocabulary`: http://hydra-cg.com
+.. _`Data URIs`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs

setup/bundles.rst

@@ -69,7 +69,8 @@ PHPUnit test report:
 
 .. code-block:: terminal
 
-    $ phpunit
+    # this command is available after running "composer require --dev symfony/phpunit-bridge"
+    $ ./bin/phpunit
 
     # ... PHPUnit output
 

setup/flex.rst

@@ -129,7 +129,7 @@ Symfony application by executing the following command:
 Upgrading Existing Applications to Flex
 ---------------------------------------
 
-Using Symfony Flex is optional, even in Symfony 4, where Flex will be used by
+Using Symfony Flex is optional, even in Symfony 4, where Flex is used by
 default. However, Flex is so convenient and improves your productivity so much
 that it's strongly recommended to upgrade your existing applications to it.
 
@@ -163,41 +163,95 @@ is not enough. You must also upgrade the directory structure to the one shown
 above. There's no automatic tool to make this upgrade, so you must follow these
 manual steps:
 
-#. Create a new empty Symfony application (``composer create-project
-   symfony/skeleton my-project-flex``)
+#. Install Flex as a dependency of your project:
 
-#. Merge the ``require`` and ``require-dev`` dependencies defined in your
-   original project's ``composer.json`` file to the ``composer.json`` file of the
-   new project (don't copy the ``symfony/symfony`` dependency, but add the
-   relevant components you are effectively using in your project).
+   .. code-block:: terminal
 
-#. Install the dependencies in the new project executing ``composer update``.
-   This will make Symfony Flex generate all the configuration files in
-   ``config/packages/``
+       $ composer require symfony/flex
 
-#. Review the generated ``config/packages/*.yaml`` files and make any needed
-   changes according to the configuration defined in the
-   ``app/config/config_*.yml`` file of your original project. Beware that this is
-   the most time-consuming and error-prone step of the upgrade process.
+#. If the project's ``composer.json`` file contains ``symfony/symfony`` dependency,
+   it still depends on the Symfony Standard edition, which is no longer available
+   in Symfony 4. First, remove this dependency:
 
-#. Move the original parameters defined in ``app/config/parameters.*.yml`` to
-   the new ``config/services.yaml`` and ``.env`` files depending on your needs.
+   .. code-block:: terminal
 
-#. Move the original source code from ``src/{App,...}Bundle/`` to ``src/`` and
-   update the namespaces of every PHP file to be ``App\...`` (advanced IDEs can do
-   this automatically).
+       $ composer remove symfony/symfony
 
-#. Move the original templates from ``app/Resources/views/`` to ``templates/``
-   and ``app/Resources/translations`` to ``translations/``. There may be a few
-   other files you need to move into a new location.
+   Now you must add in ``composer.json`` all the Symfony dependencies required
+   by your project. A quick way to do that is to add all the components that
+   were included in the previous ``symfony/symfony`` dependency and later you
+   can remove anything you don't really need:
 
-#. Make any other change needed by your application. For example, if your
-   original ``web/app_*.php`` front controllers were customized, add those changes
-   to the new ``public/index.php`` controller.
+   .. code-block:: terminal
+
+       $ composer require annotations assets doctrine twig profiler \
+         logger mailer form fixtures security translation validator
+
+#. If the project's ``composer.json`` file doesn't contain ``symfony/symfony``
+   dependency, it already defines its dependencies explicitly, as required by
+   Flex. You just need to reinstall all dependencies to force Flex generate the
+   config files in ``config/``, which is the most tedious part of the upgrade
+   process:
+
+   .. code-block:: terminal
+
+       $ rm -fr /vendor/*
+       $ composer install
+
+#. No matter which of the previous steps you followed. At this point, you'll have
+   lots of new config files in ``config/``. They contain the default config
+   defined by Symfony, so you must check your original files in ``app/config/``
+   and make the needed changes in the new files. Flex config doesn't use suffixes
+   in config files, so the old ``app/config/config_dev.yml`` goes to
+   ``config/packages/dev/*.yaml``, etc.
+
+#. The most important config file is ``app/config/services.yml``, which now is
+   located at ``config/services.yaml``. Copy the contents of the
+   `default services.yaml file`_ and then add your own service configuration.
+   Later you can revisit this file because thanks to Symfony's
+   :doc:`autowiring feature </service_container/3.3-di-changes>` you can remove
+   most of the service configuration.
+
+#. Move the rest of the ``app/`` contents as follows (and after that, remove the
+   ``app/`` directory):
+
+   * ``app/Resources/views/`` -> ``templates/``
+   * ``app/Resources/translations/`` -> ``translations/``
+   * ``app/Resources/<BundleName>/views/`` -> ``templates/<BundleName>/``
+   * rest of ``app/Resources/`` files -> ``src/Resources/``
+
+#. Move the original PHP source code from ``src/AppBundle/*`` to ``src/``. In
+   addition to moving the files, update the ``autoload`` and ``autoload-dev``
+   values of the ``composer.json`` file as `shown in this example`_ to use
+   ``App\`` and ``App\Tests\`` as the application namespaces (advanced IDEs can
+   do this automatically).
+
+   If you used multiple bundles to organize your code, you must reorganize your
+   code into ``src/``. For example, if you had ``src/UserBundle/Controller/DefaultController.php``
+   and ``src/ProductBundle/Controller/DefaultController.php``, you could move
+   them to ``src/Controller/UserController.php`` and ``src/Controller/ProductController.php``.
+
+#. Move the public assets, such as images or compiled CSS/JS files, from
+   ``src/AppBundle/Resources/public/`` to ``public/`` (e.g. ``public/images/``).
+
+  Move the source of the assets (e.g. the SCSS files) to ``assets/`` and use
+  :doc:`Webpack Encore </frontend>` to manage and compile them.
+
+#. Create the new ``public/index.php`` front controller
+   `copying Symfony's index.php source`_ and, if you made any customization in
+   your ``web/app.php`` and ``web/app_dev.php`` files, copy those changes into
+   the new file. You can now remove the old ``web/`` dir.
+
+#. Update the ``bin/console`` script `copying Symfony's bin/console source`_
+   and changing anything according to your original console script.
 
 .. _`Symfony Flex`: https://github.com/symfony/flex
 .. _`Symfony Installer`: https://github.com/symfony/symfony-installer
 .. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard
 .. _`Main recipe repository`: https://github.com/symfony/recipes
 .. _`Contrib recipe repository`: https://github.com/symfony/recipes-contrib
 .. _`Symfony Recipes documentation`: https://github.com/symfony/recipes/blob/master/README.rst
+.. _`default services.yaml file`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/config/services.yaml
+.. _`shown in this example`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L24-L33
+.. _`copying Symfony's index.php source`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php
+.. _`copying Symfony's bin/console source`: https://github.com/symfony/recipes/tree/master/symfony/console/3.3

setup/upgrade_major.rst

@@ -75,7 +75,8 @@ Now, you can start fixing the notices:
 
 .. code-block:: text
 
-    $ phpunit
+    # this command is available after running "composer require --dev symfony/phpunit-bridge"
+    $ ./bin/phpunit
     ...
 
     OK (10 tests, 20 assertions)

testing.rst

@@ -15,10 +15,11 @@ Symfony integrates with an independent library - called PHPUnit - to give
 you a rich testing framework. This article won't cover PHPUnit itself, but
 it has its own excellent `documentation`_.
 
-.. note::
+First, install PHPUnit support in your Symfony application running this command:
+
+.. code-block:: terminal
 
-    It's recommended to use the latest stable PHPUnit version, `installed as
-    PHAR`_.
+    $ composer require --dev phpunit
 
 Each test - whether it's a unit test or a functional test - is a PHP class
 that should live in the ``tests/`` directory of your application. If you follow
@@ -27,7 +28,7 @@ command:
 
 .. code-block:: terminal
 
-    $ phpunit
+    $ ./bin/phpunit
 
 PHPUnit is configured by the ``phpunit.xml.dist`` file in the root of your
 Symfony application.
@@ -99,16 +100,13 @@ Running tests for a given file or directory is also very easy:
 .. code-block:: terminal
 
     # run all tests of the application
-    $ phpunit
+    $ ./bin/phpunit
 
-    # run all tests in the Util directory
-    $ phpunit tests/Util
+    # run all tests in the Util/ directory
+    $ ./bin/phpunit tests/Util
 
     # run tests for the Calculator class
-    $ phpunit tests/Util/CalculatorTest.php
-
-    # run all tests for the entire Bundle
-    $ phpunit tests/
+    $ ./bin/phpunit tests/Util/CalculatorTest.php
 
 .. index::
    single: Tests; Functional tests
@@ -926,4 +924,3 @@ Learn more
 
 .. _`$_SERVER`: http://php.net/manual/en/reserved.variables.server.php
 .. _`documentation`: https://phpunit.de/manual/current/en/
-.. _`installed as PHAR`: https://phpunit.de/manual/current/en/installation.html#installation.phar