Skip to content

Commit 0dc8945

Browse files
committed
minor #8864 Improved the guide about upgrading apps to Flex (javiereguiluz)
This PR was squashed before being merged into the 4.0 branch (closes #8864). Discussion ---------- Improved the guide about upgrading apps to Flex I've tested this in some apps and shared this with some people and it seems to be a better way to upgrade apps to Flex. Commits ------- 3f6c83b Improved the guide about upgrading apps to Flex
2 parents 92de3bc + 3f6c83b commit 0dc8945

File tree

1 file changed

+79
-25
lines changed

1 file changed

+79
-25
lines changed

setup/flex.rst

Lines changed: 79 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ Symfony application by executing the following command:
129129
Upgrading Existing Applications to Flex
130130
---------------------------------------
131131

132-
Using Symfony Flex is optional, even in Symfony 4, where Flex will be used by
132+
Using Symfony Flex is optional, even in Symfony 4, where Flex is used by
133133
default. However, Flex is so convenient and improves your productivity so much
134134
that it's strongly recommended to upgrade your existing applications to it.
135135

@@ -163,41 +163,95 @@ is not enough. You must also upgrade the directory structure to the one shown
163163
above. There's no automatic tool to make this upgrade, so you must follow these
164164
manual steps:
165165

166-
#. Create a new empty Symfony application (``composer create-project
167-
symfony/skeleton my-project-flex``)
166+
#. Install Flex as a dependency of your project:
168167

169-
#. Merge the ``require`` and ``require-dev`` dependencies defined in your
170-
original project's ``composer.json`` file to the ``composer.json`` file of the
171-
new project (don't copy the ``symfony/symfony`` dependency, but add the
172-
relevant components you are effectively using in your project).
168+
.. code-block:: terminal
173169
174-
#. Install the dependencies in the new project executing ``composer update``.
175-
This will make Symfony Flex generate all the configuration files in
176-
``config/packages/``
170+
$ composer require symfony/flex
177171
178-
#. Review the generated ``config/packages/*.yaml`` files and make any needed
179-
changes according to the configuration defined in the
180-
``app/config/config_*.yml`` file of your original project. Beware that this is
181-
the most time-consuming and error-prone step of the upgrade process.
172+
#. If the project's ``composer.json`` file contains ``symfony/symfony`` dependency,
173+
it still depends on the Symfony Standard edition, which is no longer available
174+
in Symfony 4. First, remove this dependency:
182175

183-
#. Move the original parameters defined in ``app/config/parameters.*.yml`` to
184-
the new ``config/services.yaml`` and ``.env`` files depending on your needs.
176+
.. code-block:: terminal
185177
186-
#. Move the original source code from ``src/{App,...}Bundle/`` to ``src/`` and
187-
update the namespaces of every PHP file to be ``App\...`` (advanced IDEs can do
188-
this automatically).
178+
$ composer remove symfony/symfony
189179
190-
#. Move the original templates from ``app/Resources/views/`` to ``templates/``
191-
and ``app/Resources/translations`` to ``translations/``. There may be a few
192-
other files you need to move into a new location.
180+
Now you must add in ``composer.json`` all the Symfony dependencies required
181+
by your project. A quick way to do that is to add all the components that
182+
were included in the previous ``symfony/symfony`` dependency and later you
183+
can remove anything you don't really need:
193184

194-
#. Make any other change needed by your application. For example, if your
195-
original ``web/app_*.php`` front controllers were customized, add those changes
196-
to the new ``public/index.php`` controller.
185+
.. code-block:: terminal
186+
187+
$ composer require annotations assets doctrine twig profiler \
188+
logger mailer form fixtures security translation validator
189+
190+
#. If the project's ``composer.json`` file doesn't contain ``symfony/symfony``
191+
dependency, it already defines its dependencies explicitly, as required by
192+
Flex. You just need to reinstall all dependencies to force Flex generate the
193+
config files in ``config/``, which is the most tedious part of the upgrade
194+
process:
195+
196+
.. code-block:: terminal
197+
198+
$ rm -fr /vendor/*
199+
$ composer install
200+
201+
#. No matter which of the previous steps you followed. At this point, you'll have
202+
lots of new config files in ``config/``. They contain the default config
203+
defined by Symfony, so you must check your original files in ``app/config/``
204+
and make the needed changes in the new files. Flex config doesn't use suffixes
205+
in config files, so the old ``app/config/config_dev.yml`` goes to
206+
``config/packages/dev/*.yaml``, etc.
207+
208+
#. The most important config file is ``app/config/services.yml``, which now is
209+
located at ``config/services.yaml``. Copy the contents of the
210+
`default services.yaml file`_ and then add your own service configuration.
211+
Later you can revisit this file because thanks to Symfony's
212+
:doc:`autowiring feature </service_container/3.3-di-changes>` you can remove
213+
most of the service configuration.
214+
215+
#. Move the rest of the ``app/`` contents as follows (and after that, remove the
216+
``app/`` directory):
217+
218+
* ``app/Resources/views/`` -> ``templates/``
219+
* ``app/Resources/translations/`` -> ``translations/``
220+
* ``app/Resources/<BundleName>/views/`` -> ``templates/<BundleName>/``
221+
* rest of ``app/Resources/`` files -> ``src/Resources/``
222+
223+
#. Move the original PHP source code from ``src/AppBundle/*`` to ``src/``. In
224+
addition to moving the files, update the ``autoload`` and ``autoload-dev``
225+
values of the ``composer.json`` file as `shown in this example`_ to use
226+
``App\`` and ``App\Tests\`` as the application namespaces (advanced IDEs can
227+
do this automatically).
228+
229+
If you used multiple bundles to organize your code, you must reorganize your
230+
code into ``src/``. For example, if you had ``src/UserBundle/Controller/DefaultController.php``
231+
and ``src/ProductBundle/Controller/DefaultController.php``, you could move
232+
them to ``src/Controller/UserController.php`` and ``src/Controller/ProductController.php``.
233+
234+
#. Move the public assets, such as images or compiled CSS/JS files, from
235+
``src/AppBundle/Resources/public/`` to ``public/`` (e.g. ``public/images/``).
236+
237+
Move the source of the assets (e.g. the SCSS files) to ``assets/`` and use
238+
:doc:`Webpack Encore </frontend>` to manage and compile them.
239+
240+
#. Create the new ``public/index.php`` front controller
241+
`copying Symfony's index.php source`_ and, if you made any customization in
242+
your ``web/app.php`` and ``web/app_dev.php`` files, copy those changes into
243+
the new file. You can now remove the old ``web/`` dir.
244+
245+
#. Update the ``bin/console`` script `copying Symfony's bin/console source`_
246+
and changing anything according to your original console script.
197247

198248
.. _`Symfony Flex`: https://github.com/symfony/flex
199249
.. _`Symfony Installer`: https://github.com/symfony/symfony-installer
200250
.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard
201251
.. _`Main recipe repository`: https://github.com/symfony/recipes
202252
.. _`Contrib recipe repository`: https://github.com/symfony/recipes-contrib
203253
.. _`Symfony Recipes documentation`: https://github.com/symfony/recipes/blob/master/README.rst
254+
.. _`default services.yaml file`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/config/services.yaml
255+
.. _`shown in this example`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L24-L33
256+
.. _`copying Symfony's index.php source`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php
257+
.. _`copying Symfony's bin/console source`: https://github.com/symfony/recipes/tree/master/symfony/console/3.3

0 commit comments

Comments
 (0)