Symfony recipes contrib: community-maintained install recipes for Composer packages

What a recipe is, and what this repository holds

Symfony recipes allow the automation of Composer packages configuration via the Symfony Flex Composer plugin, and this repository hosts contributed recipes for Composer packages that are not part of the official Symfony recipes.

A recipe is the small piece of automation that makes a package usable on arrival. When Flex installs a package that has a recipe, the recipe can add a configuration file, register a service, add a route, or set an environment variable, so that the package works immediately rather than sitting in the dependency list as a library nobody has configured. The alternative is well known to anybody who has used a bundle outside the Symfony distribution: you add the package, and then you read its documentation to find out which configuration file it wants and which keys it needs.

The split between the official repository and this one is about who maintains the recipe. The official recipes cover the packages Symfony itself ships and maintains, and they get the same review as the framework. The contrib repository covers everything else, and the readme is explicit that the pull requests for new contrib recipes are managed by the community, unlike for official recipes.

That is the whole scope of the project, and it is a large one. The repository tree is a directory per vendor, with entries running from 21torr and abel through to broadway and beyond, so the number of packages covered is in the hundreds rather than the dozens. The README is written in reStructuredText and links to RECIPES.md for the full list of recipes that live in the repository, and that file lives on the flex branch rather than on main, which tells you the recipes are consumed from the flex branch of the repository.

The project is MIT licensed, the primary language is PHP, the default branch is main, and the last push to the repository was on 2026-10-19. There are no GitHub releases, which is consistent with a repository whose artefacts are files in a directory rather than packages.

Turning it on, and the one setting that does it

Enabling the contributed recipes for your project is a single Composer configuration command:

composer config extra.symfony.allow-contrib true

The reason it is opt-in rather than on by default is worth understanding, even though the documentation does not argue it at length. A recipe writes files into your project, typically into the configuration directory, and in the case of some recipes into a routing file. Turning that on for every package in the world by default would mean a `composer require` could modify your configuration in a way you did not anticipate, and the security review of a pull request that adds a recipe would have to cover what it writes and where.

So the setting is a deliberate, per-project decision, and it is set in the project's own Composer configuration where it is visible in a diff.

Once it is set, Flex consults the contrib repository when it resolves a package, and applies the matching recipe if there is one. The list of what is available is RECIPES.md, which the readme points at, and that is the file to consult before you require a package to find out whether a recipe exists and what it will do.

The practical effect for a team is that installing a package stops being a two-step affair. You require the package, Flex applies the recipe, and the configuration is in place with the values that need setting left as placeholders for you to fill in. That is the whole value proposition, and it is why the repository exists at all.

The merge rules, which are unusual for a Symfony repository

The contribution process is the part of this repository that differs most from a normal open source project, and it is worth reading carefully before you plan to contribute.

The readme says that unlike for official recipes, the pull requests for new contrib recipes are managed by the community, and that pull requests are reviewed by the Symfony Bot and automatically merged when the following conditions are met, in that order.

The title does not contain WIP.

The Symfony Bot approved the pull request and reported no validation errors.

Someone, and the wording is precise, not the Symfony bot nor the pull request author, approved the pull request.

And the pull request author or the reviewer is a Symfony Core Merger.

That last condition is the one that shapes the process. A community-managed repository, with a bot doing the mechanical validation and a human doing the review, still requires a Core Merger somewhere in the loop before the change lands. That is a deliberate quality gate for a repository whose contents are executed on other people's machines during an install, and it explains why the contribution flow is slower than the official recipes even though the reviewing is community-run.

The bot does the mechanical work. The human approval catches the semantic problem, which is that a recipe is a small program of sorts, and the Core Merger requirement is the backstop for the case where a recipe is technically valid and reviewed but still does something the project would not want every user to get.

The contributing documentation points at the main repository for the mechanics of writing a recipe, and the readme carries a set of best practices that is the actual specification of what a good recipe looks like.

The best practices, and what makes a recipe bad

The best practices section is the most useful part of the documentation for anybody writing a recipe, and it is mostly about restraint.

The first rule is about default bundle config. A recipe for a bundle should not contain all the configuration the bundle has to offer. A good recipe only contains a suggestion config for an application, meaning config that needs to be configured but where no real default value exists.

The examples make the distinction concrete. The items per page in a paginator bundle, or API credentials for an API client bundle. Both are values that the application must choose and that the library cannot guess. A page size of 20, or a set of API keys, is not the same kind of thing, and the first kind belongs in a recipe while the second kind is the bundle's own default configuration.

The corollary is about environment variables. If environment variables are used, they must be provided to the bundle's config, which is a specific requirement rather than a general style note.

The second rule is about when a recipe is not needed at all. A bundle without config or routes does not need a recipe, because Flex is smart enough to install that bundle anyways. That is a useful thing to know, because the easiest way to write a bad recipe is to write one that exists only to say nothing.

The third rule is the most interesting one, because it is about restraint in the other direction. The general rule is that no recipe should modify other bundle's configuration, with one exception: a recipe is allowed to append to a config collection. The examples are adding a new connection to DoctrineBundle, or adding a new cache adapter to the Symfony Framework bundle. Appending to a list is safe because the list is designed to be appended to, and editing a value that another bundle owns is not.

The last section is about maintainability, and it is the strictest. The repository should contain the config for packages, and using the copy-from-package Configurator for routes and config is not allowed, because that would make the recipes impossible to maintain and to assure their quality. Copying a file out of the package at install time saves the author of the recipe a little work and costs everyone the ability to know what the file contains, since it changes with every version of the package.

And the last rule is about scope. Recipes is not a replacement for composer create-project, so it is not intended to be used to bootstrap a full application and copy a lot of PHP code and front-end assets. Recipes are for quick installation of packages.

Where contrib recipes are the wrong tool

The first limit is that a recipe is configuration a third party wrote for a package you use, and it lands in your project without further ceremony once the flag is on. That is the point, and it is also the risk. The recipe's contents are reviewed, but a project that treats its configuration directory as a security boundary, with secrets and access rules in it, should look at what a recipe writes before it lands rather than after.

The second is the merge latency, which follows from the Core Merger requirement. For a package nobody has written a recipe for, and for a contributor who is not a Core Merger and does not know one, the path to a merged recipe involves a reviewer who satisfies that condition. That is a slow path for a project that wants a package configured today, and the practical answer for a team is often to write the configuration themselves, which is a small amount of work for one package and does not scale to many.

The third is that the recipes reflect a package's own documentation and conventions, and packages change. A recipe that assumes a bundle's configuration format from two years ago will still apply after the bundle changes, and the failure mode is a configuration file that no longer does what the package expects. The contrib repository has no mechanism to invalidate a recipe when a package changes its configuration, so the correctness of a recipe is a function of the package version you happen to be on.

The fourth is the scope rule biting in the wrong direction. The best practices are written to keep recipes small, which is good, but a package whose integration genuinely requires a dozen files, a service definition, a route and a set of env vars is not going to be well served by a recipe that is allowed to be a suggestion. Those packages need documentation, and the repository's own position, that recipes are not a replacement for composer create-project, is the same position taken from the other side.

And the fifth is that enabling contrib recipes changes what composer require does in your project, for every future package, not just the one you wanted. The setting is a single boolean, and once it is on, the set of packages that write into your configuration directory grows without a per-package decision. A team that wants to review the configuration change of each new dependency has to keep the flag off and write the configuration by hand.

Editorial conclusion

Symfony recipes contrib is worth enabling in a Symfony project that installs packages from vendors the core team does not maintain, because the alternative is a package installed with no configuration at all, which is the situation that produces the afternoon spent reading a bundle's docs to work out which env vars it wants. It is the wrong tool if you want a skeleton application, and it is the wrong tool if your project treats third-party configuration as a security decision. Before you turn it on, check three things: that you understand the merge rules, because a contrib recipe is merged only when the title contains no WIP, the Symfony Bot approves it with no validation errors, a third person approves it who is neither the bot nor the author, and either the author or the reviewer is a Symfony Core Merger, which is a much slower path than the official repository; that you read the best practices, in particular the rule that a recipe should carry a suggestion config rather than the full configuration of a bundle, and that a bundle with no config or routes does not need a recipe at all; and that you know what enabling it changes, because the setting is per project and it makes Flex apply contributed recipes during install, so a package that arrives with a recipe will have files written into your configuration directory.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. symfony/recipes-contrib on GitHub