Atomic Design Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>. The 1.0.12 release widens the constraint to sensio/framework-extra-bundle: ^5|^6, so check what your lock file resolves to before assuming behaviour is unchanged.
• Look first at the DI extension + Configuration class (the TreeBuilder). That is where the new assets package-name option lives, and it tells you the exact key path far faster than the docs.
• Symfony-style registration: add the bundle to config/bundles.php and import config/packages/<alias>.yaml. If you are coming from Laravel, mentally map this to a service provider + config/*.php pair — the mechanics are different, the intent is the same (bind config, register services, expose a facade/helper).
• First use case: point the bundle at a named asset package and render an asset through it. Set the package name, clear the container cache, and confirm the resolved value with bin/console debug:config <alias> before wiring anything else.

Implementation Patterns

• Config-first, not code-first. The asset package name is a config value, so prefer per-environment YAML (config/packages/dev/, config/packages/prod/) over branching in code. Same bundle, different asset host per env.
• Name your packages deliberately. The new option refers to a key inside framework.assets.packages — not the Composer package name. Create an explicit named package (e.g. app_assets) and reference that, so you can swap base URLs/paths later without touching the bundle config.
• Multi-tenant / multi-app reuse. Because the package name is now configurable rather than hard-coded, one service definition can serve several apps or tenants — bind the package name as a parameter and override per container.
• Composer constraint hygiene. If you support both sensio/framework-extra-bundle majors, mirror the package's approach (^5|^6) and test the matrix; v6 changes transitive requirements.
• Keep the Symfony/Laravel boundary explicit. In a Laravel codebase, either consume the package as a standalone library behind your own adapter, or run it in a Symfony service container. Do not let bundle classes leak into controllers/jobs — wrap them in an interface you own so the dependency stays swappable.
• Compile-time config means rebuild-time errors. Treat config changes like code changes: bin/console cache:clear (or cache:warmup) belongs in your deploy script, not in someone's shell history.

Gotchas and Tips

• v6 is not a drop-in. sensio/framework-extra-bundle 6.x raises the floor on PHP and Symfony versions and drops older annotation handling. Run composer why sensio/framework-extra-bundle and read its UPGRADE notes before bumping — a green CI on 1.0.11 says nothing about 1.0.12 with v6 resolved.
• The "Assets package name" is an asset package key. If it doesn't exist in framework.assets.packages, you get the default package or a confusing container error — never a friendly "unknown package" message. Verify with debug:config framework assets and debug:container --parameter=<param>.
• Silent fallbacks are the classic bug. An unset/blank package name often degrades to defaults in dev (where assets are served locally) and only breaks in prod (CDN/manifest). Test the prod build, not just dev.
• Cached container is the #1 false alarm. "My config change did nothing" is almost always a stale container in var/cache/. Clear it before debugging anything else.
• Dependency conflicts surface late. Both release notes are compatibility/config changes, so the failure mode is a resolution error or a subtly different service graph — not a stack trace in your code. Pin the transitive versions you actually tested.
• Extension points: decorate the bundle's service rather than forking it, and if you need behaviour the config doesn't expose, override the DI extension's parameter in your own services.yaml — but note that this is unsupported surface and will break on minor bumps.
• Versioning signal: a 1.0.x line adding major-dependency support and a new config option suggests the API is stabilising. Reasonable time to adopt; still not a reason to skip the upgrade test matrix.