Rich Form Bundle Laravel Package

Getting Started

This is a Symfony bundle consumed inside a Laravel application, so the integration path is slightly different from a purely-Laravel package.

1. Verify prerequisites before installing. 2.0.0 requires PHP >= 7.2.5 and Symfony 5.1+. In practice this means:
   • Laravel 7.x (Symfony 4.4/5.x) may work if the Symfony packages resolve to ^5.1.
   • Laravel 8.x (Symfony ^5.1) is the safe baseline.
   • Laravel 6.x and earlier are not supported — Symfony version constraints will not resolve.

   php -v                    # must be >= 7.2.5 (prefer 7.3+/7.4+)
   composer show symfony/*  # verify installed Symfony components are >= 5.1
   

2. Install via Composer and confirm resolution:

   composer require <vendor>/<package>:^2.0
   

   If Composer throws a conflict against old symfony/* packages, upgrade the framework first (or the affected Symfony components) — do not try to force the constraint.
3. Look first at: the bundle's DependencyInjection/ and Resources/config/ directory to understand which services get registered, and any *Extension.php class (Laravel's container does not auto-load Symfony bundles — you register services manually or through a thin bridge provider).
4. First use case: register the package's service(s) in a Laravel service provider and inject them into a controller or console command. Confirm the container resolves the class before wiring it into business logic.

Implementation Patterns

• Bridge provider pattern. Wrap bundle service definitions in an App\Providers\*ServiceProvider and expose only the public entry points you need. This keeps Symfony's DI idioms out of your Laravel controllers.
• Service container delegation. Many bundles ship a compiler pass that mutates the container. In Laravel, translate that into explicit $this->app->singleton(...) / bind(...) calls so you retain control and can swap implementations for testing.
• Configuration bridging. Bundle Configuration.php trees (TreeBuilder) map cleanly to config/*.php files. Mirror the bundle's config keys 1:1 to reduce cognitive overhead; load them in register() via mergeConfigFrom.
• Console usage. If the bundle exposes Symfony Commands, adapt them by wrapping in Illuminate\Console\Command and delegating to the underlying service — do not register Symfony commands directly with Laravel's Artisan, as the InputInterface/OutputInterface handling differs.
• Feature-flagged upgrade. Because 2.0.0 removes BC layers, land the upgrade on a branch, keep the old version behind a feature flag where possible, and ship in one commit — mixing 1.x and 2.x call sites in the same request path is a common source of subtle breakage.
• Testing. In setUp(), exercise both the raw bundle service (unit) and the Laravel-resolved binding (integration). The removed BC layers in 2.0 frequently hide inside default constructor arguments — assert on real instantiation, not mocks.

Gotchas and Tips

• 2.0.0 is a hard break. "Removed BC layers" means 1.x-era method signatures, deprecated aliases, and legacy config keys are gone. composer update in CI without a lockfile bump will reveal this at runtime, not at install time — always commit composer.lock.
• Symfony 5.1+ is strict. If your composer.json pins symfony/http-foundation:^4.4, resolution fails. Align Symfony component constraints across the whole application (Laravel 8 is the tidy way to do this).
• PHP 7.2.5 is a floor, not a target. EOL for 7.2 is Nov 2020 and 7.3 is Dec 2021. Pin to 7.4/8.x in CI even though the package allows 7.2.5, so you catch deprecations from removed BC layers early.
• Silent service-not-found errors. Laravel resolves lazily, so a bundle service that is misconfigured may only fail at the first request that uses it. Add a smoke test ($this->app->make(YourService::class)) in your test suite.
• Do not reuse Symfony autoloading metadata. Resources/config/services.yaml and Symfony Flex recipes are not executed by Laravel. Everything must be registered through the bridge provider — treat the bundle's YAML as documentation of intent, not executable config.
• Debugging upgrade failures. When something breaks after the bump:

  composer why-not <vendor>/<package> 2.0
  

  is the fastest way to expose phantom pins against symfony/* or PHP. Then check the package's UPGRADE-2.0.md (or CHANGELOG) for renamed classes and removed methods — the BC removal means IDE "go to definition" often lands on the 2.x shape, which differs from any blog posts or tutorials you'll find.
• Extension point. If you previously subclassed or decorated a 1.x class, verify the class is still extensible in 2.x. Removed BC layers sometimes seal classes by making them final; in that case, decorate via the interface instead of inheritance.