Prismic Bundle Laravel Package

Getting Started

• Install: composer require <vendor>/<package> and let Laravel's package auto-discovery register the service provider. If the package predates 5.5, add the provider to config/app.php manually.
• Check constraints first. The entire signal in v3.1.0 is "add symfony4 support" — that is a composer constraint change, not a runtime feature. Before anything else, inspect composer.json in the package to see whether the new constraint is ^3.4|^4.0 (widened, safe) or ^4.0 only (dropped Symfony 3). Run composer why symfony/console symfony/http-foundation in your app to see which Symfony line you actually resolve to.
• Know which Laravel you're on. Laravel 5.6/5.7 ship Symfony 4 components; Laravel 5.4/5.5 pin Symfony 3.4. If you're on 5.5 or below, this release does nothing for you and may actively conflict.
• Look here first: src/*ServiceProvider.php (register() for container bindings, boot() for publishes/routes/migrations), config/<package>.php for the default surface area, and the README's upgrade notes for anything the changelog line omits.
• First use case: publish config (php artisan vendor:publish --provider="Vendor\Package\ServiceProvider"), set credentials in .env, then resolve the package's entry class from the container — app(SomeManager::class) or a facade — rather than new.

Implementation Patterns

• Inject, don't instantiate. Bind the package's manager behind its interface in a small app-level service provider so tests can swap it; facades are fine inside Blade and quick scripts but hide the dependency graph in larger services.
• Wrap third-party calls. Put the package behind a thin app-owned service (e.g. App\Services\FooClient) so a future Symfony/Laravel bump only touches one file.
• Config over code. Drive behaviour from config/<package>.php values sourced from .env; never edit the published config inline in a shared repo without also documenting the env keys.
• Queue and event integration. If the package dispatches jobs/events, register listeners in EventServiceProvider rather than patching the package's boot method; keep your hooks upgrade-safe.
• Testing. In feature tests, $this->app->instance(Contract::class, $fake) (or Http::fake() / Queue::fake() if the package talks over HTTP or dispatch) so the suite doesn't hit the real dependency. Add one smoke test asserting the container resolves the package's main class — it catches most constraint/upgrade breakage cheaply.
• Version pinning. Pin the package to ^3.1 in your app's composer.json; if you're staying on Symfony 3 / Laravel 5.5, pin ^3.0 explicitly so a later composer update doesn't silently cross the Symfony major.
• CI matrix. If you publish a package that consumes this one, test against both Symfony 3.4 and 4.x lines (Laravel 5.5 and 5.6/5.7) — that's what "symfony4 support" implies it should now tolerate.

Gotchas and Tips

• Widened constraints are not backward-compatible guarantees. "Add Symfony 4 support" often means the maintainer ran the suite on Symfony 4.0 only; Symfony 4.1–4.4 deprecations and the 4.x→5.x removals (Symfony\Component\DependencyInjection\ContainerAware, Container::getParameter() on the service container, several FrameworkBundle\Controller\Controller helpers) are usually not covered. Verify your exact symfony/* patch versions.
• Transitive conflicts are the real failure mode. Direct support doesn't help if an unrelated dependency still caps symfony/console at ^3.4. Diagnose with composer why-not symfony/console 4.0 before blaming the package.
• Constraint changes can be a silent breaking change for downstream packages. If you wrap this package, your own composer.json must widen the same constraints, or your consumers get an unresolvable graph.
• Cache artefacts after upgrading. Run php artisan config:clear / cache:clear — stale cached config or compiled container state after a provider change is the most common "it broke on upgrade" report. php artisan about confirms the framework/component versions you're really running.
• Debugging resolution: app()->bound(Foo::class) and app()->make(Foo::class) in php artisan tinker quickly separates "package not registered" from "package bug". php artisan package:discover re-runs auto-discovery if the provider isn't listed.
• Extension points to prefer: container bindings, config keys, published views/translations, and macros on the package's classes. Avoid subclassing deep internal classes — those are exactly what Symfony major versions move around.
• No new APIs shipped here. Nothing in this release adds features you should adopt; there is no migration work beyond the constraint itself. Treat it as a compatibility bump and validate with your existing test suite rather than planning new usage patterns around it.