Bundle Dependency Laravel Package

Getting Started

Check compatibility before anything else. The last tagged release is February 2018, which puts it in the Symfony 3.4 / 4.0 era, PHP 7.x, and Doctrine annotations. Run composer require symfony-bundles/bundle-dependency --dry-run and read the constraints. On PHP 8 / Symfony 5+ expect to need doctrine/annotations and to test on a throwaway branch first; annotations were deprecated in favor of PHP attributes, and this package almost certainly predates that.

Install and register:

composer require symfony-bundles/bundle-dependency

Then add the bundle to config/bundles.php (or AppKernel::registerBundles() for legacy apps). Register it early — it needs to participate before or during bundle resolution.

Read three things in vendor/symfony-bundles/bundle-dependency/src/ before writing code, because the README is thin and the exact API names matter:

1. The annotation class (Annotation/ or similar) — this is the syntax you put on bundle classes. The examples below use @RequiresBundle, but substitute the real name.
2. The resolver (search for sort, topolog, resolve) — the entry point that turns annotated bundles into an ordered list.
3. The compiler pass / kernel hook (DependencyInjection/) — this tells you whether the package reorders bundles or only validates their order. That distinction drives your whole integration strategy.

First use case. In a scratch branch, pick two bundles where B genuinely needs A initialised first. Annotate B:

/**
 * @RequiresBundle(Acme\ABundle::class)
 */
class BBundle extends Bundle
{
}

Then either feed your bundle list through the package's resolver, or boot the kernel and see what the package reports. Confirming the mechanism on two bundles is the fastest way to learn the package — do that before annotating a dozen bundles.

Verify the result. bin/console debug:container --parameter=kernel.bundles (or a temporary var_dump in registerBundles()) shows the actual boot order. Compare it with what you declared.

Implementation Patterns

One direction only: "what I need", never "what needs me". Annotations describing requirements keep the graph a DAG and make each annotation independently safe to delete. Do not model reverse edges.

Centralise the list and resolve once. In Symfony Flex, config/bundles.php is a plain require, so it can execute code. If the package exposes a resolver, this is the cleanest integration:

// config/bundles.php
use SymfonyBundles\BundleDependency\DependencyResolver; // verify name in src/

return DependencyResolver::sort([
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Acme\ABundle::class                                  => ['all' => true],
    Acme\BBundle::class                                  => ['all' => true],
]);

If the package only validates ordering rather than reordering, keep the array hand-ordered and treat the package as a lint step. Either way, there should be exactly one source of truth — not annotations and hand-ordering comments.

Wrap vendor bundles you cannot annotate. If VendorBundle must precede yours and you can't edit it, create a tiny local bundle whose only job is @RequiresBundle(VendorBundle::class), and require that local bundle from the dependent one. Alternatively, resolve only your own bundles and keep third-party ones in a small, explicit ordered block.

Make CI the primary consumer. The real value is failing fast on missing or circular dependencies. Add a CI step that boots the kernel (or invokes the resolver directly) for each environment — dev, test, prod — because an env-specific bundle list can hide a missing dependency that only appears in prod.

Do not rely on bundle order for container configuration. Bundle registration order affects build() / boot() order, but compiler passes and prependExtension merging still need explicit priorities. If two bundles contribute config that must merge in a particular sequence, use a CompilerPass with a priority — not this resolver.

Incremental migration. Annotate the "leaf" dependency of each cluster first, run the resolver, fix errors, repeat. Remove manual ordering comments as you go, otherwise humans will silently reorder the array and defeat the purpose.

Keep the graph environment-stable. Don't declare DebugBundle / WebProfilerBundle as hard dependencies of application bundles. Either keep the graph identical across environments, or resolve per environment with deliberate, documented divergence.

Unit-test the graph. If the resolver is a standalone class, test it with stub bundle classes: missing dependency, cycle A → B → A, self-cycle. Those three tests are your regression net for future annotation edits.

Gotchas and Tips

• It's from 2018 and unmaintained. Pin the exact version. If it breaks on a Symfony or PHP upgrade, a topological sort is roughly 50 lines — forking or replacing it is usually cheaper than fighting it.
• Annotation reader requirements. Doctrine annotations need doctrine/annotations installed and the reader service enabled. Bundle classes must be named, autoloadable, and non-anonymous — the reader looks them up by FQCN.
• No PHP 8 attributes unless the package has been updated since release. If you're on PHP 8, verify before committing to an annotation-based workflow.
• "Automatic ordering" may actually mean "validation". Test this on day one. If it only validates, don't delete your manual ordering from bundles.php.
• Stale cache masks changes. The order and any resolved errors are computed during kernel build. Always bin/console cache:clear after editing annotations, and remember that cache:warmup in prod can surface errors that dev never showed.
• False "missing dependency" reports. The resolver sees registered bundles, not composer.json. A bundle installed but disabled in bundles.php, or enabled only in dev, will be reported as missing. Check the bundle list for the active environment.
• Circular dependencies usually mean a design leak. Two bundles that each require the "convenience" of the other need the shared code extracted into a third bundle. Don't try to break the cycle with annotations.
• Bundle order and compiler passes are different problems. kernel.bundles is populated before build(), so passes can inspect the final order — but service definitions from two bundles still merge according to compiler-pass priority, not bundle order.
• Debug by dumping the computed order. Decorate the resolver (or add a temporary var_dump before sorting) and log the final list. When boot fails deep in a third bundle, knowing the resolved order saves hours.
• Don't use it inside reusable third-party bundles. composer.json require is the contract for library dependencies. This package is application-level ordering sugar for bundles you control.
• Performance is a non-issue for typical apps; annotation scanning adds a little overhead, so resolve at kernel build time rather than per request.