Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 62 ยท Getting Started

Flex, Recipes and Bundles

See how composer require sets up a Symfony package for you: Flex recipes, symfony.lock, bundles vs plain packages, config/bundles.php and packs.

In most PHP projects, installing a library is only half the job. You also create a config file, add an environment variable, register a service and remember the right namespace. In Symfony, composer require symfony/mailer does all of it in one command. The tool behind this is Symfony Flex, a Composer plugin that runs recipes: small, versioned instructions that tell Flex which files to copy and which settings to add when a package is installed.

This lesson explains what Flex does, what a recipe contains, how symfony.lock and config/bundles.php fit in, the difference between a bundle and a plain package, and what a pack is. The commands are real and read-only; the runnable examples are stand-ins that perform the same steps on in-memory data, so you can watch the recipe mechanism work.

What Flex does

Flex hooks into composer require and composer remove. When you install a package, Flex checks whether a recipe exists for it in the recipe repositories. If one does, Flex applies it:

Terminal
composer require symfony/mailer

Typical effects of a recipe:

  • Copies configuration files into your project, for example config/packages/mailer.yaml.
  • Registers the bundle in config/bundles.php, if the package has one.
  • Adds environment variables with safe defaults to .env, for example MAILER_DSN.
  • Adds scripts or ignore rules, for example entries in .gitignore or composer.json.
  • Creates directories or sample files the package expects.

When you run composer remove symfony/mailer, Flex unconfigures the recipe again. Flex also lets you use short aliases: composer require twig installs symfony/twig-bundle, and composer require orm installs the Doctrine pack.

flowchart TD
    A["composer require vendor/package"] --> B["Composer installs the package"]
    B --> C{"Recipe available?"}
    C -- "yes" --> D["Flex applies the recipe"]
    C -- "no" --> G["Nothing is configured<br/>(you configure it by hand)"]
    D --> E["Copy config files<br/>Register bundle<br/>Add .env lines"]
    E --> F["Record in symfony.lock"]

Composer always installs the code; Flex adds the setup steps only when a recipe exists.

Where recipes come from

Recipes live in two public repositories. The main recipes repository contains reviewed recipes for Symfony's own packages and well-known libraries. The contrib repository holds community recipes, which are less strictly reviewed, and Flex asks you before installing one. Each recipe is versioned: version 1.0 of a package may have a different recipe than 2.0, so a recipe always fits the package version you install.

You can see and manage them from the command line:

Terminal
composer recipes                       # list installed recipes and whether updates exist
composer recipes symfony/mailer        # details of one recipe
composer recipes:update symfony/mailer # review and merge a newer recipe
composer recipes:install symfony/mailer --force   # re-apply a recipe

Updating recipes is a normal maintenance task after upgrading Symfony. Flex shows the recipe changes as a Git-style patch, so you merge them into your own config the way you merge code.

A recipe is just data

A recipe has a manifest listing what to do. Here is the idea in simplified form:

JSON
{
    "bundles": {
        "Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle": ["all"]
    },
    "copy-from-recipe": {
        "config/": "%CONFIG_DIR%/"
    },
    "env": {
        "MAILER_DSN": "null://null"
    }
}

The next example is a stand-in that applies a manifest like this to an in-memory project. It is not Flex, but it follows the same three steps, and it also shows that removing the package undoes them.

PHP Applying a recipe (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

symfony.lock

Flex records every recipe it applied in symfony.lock:

JSON
{
    "symfony/mailer": {
        "version": "7.4",
        "recipe": {
            "repo": "github.com/symfony/recipes",
            "branch": "main",
            "version": "4.3"
        },
        "files": ["config/packages/mailer.yaml"]
    }
}

This file answers one question: which recipes are already installed, and in which version? Flex uses it to avoid applying a recipe twice and to offer updates later. Commit it next to composer.lock, because your teammates must see the same recipe state. If you delete it, Flex thinks no recipe was applied and may try to reinstall them.

Bundles and packages

A package is anything you can install with Composer: a library, a framework, a tool. A bundle is a special kind of package that plugs into the Symfony kernel. A bundle can register services, add configuration options, ship routes, templates, translations and console commands.

The difference matters:

  • monolog/monolog is a plain package: a logging library that works anywhere.
  • symfony/monolog-bundle is a bundle: it integrates that library into Symfony, so you configure loggers in config/packages/monolog.yaml and get the logger as an autowired service.

Many libraries come in this pair. Libraries that are used from your own code without any container integration (a PDF generator, a money class) are plain packages and need no registration.

Enabled bundles are listed in config/bundles.php:

PHP
<?php

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true],
    Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
];

Each key is a bundle class, and the value says in which environments it is active. The debug toolbar bundles are enabled only in dev (and test for the profiler), so production never loads them. The kernel reads this array when it boots. This stand-in does the same filtering:

PHP Which bundles load in each environment? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Packs

A pack is a package with no code of its own. Its composer.json only requires a group of other packages that are usually installed together. For example, composer require orm installs the Doctrine pack, which brings the ORM, the Doctrine bundle and the migrations bundle in one go. Packs are a convenience for beginners: one memorable name instead of five package names. Flex can unpack a pack, so that the individual packages appear in your composer.json and you can remove the ones you do not want:

Terminal
composer require orm
composer unpack symfony/orm-pack

Why use Flex?

Flex makes Symfony's modularity practical: you start with a tiny skeleton and add features one command at a time, each arriving pre-configured. The cost is that files appear in your project that you did not write. Always read the output of composer require, look at git status afterwards, and commit recipe changes separately from your own work. Then you always know what a package changed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Symfony Flex do when you run composer require symfony/mailer?

    Composer installs the code; Flex then runs the recipe (if one exists) to configure the package.
  2. 2. What is the purpose of symfony.lock?

    symfony.lock tracks the installed recipes and their versions. composer.lock tracks package versions.
  3. 3. How is a bundle different from a plain package?

    Plain packages are ordinary libraries; bundles plug into the kernel and are registered in bundles.php.
  4. 4. What does ['dev' => true] next to a bundle in config/bundles.php mean?

    Environment keys enable the bundle only for those environments. all enables it everywhere.
  5. 5. What is a Symfony pack?

    Packs are shortcuts: one name that installs several related packages.

Summary

  • Flex is a Composer plugin: after composer require, it applies a package's recipe if one exists.
  • A recipe copies config files, registers bundles, adds .env variables and similar setup, and composer remove undoes it.
  • symfony.lock records applied recipes; commit it with composer.lock. Update recipes with composer recipes:update.
  • A bundle plugs into the kernel and is enabled per environment in config/bundles.php; a plain package is just a library.
  • A pack is a package that only groups other packages, and composer unpack turns it into explicit dependencies.
  • Always review what a recipe changed with git status and git diff.

Next up: From Request to Response.