Resonate Users Laravel Package

Getting Started

This is a thin wrapper package: its own surface area is small, and most of what you actually call comes from webpatser/resonate. Treat the wrapper as the integration layer and read the upstream docs first.

Minimal path:

1. composer require <vendor>/<package>:^1.0 — the 1.0.0 tag is the first stable release, so this is the first version where a caret constraint is a safe bet.
2. Read UPGRADE.md in the package root. The release notes explicitly point there, which means the upgrade path is documented outside the changelog. Do not skip it just because "No API changes" is stated — that phrase describes this package's public API, not the dependency's.
3. Confirm the service provider is auto-discovered (composer dump-autoload after install, then check php artisan about or php artisan package:discover output).
4. Publish any shipped config/asset files with php artisan vendor:publish --provider="..." and commit the result so config drift is visible in review.
5. First use case: wire it into an existing event or notification flow in a single place — one listener, one job, one controller — and verify end-to-end before spreading it across the codebase.

If you are on Laravel 10/11 with package discovery enabled, steps 3–4 are usually the only setup you need. If the package ships a facade, prefer resolving it through the container in application code so tests can swap it.

Implementation Patterns

Isolate the dependency behind your own seam. Even at 1.0, a package whose core lives in a separate library can shift under you. Wrap calls in a small application-level service (e.g. App\Support\Resonator) and inject that. When the upstream contract moves, you edit one class instead of grepping the codebase.

Config over code. Anything the package reads from config should be set via config/*.php and environment variables, not hardcoded at call sites. Keep the published config file in version control and diff it on every upgrade — this is where breaking changes usually show up silently.

Queue and event integration. If the package participates in dispatching or handling events, decide early whether it runs inline or on a queue. Register it as a listener in EventServiceProvider (or via Event::listen) rather than calling it from controllers, so retries and failure handling come for free.

Test doubles. Bind a fake or stub implementation of the package's contract in your TestCase::setUp() so feature tests don't hit real transports. If the package ships a fake()-style helper, use it; otherwise a Mockery binding on the container is sufficient.

Version pinning discipline. For the first few weeks on 1.0.x, consider pinning to an exact minor (1.0.*) in composer.json while you build confidence, then widen to ^1.0 once your test suite covers the integration paths.

Gotchas and Tips

The headline risk is the transitive bump, not this package. webpatser/resonate moved from ^0.7 to ^1.0. Pre-1.0 to 1.0 in a dependency is exactly where breaking changes live, and "No API changes" here refers to the wrapper's own API. Run composer why webpatser/resonate and composer update --dry-run before committing to the upgrade to see what else in your lock file is affected.

Lock file conflicts are likely. Any other package still requiring webpatser/resonate:^0.7 will hard-block the install. You will see a solver error naming both constraints — that is the dependency, not a bug in this package. Resolve by upgrading the sibling package or dropping it.

Read UPGRADE.md before CHANGELOG.md. The changelog entry is two lines and tells you almost nothing; the upgrade doc is where any behavioural differences in the upstream library will be spelled out. If UPGRADE.md is thin, check the resonate 1.0 release notes directly on its repository.

Config caching bites on deploy. After changing the published config, run php artisan config:clear locally and ensure your deploy pipeline runs config:cache. Stale cached config is the most common cause of "it works locally but not in staging" with wrapper packages.

Debugging. Start with php artisan package:discover -v to confirm registration, then a dd(app()->bound(SomeContract::class)) check on the container. If behaviour diverges from the upstream docs, the wrapper is probably applying defaults from its config file — inspect the published config before assuming the library is at fault.

Extension points. The container binding is the primary seam: overriding the implementation in a service provider gives you logging, metrics, or a no-op for local development without forking. Do that rather than subclassing, which couples you to internals that the 1.0 stability guarantee does not cover.

Watch the next release closely. A 1.0.0 that only bumps a dependency often precedes a 1.0.1/1.1.0 that cleans up assumptions made during the 0.x era. Subscribe to releases and re-check this assessment after the next couple of tags.