Webloader Bundle Laravel Package

Getting Started

• Install with composer require vendor/package. For Symfony 5 projects, require v1.1.2 or later — earlier 1.1.x releases contained a BC break against Symfony 5. Symfony 4.* remains supported on the same 1.1.x line.
• Confirm the resolved dependency graph before writing code: composer show vendor/package and composer why symfony/*. The package intentionally spans symfony/* ^4.4|^5.0, so your lockfile decides which code path you get.
• Publish the config file if the package exposes one: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Read the published file top-to-bottom — defaults usually encode the intended integration.
• First use case: resolve the package's main service from the container (app(Manager::class) or the facade) inside a controller or a queued job, and exercise one read-only operation before wiring it into write paths.
• Where to look first: README.md (install + version matrix), CHANGELOG.md (the 1.1.2 entry is your signal for Symfony 5 readiness), the service provider (what is bound and how), and the config file (what is tunable).

Implementation Patterns

• Constructor injection over facades for anything testable. Register the package's manager as a singleton (it almost certainly already is via its service provider) and inject interfaces where the package offers them.
• Config-driven setup. Prefer publishing and editing config over instantiating classes directly; this keeps upgrades from v1.1.x to later 1.x releases cheap and avoids pinning internal class names that may shift with the Symfony 5 compatibility work.
• Environment-scoped overrides. Set package options in config/ with env() fallbacks, then override per-environment in .env. Cache with php artisan config:cache in deploy pipelines.
• Version pinning as a pattern. Pin the package to ^1.1.2 and pin Symfony components consistently across the app. Avoid mixing a Symfony 4 constraint on one package with Symfony 5 on another; let Composer resolve the whole set together.
• Testing. Use orchestra/testbench for package-level integration tests and plain phpunit for units. Bind fakes or mocks of the Symfony collaborators the package consumes so tests behave the same on Symfony 4 and 5 CI legs.
• Queue/console integration. Resolve the service inside handle() rather than storing it on a serialized job property; Symfony-backed services often hold non-serializable state.
• Extension points. If the package exposes a manager, use its extend()/driver registration hooks rather than subclassing internals — internals are exactly what changed between Symfony 4 and 5.

Gotchas and Tips

• Upgrade to 1.1.2 before adopting on Symfony 5. The published 1.1.0/1.1.1 line carried a BC break; if you see Class not found, signature mismatch, or Declaration must be compatible errors from a Symfony namespace, check the package version first.
• Dual Symfony 4/5 support means conditional internals. Do not rely on instanceof checks or type hints against Symfony classes that moved between 4 and 5; go through the package's public API instead.
• Composer conflict debugging. When you get "could not be resolved", run composer why-not symfony/console 5.x and composer update --with-dependencies on a scratch branch. Conflicting transitive Symfony constraints are the usual culprit.
• Clear caches after upgrades. php artisan config:clear && php artisan cache:clear — stale cached config referencing old class names produces confusing errors after a version bump.
• Debug bindings with Tinker. php artisan tinker then app()->bound(...) / get_class(app(SomeContract::class)) to confirm which implementation is live.
• Check the CI matrix. If you support both Laravel and Symfony ranges, run tests against Symfony 4.4 and 5.x explicitly; the 1.1.2 fix exists precisely because one leg was untested upstream.
• Read the changelog on every 1.x bump. The project has shipped BC-affecting changes inside a patch/minor line; treat 1.1.x upgrades as reviewable, not automatic.