Docker Compose Generator Bundle Laravel Package

Getting Started

• Set expectations first: this is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/*.php publish tag, no Artisan command. Composer will install it, but nothing in Laravel's bootstrap will register or use it. Treat it as a reference implementation or a standalone generator you invoke from a script, not as an artisan-driven tool.
• Look at the source before doing anything else. Read vendor/klke/docker-compose-generator-bundle/DependencyInjection/Configuration.php (the real option surface — READMEs on 4-star packages are usually stale) and Resources/config/ (service wiring + any Twig/YAML template used for output). That template is the only thing that determines whether the output is useful to you.
• Decide which path you're on before installing:
  1. "Reference" path — read the template, understand the shape of a generated compose file, then hand-write your own for Laravel. Zero runtime dependency. Recommended.
  2. "Standalone" path — vendor or fork the generator, call it outside Laravel's lifecycle (a bin/ script or Make target) to emit a compose file for a throwaway test topology.
  3. "Graft" path — attempt to register the bundle and pull Symfony DI/config machinery into a Laravel app. Architecturally hostile; only do this if you own a mixed Symfony/Laravel monorepo.
• If you attempt the Symfony path (mixed repo only): the bundle must be added to config/bundles.php before any command exists. If a bin/console list | grep -i docker returns nothing, it's not registered — that's the first thing to debug, not the last.
• First real use case for a Laravel developer: a test suite that needs a real database + queue/redis to run functional tests. Use the generator (or its template) as a starting reference to produce a docker-compose.test.yml with app + mysql + redis, then point .env.testing at the compose service hostnames. Compare that output against laravel/sail — Sail almost certainly already does it, better.
• Do not put this in require. If it goes in at all, composer require --dev klke/docker-compose-generator-bundle and keep it out of the deployed application.

Implementation Patterns

• Generate once, commit, then own it. The realistic Laravel pattern is: run the generator (or use its template as a guide), commit the resulting docker-compose.yml, hand-edit it, and stop regenerating. Re-running over a customized file is how you lose an afternoon to a clobbered override.

• Wrap generation in a script that refuses to overwrite. [ -f docker-compose.yml ] || php scripts/gen-compose.php inside a make docker-init target, printing a diff if the file already exists. This gives you the convenience once and prevents the clobbering forever.

• Prefer the standalone invocation over an in-app integration. A bin/generate-compose PHP script that requires the generator classes directly (bypassing Symfony's Kernel) is far more palatable than dragging Symfony's DI into a Laravel app. You get the compose output without the framework coupling.

• Let env vars drive both sides. Keep the generated file using ${DATABASE_URL} and ${REDIS_HOST}-style interpolation so a single .env.testing feeds both Laravel's config/database.php and the compose services. Otherwise the compose file and your config/ drift apart silently.

• Name services to match Laravel's config expectations. A service named db means DB_HOST=db reads correctly in config/database.php and survives a MySQL image bump. Names like mysql-primary-1 break the mental model and force you to edit config every time.

• CI pipeline pattern:

  generate (if absent) → docker compose up -d --wait → migrate → phpunit → docker compose down -v
  

  The --wait and a healthcheck on the DB are the pieces generators rarely give you; add them yourself.

• Extend via docker-compose.override.yml, never by forking the template. Healthchecks, init SQL, fixtures, mailhog, Xdebug toggles — all of these are things the generator won't model. An override file upgrades cleanly; a patched Twig template does not.

• If you're in a mixed Symfony/Laravel monorepo, run this generator only in the Symfony sub-app's build step and share the resulting compose topology with the Laravel side via a committed .yml. Don't try to run it from the Laravel side.

• Treat the generator as a spike, not a standard. Time-box the evaluation to a day: generate a compose file for one non-critical service (a test DB), diff it against what Sail produces, and reject unless it's strictly better. It usually isn't.

Gotchas and Tips

• Symfony DI conflicts with Laravel's transitive Symfony packages. Laravel ships several symfony/* components pinned by the framework. A bundle requiring a divergent major version can force a composer update resolution fight. If you see conflict errors, that's not a bug in your app — it's the architecture mismatch.
• "Command not found" is the default state on Laravel. No bundle = no command. If you expected php artisan docker:generate, it does not exist. Don't spend an hour looking for it.
• The config tree is Symfony-style (Configuration.php returning a TreeBuilder), not Laravel-style arrays. Options you set in config/packages/*.yaml have no equivalent in Laravel's config/*.php. Any attempt to "port" the config is a rewrite, not a copy.
• Generated output ages quickly. PHP image tags, MySQL versions, and the Compose spec move. A generated file from six months ago is a source of silent CI drift. Pin image digests/tags explicitly in whatever you commit, and treat the generated file as a starting point you'll maintain.
• Overwrite hazard is real and asymmetric. Regeneration clobbers manual edits; without a provenance header (e.g. # generated by klke/... — edits will be lost) the team discovers this late, usually in CI. Add the header yourself, or gate the generator so it can't run over an existing file.
• Port and volume collisions on shared CI runners. Generated topologies rarely namespace volumes or shift ports. On a shared runner, two jobs generating the same file will fight over 3306/volume names. Use COMPOSE_PROJECT_NAME per job and prefer ephemeral volumes.
• Maturity is the headline risk: 4 stars, 0 dependents. Assume abandonment is the base case. If you adopt, fork it into your org so you control the template and can patch the Compose/PHP versions yourself — don't rely on upstream releases for version tracking.
• Compare against the two-line Sail answer every time. composer require laravel/sail --dev && php artisan sail:install covers 90% of what this package aims at, is first-party, and is already known to your team. The bar for using this instead is a specific gap Sail does not fill — write that gap down before installing.
• Debugging has no community corpus. No Stack Overflow answers, no issue history to mine. When it misbehaves you read the source or you're stuck. Budget for that: a capable dev can read the generator in under an hour, but expects zero external help.
• Keep it strictly dev-only. Anything that writes infrastructure definitions should never be a runtime dependency. If a production path ever requires the generator, that's a supply-chain decision you didn't make consciously.
• Extension points are the override file and a fork — nothing else. There is no plugin system, no output filter, no event hook you can meaningfully use from Laravel. Plan your customizations around docker-compose.override.yml and your own fork, not around the bundle's internals.