My Poseo Bundle Laravel Package

Getting Started

• Require the package with Composer and confirm your runtime meets the new floor: PHP 8.0+. If you are still on PHP 7.4, stay on the previous major/minor line until you can upgrade.
• Check your composer.json before upgrading. v6.1.0 drops support for non-maintained Symfony versions and adds newer php-http/* constraints for PHP 8. In practice this means your symfony/* packages and PSR-18/HTTPlug implementations need to be on supported releases.
• Publish any package config (php artisan vendor:publish --tag=...) and review the default driver/client settings. The package is configured through Laravel's config repository, so the config file is the first place to look when behaviour differs between environments.
• First use case: resolve the package's client/manager from the container and perform a single outbound operation using the default driver. Do this in php artisan tinker before wiring it into application code; it validates your PHP version, Symfony constraints, and HTTP client discovery in one step.
• Where to look first: the package README, the CHANGELOG/upgrade notes for v6.1.0, the service provider bindings, and the config file. The service provider tells you which interfaces are bound and where custom implementations can be injected.

Implementation Patterns

• Inject the contract, not the concrete client. Type-hint the package's client/manager interface in constructors and let Laravel resolve it. This keeps your code stable when the underlying php-http/* implementation changes between releases.
• Explicitly bind a PSR-18/PSR-17 implementation. Rather than relying on php-http/discovery to pick a client at runtime, bind your chosen implementation (for example a Guzzle-backed PSR-18 client) in a service provider. This makes behaviour deterministic across local, CI, and production.
• Drive behaviour through config, not code. Use per-environment config for drivers, timeouts, base URLs, and credentials; keep secrets in .env and reference them from config. Cache config in production (php artisan config:cache) and clear it after upgrades.
• Wrap outbound calls in queued jobs for anything that is not user-blocking. Pair this with the package's retry/backoff options or Laravel's job-level retries/backoff, and emit domain events on success/failure so the rest of the app can react without coupling to the HTTP layer.
• Test with fakes at the boundary. If the package exposes a Laravel HTTP client integration, use Http::fake(). Otherwise bind a mock PSR-18 client in the container during tests so no real network calls are made.
• Use the container as the extension point. Custom clients, middleware/plugins, and loggers should be registered via bindings or config, not by subclassing package internals. This is the cleanest way to add tracing, correlation IDs, or custom auth headers.

Gotchas and Tips

• v6.1.0 is a minor release, but dependency-floor changes can break installs. Dropping unsupported Symfony versions and moving php-http/* constraints can surface as Composer conflicts rather than runtime errors. Run composer why-not on conflicting packages and align your symfony/* versions before upgrading.
• Watch transitive Symfony constraints. Other Laravel packages may pin older Symfony components. If Composer refuses the upgrade, the fix is usually to update the wider dependency set, not to force the package version.
• php-http/discovery can select different implementations in different environments. If behaviour differs between local and production, check which PSR-18 client was discovered. Pin it explicitly.
• Clear caches after upgrading. Run php artisan config:clear, php artisan cache:clear, and re-run config:cache in production. Stale config is a common cause of "the upgrade didn't take effect".
• Debugging outbound traffic: enable the package's logging options or attach a PSR-3 logger plugin to the HTTP client, and use Laravel Telescope/Log for request/response visibility. Avoid logging credentials.
• CI matrix: test on PHP 8.0/8.1+ and against the minimum and latest supported Symfony versions. The release explicitly narrows the supported matrix; your CI should reflect that.
• Extension points to prefer: container bindings for the client interface, config-driven driver selection, and events/listeners around operations. Avoid relying on internal classes, which are the most likely to shift as php-http and Symfony dependencies move.