Using Symfony Flex to Manage Symfony Applications

How Does Flex Work

Symfony Flex is a Composer plugin that modifies the behavior of the 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:

1
2

$ cd my-project/
$ composer require mailer

If you execute that command in a Symfony application which doesn't use Flex, you'll see a Composer error explaining that mailer is not a valid package 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 Swift Mailer, 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 the Symfony Flex server before trying to install the package with Composer.

• If there's no information about that package, the 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 a "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.

Flex keeps tracks of the recipes it installed in a symfony.lock file, which must be committed to your code repository.

1
2
3
4
5
6
7
8
9
10
11
12

{
    "bundles": {
        "Symfony\\Bundle\\SwiftmailerBundle\\SwiftmailerBundle": ["all"]
    },
    "copy-from-recipe": {
        "config/": "%CONFIG_DIR%/"
    },
    "env": {
        "MAILER_URL": "smtp://localhost:25?encryption=&auth_mode="
    },
    "aliases": ["mailer", "mail"]
}

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. This means you can create a new Flex-enabled Symfony application by executing the following command:

1

$ composer create-project symfony/skeleton:3.4.* my-project

Upgrading Existing Applications to Flex

Using Symfony Flex is optional, even in Symfony 4, where Flex will be 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.

The only caveat is that Symfony Flex requires that applications use the following directory structure, which is the same used by default in Symfony 4:

1
2
3
4
5
6
7
8
9
10
11
12
13

your-project/
├── config/
│   ├── bundles.php
│   ├── packages/
│   ├── routes.yaml
│   └── services.yaml
├── public/
│   └── index.php
├── src/
│   ├── ...
│   └── Kernel.php
├── templates/
└── vendor/

This means that installing the symfony/flex dependency in your application 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:

1. Create a new empty Symfony application (composer create-project symfony/skeleton my-project-flex)
2. 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).
3. Install the dependencies in the new project executing composer update. This will make Symfony Flex generate all the configuration files in config/packages/
4. 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.
5. Move the original parameters defined in app/config/parameters.*.yml to the new config/services.yaml and .env files depending on your needs. If you have defined custom config options in your bundles move them to the new config/services.yaml and .env files.
6. SYMFONY_DEBUG and SYMFONY_ENV environment variables were replaced by APP_DEBUG and APP_ENV. Copy their values to the new vars and then remove the former ones.
7. 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).
8. 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.
9. 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.

Customizing Flex Paths

The Flex recipes make a few assumptions about your project's directory structure. Some of these assumptions can be customized by adding a key under the extra section of your composer.json file. For example, to tell Flex to copy any PHP classes into src/App instead of src:

1
2
3
4
5
6
7

{
    "...": "...",

    "extra": {
        "src-dir": "src/App"
    }
}

The configurable paths are:

• bin-dir: defaults to bin/
• config-dir: defaults to config/
• src-dir defaults to src/
• var-dir defaults to var/
• public-dir defaults to public/

If you customize these paths, some files copied from a recipe still may contain references to the original path. In other words: you may need to update some things manually after a recipe is installed.