Getting Started

yceruto/bundle-flex is a Composer plugin that closes the gap Symfony Flex leaves for third-party bundles: when you composer require a bundle that has no Flex recipe, this plugin registers it in your project's config/bundles.php automatically, and removes the entry when you composer remove it. Think of it as "bundle registration as a side effect of dependency management."

Minimal steps:

Confirm prerequisites: Composer 2.x, a Symfony 4.4+/5.x+ app (i.e. one that already has config/bundles.php), and PHP version compatible with the plugin's composer.json.
Install it in the root project (plugins only run from the root package):
```
composer require --dev yceruto/bundle-flex
```
On Composer 2.2+ you will be prompted to allow the plugin. Accept it, or add it to config.allow-plugins in composer.json.
First use case: pick any bundle without a recipe and require it:
```
composer require acme/some-bundle
git diff config/bundles.php
```
If the plugin recognized the package as a Symfony bundle, you'll see a new Acme\SomeBundle\AcmeSomeBundle::class => ['all' => true] entry.

Where to look first:

config/bundles.php — the file the plugin mutates; this is your source of truth and should always be committed.
vendor/yceruto/bundle-flex/src/ — the plugin is small; read the event subscribers to see exactly which Composer events it hooks (post-package-install, post-package-update, post-package-uninstall or similar) and how it decides a package is a bundle (typically type: symfony-bundle and/or extra metadata).
The target bundle's composer.json — check its type and extra keys; that's what makes it "visible" to the plugin.
composer.lock — after a require, confirm the plugin version is pinned.

Given the package's age, low star count, and unknown repository status, treat step 2 as an evaluation step: run it in a scratch branch, inspect the diff, and only then adopt it in a shared codebase.

Implementation Patterns

The core workflow — require, review, commit. The plugin's value is purely at dependency-management time, so the natural pattern is:

git checkout -b add-some-bundle
composer require acme/some-bundle
git diff config/bundles.php     # inspect what the plugin wrote
bin/console cache:clear
git commit -am "Add acme/some-bundle"

Never let the plugin's write be invisible. It edits a committed PHP file, so it belongs in code review like any other change.

For bundle authors. If you maintain a bundle and want it to be picked up, declare it as a bundle in composer.json ("type": "symfony-bundle" plus, if the plugin requires it, an extra entry naming the bundle class). Verify by requiring it into a throwaway Symfony app with the plugin installed and checking that config/bundles.php updates and bin/console boots.

Coexistence with Symfony Flex. Flex handles symfony/* and recipe-bearing packages; this plugin handles the long tail. Keep them separate in your mental model: if a recipe exists, Flex wins and the plugin should have nothing to do. If both ever try to manage the same entry, that's a bug — see Gotchas.

CI and container builds. Because the plugin runs on composer install, it will re-add entries on a clean checkout if config/bundles.php is missing or was reset. Keep config/bundles.php committed so CI and production images use the committed state rather than relying on plugin execution. If you do want install-time registration in CI, ensure allow-plugins is pre-configured so composer install --no-interaction doesn't fail on the prompt:

{
  "config": {
    "allow-plugins": {
      "yceruto/bundle-flex": true
    }
  }
}

Environment awareness. Auto-registration typically appends ['all' => true]. That's fine for libraries like a mailer or an imaging bundle, but for bundles that must only load in dev (debug toolbars, fixtures, profilers) or only in prod, edit the entry by hand afterwards. Don't expect the plugin to infer environments.

Multi-app / monorepo. Plugins operate on the root package, so in a repo with several Symfony apps the plugin edits the root app's config/bundles.php. It is not a substitute for a proper monorepo dependency strategy; avoid requiring bundles at the workspace root if only one app needs them.

Companion to an internal recipe repository. If your organization runs a private Flex endpoint, prefer recipes. Reach for this plugin for the bundles you don't control or that haven't been reciped — it's the lowest-friction option for "third-party bundle, no recipe, don't want to hand-edit bundles.php."

Gotchas and Tips

Low adoption and unknown upstream. 18 stars and an unknown/possibly archived repository mean: no security response, no Composer 3 guarantee, no Symfony 7 guarantee. Pin an exact version, read the plugin source before trusting it (it runs with full filesystem access during install), and have an exit plan — forking the ~few-hundred-line plugin is realistic.
Composer 2.2+ allow-plugins is mandatory. Interactive installs prompt; non-interactive installs fail or silently skip the plugin. Always add the allow-list entry to composer.json and commit it, and test a fresh composer install --no-interaction in CI.
The plugin must be installed for the write to happen. If it's in require-dev and production runs composer install --no-dev, the plugin isn't there to register anything. That's fine only because you commit config/bundles.php. Never rely on production installs to generate bundle registrations.
Bundle ordering matters. Some bundles must be registered before others (Doctrine, Debug, Monolog handlers, bundles that decorate other bundles' services). Auto-append puts new entries at the end. If you hit "service not found" or "bundle X must be registered before Y," reorder by hand and expect the plugin to fight you on the next install.
Class-not-found after require. If the plugin writes the entry but the bundle class doesn't exist (wrong namespace, autoload not dumped, or the package isn't actually a Symfony bundle), the container fails to compile. Run composer dump-autoload and bin/console cache:clear, then re-check the class name in the package's composer.json.
config/bundles.php must exist and be writable. A missing file, a read-only checkout, or an unusual format (trailing content, multiple arrays) can break the rewrite. The plugin is not a general PHP rewriter; it expects the standard Flex-generated structure.
Debugging: run with composer require -vvv acme/some-bundle to see plugin events fire. If nothing happens, the package likely lacks type: symfony-bundle or the expected extra flag — inspect its composer.json and compare to a bundle that did get registered. composer diagnose catches plugin/allow-list misconfiguration.
Recovery is trivial — use git. If a write goes wrong, git checkout -- config/bundles.php and register manually. Treat the plugin as an accelerator, never as the only record of what your app loads.
Extension point: if you need custom logic (e.g., only register in dev, or write a different file), the practical route is forking and modifying the event subscriber, not configuring it — expect little to no configuration surface in a package this small.
Alternatives worth weighing: a private Flex recipe server (best long-term), Symfony's own bundle conventions plus a short make target that edits config/bundles.php, or simply manual registration. If your dependency churn is low, the manual option costs less than an unmaintained plugin.

Bundle Flex Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips