Proxy Symfony Laravel Package

Getting Started

The v0.3.0 release is a compatibility and configuration release rather than a rewrite, so onboarding is unchanged from earlier versions:

1. Install with composer require <vendor>/<package>, then run php artisan vendor:publish --tag=<package>-config (or --provider="...") to pull the config file into config/.
2. Add the credentials/connection block to your .env and reference it through the published config. The relevant additions in this release are the connection options — specifically the persist flag now being user-controllable.
3. Bind or resolve the client through Laravel’s container rather than instantiating it directly. The package should expose a service provider that registers a singleton/factory; use app(Client::class) or dependency injection.

First use case: configure a single connection with persist => true in production and persist => false in local/testing, then open a connection and issue a simple command in a tinker session or health-check route. That validates both the install and the new toggle in one go.

Implementation Patterns

Config-driven connections. Keep the persist flag out of code and in config/<package>.php, keyed off env('..._PERSIST', false). This lets you flip behavior per environment without touching call sites. Production with long-running processes generally benefits from persist => true; local, CI, and tests almost never do.

Service provider / container binding. Register the client as a singleton and resolve it per-connection. If the package supports multiple named connections, prefer app(ClientManager::class)->connection('reporting') style access over static facades so you can swap implementations in tests.

Queue workers and Horizon. Persistent connections are the classic source of “stale connection after fork” bugs. With the new persist toggle, configure workers explicitly: either set persist => false in the worker’s config, or hook into Queue::looping/WorkerStarting to reconnect. Document this in your app’s README — it is now your responsibility, not the package’s.

Testing. Point the testing connection at persist => false and use an in-memory or fake client where the package offers one. Because persistence spans requests, using persistent connections inside RefreshDatabase-style tests can leak state between cases.

Symfony 4 deprecation fix. If you were previously pinning Symfony components below 4.x or suppressing deprecation notices, you can relax those constraints. Check your composer.json for symfony/* version pins after upgrading and run composer update --with-dependencies to make sure the transitive versions line up.

Gotchas and Tips

• Persist is per-process, not per-request. Under PHP-FPM each worker keeps a live connection; under Octane or queue workers it survives for the whole process lifetime. Test the off path (persist => false) before rolling it into workers.
• Silent connection reuse across tenants. If your app switches database/namespace per request on a shared persistent connection, always reset context (e.g. select()/flush/clear) at the start of a job. The toggle does not fix this for you.
• Deprecation noise ≠ breakage. The Symfony 4 fixes remove E_USER_DEPRECATED emissions from the package itself. Remaining deprecations in your logs are likely from your own dependencies — don’t chase them into this package.
• Debugging connection state: log the resolved config (minus secrets) once at boot in a booted() callback so you can see which persist value is actually in effect for a given worker.
• Extension point: if the package exposes a connection factory or event (e.g. ConnectionCreated, ConnectionClosed), use it to centralize reconnect/cleanup logic rather than wrapping every call site.
• Version pinning: this is a 0.x release, so pin with "^0.3" and review the changelog on each minor — the persist default may shift in a future version.