Fluent Symfony Laravel Package

Getting Started

• Install with composer require mnapoli/fluent-symfony. Because the project has been effectively unmaintained since 2017, pin the exact version in composer.json ("mnapoli/fluent-symfony": "dev-master#<sha>") rather than a floating constraint, so a fork or tag move can't break you silently.
• First place to look is the package's service-definition entry point (the wrapper around Symfony's ContainerBuilder). The core idea is that instead of declaring services in YAML/XML you build them in PHP with a chainable API: register a class, then attach arguments, method calls, and tags on the returned definition object.
• A first real use case: take one YAML service you already have and port it. E.g. a service that takes a scalar argument, one collaborator, and is tagged as a kernel event listener. This exercises every part of the fluent API (arguments, references, tags) in one small, testable example and lets you compare the DI behavior by running bin/console debug:container <id> before and after.
• Confirm the underlying Symfony version first: check composer.json of the package and bin/console --version. If you're on Symfony 4+, assume incompatibility until proven otherwise (see Gotchas).

Implementation Patterns

• Register-then-configure chains. The idiomatic flow is one expression per service: name + class, then .argument(...), .call(...), .tag(...). Keep each chain to a single service; splitting across statements makes diffs noisy but is fine when you need conditional config.
• References and parameters. To wire a collaborator use the fluent reference helper (equivalent to service('other.id')) rather than a raw string; to use a container parameter, reference the parameter helper (equivalent to %kernel.debug%). Passing a plain string that looks like a service ID is the most common source of silent misconfiguration.
• Tags as first-class chains. Event listeners, console commands, and twig extensions all become .tag('kernel.event_listener', [...]) calls. Keeping tag attributes inline with the service definition is the main day-to-day win over YAML.
• Hybrid configuration. You rarely port a whole app at once. Load the existing YAML/XML into the same ContainerBuilder, then add fluent definitions on top. This works because fluent-symfony is a thin layer over Symfony DI — order of loading matters only for overrides.
• Composition via a config function. Wrap your service registrations in a function/closure that receives the builder (function (FluentContainerBuilder $c) { ... }) and call it from your kernel/extension. This keeps the fluent block testable in isolation and lets you reuse it across kernels.
• Testing hook. In unit tests, build a container with only the service under test, compile it, and assert $container->get(Foo::class) returns an instance with the expected collaborators. This is faster and more precise than booting the full kernel.

Gotchas and Tips

• Abandonment is the headline risk. The last release predates Symfony 4. Symfony's DI has since gained native fluent/PHP config (ServicesConfigurator, PhpFileLoader). Before adopting this package, check whether services: in a PHP file under config/services.php already covers your need — for anything on Symfony 4.3+, it almost certainly does, and it's maintained.
• No autowiring. The package was built in the explicit-wiring era. There is no autowire()/autoconfigure() chain, so every argument is manual. On modern codebases this makes definitions more verbose than native Symfony, not less.
• Version pins break silently. Because dependencies are old, a composer update on an unrelated package can pull Symfony DI versions the fluent wrapper doesn't tolerate. Lockfile discipline and a CI job that runs bin/console debug:container are worth the setup.
• Compilation vs runtime. Errors from fluent definitions surface at container compile time (during cache:warmup), not at request time. If a service fails only in production, clear var/cache and warm up manually — that's where the actionable exception will be.
• Debugging. bin/console debug:container <id> --show-arguments shows what the fluent chain actually produced; compare it to the original YAML definition when porting. The chain itself builds a normal Definition, so all standard Symfony DI tooling applies.
• Extension point. If you need a chain the package doesn't expose (decorators, factories, lazy proxies), drop down to $container->getDefinition($id) and use the native Symfony API on it. The fluent object is a convenience layer, not a sealed abstraction — mixing is expected and safe.
• Decoration is fiddly. The fluent chain has no dedicated decorator helper in this generation of the package; use setDecoratedService() on the underlying definition. Watch the decoration priority argument, which is easy to omit and causes hard-to-diagnose ordering bugs.
• Migration tip. If you're adopting this to learn fluent DI, skip the package and read Symfony's own PhpFileLoader/ServicesConfigurator docs — same mental model, current and supported. If you've inherited a codebase on it, port one service file per sprint to native PHP config; the APIs are close enough to do it mechanically.