Env Bundle Laravel Package

Getting Started

v3.0.0 is a platform/compatibility release rather than a feature release: the only substantive change is Symfony 7 support, alongside CI/linter/Psalm housekeeping and a README improvement. There are no new APIs, deprecations, or breaking changes called out in the release notes, so treat the major bump as an ecosystem-alignment release (Symfony 7 implies PHP 8.2+ and pairs naturally with Laravel 11) rather than a rewrite.

Start with:

composer require <vendor>/<package>:^3.0
php artisan about
php artisan vendor:publish --provider="<Vendor>\\<Package>\\<Package>ServiceProvider"

Look first at:

1. The README's Laravel section (the one thing explicitly improved in this release).
2. The package's service provider and any config/<package>.php file that gets published.
3. composer.json constraints for symfony/*, illuminate/*, and php — this tells you whether the bump is really about Symfony 7 or also about dropping older Laravel/PHP support.
4. The changelog/UPGRADE file, since a 3.0.0 tag with only maintenance commits usually means the major bump was forced by dependency constraints.

A good first use case is the simplest integration the package offers: resolve its client/manager from the container, inject it into a controller or queued job, configure credentials through .env, and make one call end-to-end before wiring it into anything else. If the package auto-discovers its provider, confirm it appears in bootstrap/cache/packages.php after composer dump-autoload.

Implementation Patterns

Constructor injection over facades. Bind the package's client/manager in a service provider (or rely on its own binding) and inject it into controllers, jobs, and actions. Use the facade only for terse, one-off calls in controllers or Blade; keep domain/services code dependent on the injectable type so tests can swap it.

Config-first setup. Publish the config file, put environment-specific values in .env, and keep the committed config file as the source of truth for non-secret defaults. Since Laravel caches config, never call env() outside config files — read everything through config('<package>.*').

Push slow work to the queue. Anything that talks to an external service should run inside a job with sensible $tries, backoff(), and retryUntil(). If the package emits events or supports hooks, listen for them rather than polling.

Testing pattern. In TestCase::setUp(), bind a fake/stub implementation of the package's contract ($this->app->instance(...) or $this->swap(...)). If the package uses Laravel's HTTP client underneath, Http::fake() is usually enough. Use Event::fake() when asserting that package events fire.

Scheduled/batch usage. For bulk operations, wrap calls in an Artisan command and schedule it; use $this->components->info() for output so it plays nicely with Laravel's console UI.

Scoped bindings for multi-tenant apps. If the package holds per-tenant or per-connection state, register it with $this->app->scoped(...) (or bind + explicit reset) so long-running Octane/queue workers do not leak state between requests.

Extension points. Most packages of this shape expose one of: a manager with extend(), a contract you can rebind, or a config-driven driver list. Prefer rebinding the contract in a service provider over subclassing internals — that survives minor upgrades.

Gotchas and Tips

• Symfony 7 means PHP 8.2+. If the app is on Laravel 10 / PHP 8.1, stay on the 2.x line. Verify with composer why-not <vendor>/<package> 3.0 before upgrading; transitive packages that pin symfony/* to 6.x are the usual blocker.
• The major bump may drop old platform support even though the notes look minor. Read composer.json for php, illuminate/support, and symfony/* ranges rather than trusting the commit list.
• The CI/linter/Psalm commits are maintenance noise. “Fix Audit workflow”, “Tune Audit workflow”, “Remove explicit php version for psalm”, and linter rule updates affect the package's own pipeline, not your runtime. Don't go looking for behaviour changes there.
• Clear caches after upgrading. php artisan config:clear, php artisan cache:clear, and composer dump-autoload. If the provider still isn't registered, delete bootstrap/cache/packages.php and bootstrap/cache/services.php.
• Published config drift. After a major upgrade, diff your published config against the package's new stub; new keys with defaults are common, and missing keys can silently fall back to null.
• Debugging bindings. Use php artisan tinker and check app()->bound(<Contract>::class) and get_class(app(<Contract>::class)) to confirm which implementation is actually resolved.
• Don't test the package's internals. Assert on your integration boundary (job dispatched, event fired, HTTP call made). That keeps your suite stable across 3.x patch releases.
• Pin the major version. Use ^3.0 rather than *, and let Renovate/Dependabot surface patch releases; the 3.x line should be low-churn given how 3.0.0 was assembled.