Laravel Common Laravel Package

Getting Started

pijler/laravel-common is a shared-utilities package intended to be pulled into multiple Laravel applications, so the first thing to do is confirm you actually need it: it exists to centralise cross-project concerns (queue/Horizon helpers in this release) rather than to be a general-purpose framework.

Minimal steps:

1. Install: composer require pijler/laravel-common.
2. Laravel auto-discovers the service provider in most setups; verify with php artisan about or php artisan package:discover that CommonServiceProvider is registered.
3. Publish config if the package exposes it: php artisan vendor:publish --tag=common-config. Check the resulting config/common.php (or equivalent) before changing anything — defaults are usually sane.
4. First use case for this release: wire up Horizon queue handling. If you use Horizon, inspect the HorizonQueue class and confirm which connection it resolves — as of v0.11.0 it uses your application's default queue connection unless you explicitly override it.

Where to look first: the package's src/ directory (particularly anything queue- or Horizon-related), the published config, and the README's queue section. If you're on v0.10.x and your app relied on a non-default queue connection being hardcoded, read the Gotchas section before upgrading.

Implementation Patterns

• Treat the package as infrastructure, not application logic. Bind it once and let your app code stay unaware of it; don't sprinkle HorizonQueue references through controllers.
• Prefer config over code. The v0.11.0 change is a clear signal: set queue.default (and horizon.defaults) in your .env/config/queue.php rather than trying to hardcode a connection at the call site.
• Queue routing pattern: if you run multiple connections (e.g. redis for Horizon, sqs for long-running jobs), explicitly set the connection on the job or queue config rather than assuming the package picks it up. The "default connection" behaviour means your QUEUE_CONNECTION env value is now authoritative.
• Multi-app consistency: since this is a "common" package, pin the same version across all your applications and roll upgrades out together. Divergent versions across apps that share queue infrastructure is where subtle bugs appear.
• Testing: in phpunit.xml set QUEUE_CONNECTION=sync (or null with Queue::fake()). Because the package now defers to the default connection, your test environment no longer needs to override anything package-specific.
• Local development: run php artisan horizon as usual; if jobs vanish, check QUEUE_CONNECTION first — that's now the single source of truth for where HorizonQueue sends work.

Gotchas and Tips

• v0.11.0 is a behavioural change, not a pure refactor. Switching to the default queue connection means apps that were implicitly relying on a previously hardcoded connection may suddenly route jobs to a different queue. Audit config/queue.php and your .env before upgrading.
• Clear config caches after upgrading: php artisan config:clear and, in production, php artisan config:cache again. Stale cached config is the most common cause of "the upgrade did nothing / broke everything" with queue-connection changes.
• Env var precedence: if QUEUE_CONNECTION is unset in a given environment, you fall back to config/queue.php's default (sync in fresh Laravel apps). That will silently run jobs inline in production if you forget to set it — verify in every environment.
• Horizon-specific config lives in config/horizon.php. The package resolves the connection from Laravel's queue config, but Horizon's supervisors still need matching connection definitions; a mismatch surfaces as jobs being enqueued but never processed.
• Debugging tip: php artisan queue:monitor and php artisan horizon:status will show which connection is actually in use. Pair this with a quick dd(config('queue.default')) in a tinker session when in doubt.
• Extension points: if you need a custom connection, don't fork the package — register your own queue resolver or override the binding in a service provider. Keep the package upgradable.
• Thin release notes are a risk signal. This release documents only one PR with no migration guidance; if you're production-critical on queue behaviour, read the diff for PR #14 (v0.10.0...v0.11.0) yourself rather than trusting the changelog.
• Pin your version in composer.json with a conservative constraint until the connection-selection behaviour has been stable for a release or two, since it directly affects job durability.