diff --git a/setup/flex.rst b/setup/flex.rst index 17715c8910c..e290ea3fe6b 100644 --- a/setup/flex.rst +++ b/setup/flex.rst @@ -5,20 +5,20 @@ Using Symfony Flex to Manage Symfony Applications `Symfony Flex`_ is the new way to install and manage Symfony applications. Flex is not a new Symfony version, but a tool that replaces and improves the -`Symfony Installer`_. +`Symfony Installer`_ and the `Symfony Standard Edition`_. Symfony Flex **automates the most common tasks of Symfony applications**, such -as installing and removing bundles and other dependencies. Symfony Flex works -for Symfony 3.3 and newer versions. Starting from Symfony 4.0, Flex will be used -by default, but it will still be optional to use. +as installing and removing bundles and other Composer dependencies. Symfony +Flex works for Symfony 3.3 and newer versions. Starting from Symfony 4.0, Flex +should be used by default, but it is optional to use. How Does Flex Work ------------------ Internally, Symfony Flex is a Composer plugin that modifies the behavior of the -``require`` and ``update`` commands. When installing or updating dependencies -in a Flex-enabled application, Symfony can perform tasks before and after the -execution of Composer tasks. +``require``, ``update``, and ``remove`` commands. When installing or removing +dependencies in a Flex-enabled application, Symfony can perform tasks before +and after the execution of Composer tasks. Consider the following example: @@ -33,25 +33,30 @@ name. However, if the application has Symfony Flex installed, that command ends up installing and enabling the SwiftmailerBundle, which is the best way to integrate Swiftmailer, the official mailer for Symfony applications. -When Symfony Flex is installed in the application and you execute ``composer require``, -the application makes a request to Symfony Flex servers before trying to install -the package with Composer: +When Symfony Flex is installed in the application and you execute ``composer +require``, the application makes a request to Symfony Flex servers before +trying to install the package with Composer: * If there's no information about that package, Flex server returns nothing and the package installation follows the usual procedure based on Composer; + * If there's special information about that package, Flex returns it in a file - called "recipe" and the application uses it to decide which package to install - and which automated tasks to run after the installation. + called "recipe" and the application uses it to decide which package to + install and which automated tasks to run after the installation. In the above example, Symfony Flex asks about the ``mailer`` package and the -Symfony Flex server detects that ``mailer`` is in fact an alias for SwiftmailerBundle -and returns the "recipe" for it. +Symfony Flex server detects that ``mailer`` is in fact an alias for +SwiftmailerBundle and returns the "recipe" for it. + +Flex keeps tracks of which recipes it installed in a ``symfony.lock`` file that +must be committed in your code repository. Symfony Flex Recipes ~~~~~~~~~~~~~~~~~~~~ Recipes are defined in a ``manifest.json`` file and can contain any number of -other files and directories. For example, this is the ``manifest.json`` for SwiftmailerBundle: +other files and directories. For example, this is the ``manifest.json`` for +SwiftmailerBundle: .. code-block:: javascript @@ -69,27 +74,29 @@ other files and directories. For example, this is the ``manifest.json`` for Swif } The ``aliases`` option allows Flex to install packages using short and easy to -remember names (``composer require mailer`` vs ``composer require symfony/swiftmailer-bundle``). -The ``bundles`` option tells Flex in which environments should this bundle be -enabled automatically (``all`` in this case). The ``env`` option makes Flex to -add new environment variables to the application. Finally, the ``copy-from-recipe`` -option allows the recipe to copy files and directories into your application. - -The instructions defined in this ``manifest.json`` file are also used by Symfony -Flex when uninstalling dependencies (e.g. ``composer remove mailer``) to undo -all changes. This means that Flex can remove the SwiftmailerBundle from the -application, delete the ``MAILER_URL`` environment variable and any other file -and directory created by this recipe. +remember names (``composer require mailer`` vs ``composer require +symfony/swiftmailer-bundle``). The ``bundles`` option tells Flex in which +environments should this bundle be enabled automatically (``all`` in this +case). The ``env`` option makes Flex to add new environment variables to the +application. Finally, the ``copy-from-recipe`` option allows the recipe to copy +files and directories into your application. + +The instructions defined in this ``manifest.json`` file are also used by +Symfony Flex when uninstalling dependencies (e.g. ``composer remove mailer``) +to undo all changes. This means that Flex can remove the SwiftmailerBundle from +the application, delete the ``MAILER_URL`` environment variable and any other +file and directory created by this recipe. Symfony Flex recipes are contributed by the community and they are stored in two public repositories: * `Main recipe repository`_, is a curated list of recipes for high quality and maintained packages. Symfony Flex only looks in this repository by default. -* `Contrib recipe repository`_, contains all the recipes created by the community. - All of them are guaranteed to work, but their associated packages could be - unmaintained. Symfony Flex ignores these recipes by default, but you can execute - this command to start using them in your project: + +* `Contrib recipe repository`_, contains all the recipes created by the + community. All of them are guaranteed to work, but their associated packages + could be unmaintained. Symfony Flex ignores these recipes by default, but you + can execute this command to start using them in your project: .. code-block:: terminal @@ -103,9 +110,9 @@ Using Symfony Flex in New Applications -------------------------------------- Symfony has published a new "skeleton" project, which is a minimal Symfony -project recommended to create new applications. This "skeleton" already includes -Symfony Flex as a dependency, so you can create a new Flex-enabled Symfony -application executing the following command: +project recommended to create new applications. This "skeleton" already +includes Symfony Flex as a dependency, so you can create a new Flex-enabled +Symfony application executing the following command: .. code-block:: terminal @@ -114,7 +121,8 @@ application executing the following command: .. note:: The use of the Symfony Installer to create new applications is no longer - recommended since Symfony 3.3. Use Composer ``create-project`` command instead. + recommended since Symfony 3.3. Use Composer ``create-project`` command + instead. Upgrading Existing Applications to Flex --------------------------------------- @@ -144,29 +152,42 @@ following directory structure, which is the same used by default in Symfony 4: This means that installing the ``symfony/flex`` dependency in your application is not enough. You must also upgrade the directory structure to the one showed -above. Sadly, 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``) -#. Copy the ``require`` and ``require-dev`` dependencies defined in your original - project's ``composer.json`` file to the ``composer.json`` file of the new project. -#. Install the dependencies in the new project executing ``composer install``. This - will make Symfony Flex generate all the configuration files in ``config/packages/`` +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``) + +#. 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). + +#. Install the dependencies in the new project executing ``composer install``. + This will make Symfony Flex generate all the configuration files in + ``config/packages/`` + #. 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. -#. Move the original parameters defined in ``app/config/parameters.*.yml`` to the - new ``config/services.yaml`` and ``.env`` files depending on your needs. + 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. + +#. Move the original parameters defined in ``app/config/parameters.*.yml`` to + the new ``config/services.yaml`` and ``.env`` files depending on your needs. + #. Move the original source code from ``src/{App,...}Bundle/`` to ``src/`` and - update the namespaces of every PHP file (advanced IDEs can do this automatically). + update the namespaces of every PHP file (advanced IDEs can do this + automatically). + #. Move the original templates from ``app/Resources/views/`` to ``templates/`` -#. 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. + +#. 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. .. _`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