Skip to content

Tweak docs for Flex #8571

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 2, 2017
Merged

Tweak docs for Flex #8571

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 72 additions & 51 deletions setup/flex.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be used by default, but it is optional to use.
I'd say:
should be used by default, but it is still optional.
To to avoid the double "used/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:

Expand All @@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rewrite to:
Flex keeps tracks of installed recipes in a ``symfony.lock`` file which must be committed in your code repository.
Just for better concordance


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

Expand All @@ -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
Copy link

@jaikdean jaikdean Nov 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

environments should this bundle be enabled automatically should be environments this bundle should be automatically enabled

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

Expand All @@ -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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

, so you can create a new
to
, thus you can create a new

Symfony application executing the following command:

.. code-block:: terminal

Expand All @@ -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
---------------------------------------
Expand Down Expand Up @@ -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