Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Setup
  4. Using Symfony Flex to Manage Symfony Applications
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • How Does Flex Work
    • Symfony Flex Recipes
  • Using Symfony Flex in New Applications
  • Upgrading Existing Applications to Flex

Using Symfony Flex to Manage Symfony Applications

Edit this page

Warning: You are browsing the documentation for Symfony 4.0, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

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 and the Symfony Standard Edition.

Symfony Flex automates the most common tasks of Symfony applications, like installing and removing bundles and other Composer dependencies. Symfony Flex works for Symfony 3.3 and higher. Starting from Symfony 4.0, Flex should be used by default, but it is still optional.

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 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 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.

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:

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"]
}

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 this bundle should 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 will ask your permission before installing any of these recipes.

Read the Symfony Recipes documentation to learn everything about how to create recipes for your own packages.

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 my-project

Note

The use of the Symfony Installer to create new applications is no longer recommended since Symfony 3.3. Use the Composer create-project command instead.

Upgrading Existing Applications to Flex

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.

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
14
15
16
17
18
19
your-project/
├── assets/
├── bin/
│   └── console
├── config/
│   ├── bundles.php
│   ├── packages/
│   ├── routes.yaml
│   └── services.yaml
├── public/
│   └── index.php
├── src/
│   ├── ...
│   └── Kernel.php
├── templates/
├── tests/
├── translations/
├── var/
└── 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. Install Flex as a dependency of your project:

    1
    $ composer require symfony/flex
  2. 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:

    1
    $ composer remove symfony/symfony

    Now add the symfony/symfony package to the conflict section of the project's composer.json file as shown in this example of the skeleton-project so that it will not be installed again:

    1
    2
    3
    4
    5
    6
    7
    8
    {
        "require": {
            "symfony/flex": "^1.0",
    +     },
    +     "conflict": {
    +         "symfony/symfony": "*"
        }
    }

    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:

    1
    2
    3
    $ composer require annotations asset orm-pack twig \
      logger mailer form security translation validator
    $ composer require --dev dotenv maker-bundle orm-fixtures profiler
  3. 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:

    1
    2
    $ rm -fr vendor/*
    $ composer install
  4. 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.
  5. 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 autowiring feature you can remove most of the service configuration.

    Note

    Make sure that your previous configuration files don't have imports declarations pointing to resources already loaded by Kernel::configureContainer() or Kernel::configureRoutes() methods.

  6. 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/<BundleName>/views/ -> templates/bundles/<BundleName>/
    • rest of app/Resources/ files -> src/Resources/
  7. Move the original PHP source code from src/AppBundle/*, except bundle specific files (like AppBundle.php and DependencyInjection/), to src/. Remove src/AppBundle/.

    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.

  8. Move the public assets, such as images or compiled CSS/JS files, from src/AppBundle/Resources/public/ to public/ (e.g. public/images/).
  9. Move the source of the assets (e.g. the SCSS files) to assets/ and use Webpack Encore to manage and compile them.
  10. 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.
  11. Update the bin/console script copying Symfony's bin/console source and changing anything according to your original console script.
  12. Remove the bin/symfony_requirements script and if you need a replacement for it, use the new Symfony Requirements Checker.
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Show your Symfony expertise

    Show your Symfony expertise

    Code consumes server resources. Blackfire tells you how

    Code consumes server resources. Blackfire tells you how

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Neagu Cristian-Doru, a Symfony contributor

    Thanks Neagu Cristian-Doru (@cristian-neagu) for being a Symfony contributor

    2 commits • 44 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia