What is the difference between recipes, bundles and packages?

[nbro]

If I understand correctly, bundle is a synonym for package, but a recipe is something different. It seems that a recipe is a Symfony Flex concept. My understanding is that a recipe is a way to install a bundle (aka package) and automatically set certain configuration options for that bundle/package.

If this is all correct, I don't understand why aren't all packages recipes and why is Symfony Flex not integrated into composer. Why isn't the installation of recipes the default behavior? Are there cases where we need just to install bundles without sensible defaults? If yes, can you provide a few examples?

Also, is there a command, which I can type on the terminal, that lists only the recipes, and another that lists only the packages, or a single command that can show if something is a recipe or just a bundle? I couldn't find that in composer show --help

[Trismegiste]

Short summary :

• Package : a PHP library managed by composer that (generally) goes into /vendor. No need for symfony.
• Bundle : a package integrated for Symfony that adds controllers, assets, config files, twig templates...Files goes into /vendor too, therefore unversioned in git. A bundle adds a class into the list in /config/bundles.php (this is a "default recipe" in a way)
• Recipe : add/edit files outside vendor folder : it could add a config files, edit a docker-compose.yml for example...

[nbro]

Can you provide an example of a package, bundle and a recipe?

If a bundle is a package written specifically for Symfony, then when would you need to install a non-Symfony package in a Symfony project?

What do you mean by "Recipe : add/edit files outside vendor folder"? Is a recipe a package or not? Or is it just something that adds config files and it's not a package itself? I had already understood that recipes involve config files. My question was more - if recipes are bundles or packages that also set up certain sensible config options, why shouldn't all packages and bundles be recipes?

[mbabker]

If this is all correct, I don't understand why aren't all packages recipes and why is Symfony Flex not integrated into composer. Why isn't the installation of recipes the default behavior? Are there cases where we need just to install bundles without sensible defaults? If yes, can you provide a few examples?

Composer is a tool for all of PHP. Flex is a Composer plugin that hooks into Composer to do some stuff for Symfony applications. So it can't just be integrated into Composer because many of the things Flex does don't apply to Laravel, Laminas, Yii, or framework-less environments.

If I understand correctly, bundle is a synonym for package, but a recipe is something different. It seems that a recipe is a Symfony Flex concept. My understanding is that a recipe is a way to install a bundle (aka package) and automatically set certain configuration options for that bundle/package.

For Composer, there is no difference between a package and a bundle. A bundle is a Symfony framework concept, the common use cases include integrating a standalone PHP package into a Symfony application or extending Symfony framework features.

A recipe is indeed a feature of the Flex plugin. It's entirely opt-in, but part of what it offers is the ability to add in opinionated default configurations and files to your Symfony application.

If a bundle is a package written specifically for Symfony, then when would you need to install a non-Symfony package in a Symfony project?

Because most of the time bundles are integrating PHP packages that don't have Symfony-specific optimizations built right into them. Two examples of different types of bundles and their relationships with more generic PHP packages:

• The DoctrineBundle integrates Doctrine's DBAL and ORM into Symfony applications and adds Symfony-specific functionality for those libraries (i.e. the debug tooling that makes its info available in the web profiler)
• The LexikJWTAuthenticationBundle extends Symfony's security system and adds support for JWT-based authentication, and under the hood, it uses several other PHP packages to offer that functionality

[kira0269]

This an example of my symfony.lock:

{
    "artgris/filemanager-bundle": {
        "version": "2.7.1"
    },
    "doctrine/annotations": {
        "version": "2.0",
        "recipe": {
            "repo": "github.com/symfony/recipes",
            "branch": "main",
            "version": "1.10",
            "ref": "64d8583af5ea57b7afa4aba4b159907f3a148b05"
        }
    },
    "friendsofphp/php-cs-fixer": {
        "version": "3.16",
        "recipe": {
            "repo": "github.com/symfony/recipes",
            "branch": "main",
            "version": "3.0",
            "ref": "be2103eb4a20942e28a6dd87736669b757132435"
        },
        "files": [
            ".php-cs-fixer.dist.php"
        ]
    },
    "symfony/debug-bundle": {
        "version": "6.2",
        "recipe": {
            "repo": "github.com/symfony/recipes",
            "branch": "main",
            "version": "5.3",
            "ref": "5aa8aa48234c8eb6dbdd7b3cd5d791485d2cec4b"
        },
        "files": [
            "config/packages/debug.yaml"
        ]
    },
    ...
}

As you can see, you will find either:

• bundles with no recipe (artgris/filemanager-bundle)
• packages (not bundles) without recipe (phpcsfixer)
• packages with recipes (doctrine/annotations)
• bundles with recipes (symfony/debug-bundle)

[nbro]

It seems that packages can be both in composer.lock and symfony.lock. For example, in my case, api-platform/core appears in both. So, I suppose that composer also keeps tracks of the Flex packages/bundles and Flex, for some reason, just maintains the separate file symfony.lock with the packages it maintains too. Maybe the reason is that Flex needs a new syntax to also keep track of other info, including the recipes.

[mbabker]

So, I suppose that composer also keeps tracks of the Flex packages/bundles

No, that's not how it works.

Composer is the package manager, it keeps track of all the dependencies for your application and the versions that those dependencies are running at. Without Composer, none of it works.

Flex is a Composer plugin adding Symfony-specific functionality to the Composer workflow. Part of that functionality is in applying recipes. The metadata the Flex plugin uses for keeping track of those recipes is completely separate from the Composer metadata for keeping track of all of your application's dependencies so that information is tracked in a separate lock file.

The composer.lock file and symfony.lock are not functionally equivalent and you shouldn't try to tie them together.

[nbro]

That's exactly what I wrote in my last comment. Also, you say "No, that's not how it works.", but then you say that composer keeps tracks of all the dependencies, which means it also keeps track of the "flex dependencies".

[mbabker]

There isn't a notion of "Flex dependencies" though. Flex has metadata to keep track of what packages are installed and what recipes it applied, and that is the metadata it writes to symfony.lock. But in no way is Flex involved with managing the application's dependencies; that is all Composer. You're trying to tie the two systems together when in reality they're only loosely related because Flex (because of the features it provides) has to run as a Composer plugin. Truthfully, all of the recipe stuff could be extracted and run in its own standalone CLI tool, but then all the DX convenience the plugin provides is basically wiped out.