From 412d66e8af58a517761796a21c66856e12b49199 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 10 Dec 2017 12:24:25 +0100 Subject: [PATCH 1/3] Improved the guide about upgrading apps to Flex --- setup/flex.rst | 104 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 79 insertions(+), 25 deletions(-) diff --git a/setup/flex.rst b/setup/flex.rst index c6a92a9d7db..b7a4a90c847 100644 --- a/setup/flex.rst +++ b/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,37 +163,87 @@ 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 ` 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//views/`` -> ``templates//`` + * 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 ` 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 @@ -201,3 +251,7 @@ manual steps: .. _`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 From e198817c466087cca7ac54b1c5f724cd70d83719 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 11 Dec 2017 12:00:52 +0100 Subject: [PATCH 2/3] Fixed a syntax issue --- setup/flex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/flex.rst b/setup/flex.rst index b7a4a90c847..99742ea95bf 100644 --- a/setup/flex.rst +++ b/setup/flex.rst @@ -232,7 +232,7 @@ manual steps: 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/``). + ``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 ` to manage and compile them. From 83bc62433899f336e66a18fe351a8e1e1081148f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 11 Dec 2017 12:06:14 +0100 Subject: [PATCH 3/3] Fixed a reference --- setup/flex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/flex.rst b/setup/flex.rst index 99742ea95bf..e22eab22613 100644 --- a/setup/flex.rst +++ b/setup/flex.rst @@ -209,7 +209,7 @@ manual steps: 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 ` you can remove + :doc:`autowiring feature ` you can remove most of the service configuration. #. Move the rest of the ``app/`` contents as follows (and after that, remove the