Laravel Metronome Laravel Package

Getting Started

• Install: composer require rvxlab/laravel-metronome. Laravel's package auto-discovery registers the service provider — there is nothing to add to config/app.php.
• Publish config: php artisan vendor:publish --tag="metronome-config" (confirm the exact tag in the README; the config file itself is the authoritative list of options). Add the credentials to .env and reference them only from config/metronome.php so config:cache works.
• Where to look first, in this order: README → the published config/metronome.php → the package's service provider (this shows you the container binding and any singleton/lifecycle decisions) → the facade/class docblocks, which at v1.0.0 are the stable public API surface.
• First use case: prove connectivity with a single call from php artisan tinker — resolve the client out of the container (app(...) or the facade) and make the smallest possible request. Do this before wiring anything into a controller; it separates credential/config problems from application problems.
• Then: put that same call behind a queued job and trigger it from a test route or command. Because v1.0.0 is the first stable release (up from 0.1.1), the API you learn here is the one you can reasonably pin with ^1.0 — treat this as the version to build against rather than an interim 0.x.

Implementation Patterns

• Resolve, don't construct. Always pull the client from the container or the facade rather than instantiating it. That keeps config, HTTP client options, and any package-level middleware (auth headers, retries) applied consistently, and makes fakes possible in tests.
• Wrap it in one application-owned class. Create something like App\Services\Metronome\Client (or an action per operation) that depends on the package client. Every call site depends on your class, not the package's. When the package changes — or when you need to record what you sent — you change one file.
• Push outbound calls onto the queue. The integration is inherently an external HTTP boundary; keep it off the request path. Use a dedicated queue with tries, backoff, and timeout set explicitly, and ShouldBeUnique or a uniqueness key so the same domain event isn't dispatched twice.
• Idempotency by construction. Derive an idempotency key from your own domain identifier (order ID, event UUID), not from a random value generated at send time. Retries are expected; duplicate side effects are not.
• Model the outbound payload as a DTO. Build the array/object in a small class with a toArray()/toPayload() method and unit-test it. Asserting on a DTO is far cheaper than asserting on an HTTP interaction, and it documents the contract you rely on.
• Test at the boundary. In feature tests, use Laravel's Http::fake() (or the package's own fake, if it ships one) and assert the request was sent with the expected payload and headers. In unit tests, bind a fake implementation of your wrapper class into the container.
• Multi-tenant / multi-account: if credentials vary per tenant, don't rely on a globally configured singleton for the whole request. Resolve or configure the client per tenant explicitly, and make that resolution go through one factory method so it's auditable.
• Observe it like any other dependency. Emit a log line (event name, key, latency, outcome — no secrets) on every outbound call. When something breaks in production, that log is the difference between a five-minute fix and an afternoon of guessing.

Gotchas and Tips

• Upgrading from 0.1.1: v1.0.0 is a stability milestone, not necessarily a no-op — the release notes link to a full compare diff. Before upgrading, read compare/v0.1.1...v1.0.0 and check specifically for renamed classes, renamed config keys, and changed default values. The 0.x → 1.0 boundary is exactly where a maintainer is most likely to have tidied names without calling it out in the summary.
• Pin ^1.0, but don't assume forever-stability. From here the package owes you semver, which is a real improvement over 0.x — but keep the diff check in your upgrade routine anyway.
• env() only inside config files. If you reference env('METRONOME_...') from a service class, it returns null the moment php artisan config:cache runs in deploy. This is the single most common "works locally, broken in staging" cause for wrapper packages.
• Set timeouts and retries yourself. Package defaults for HTTP timeouts are often generous or absent; a hung outbound call will hold a queue worker. Configure a connect/response timeout in the published config or in the underlying HTTP client.
• Mind rate limits. If the remote API throttles, use exponential backoff with jitter plus a rateLimited() handler on the job; otherwise a burst of queued work turns into a retry storm that makes the throttling worse.
• Timezones and units are silent bugs. Send UTC / ISO-8601 timestamps and be explicit about integer vs decimal quantities. A metric reported in the wrong unit or window rarely throws — it just produces wrong numbers downstream, which is much harder to notice.
• Don't log credentials or full signed payloads. Log identifiers and outcomes; redact headers when you dump requests. Laravel's Telescope and the HTTP client's event hooks are the fastest way to see what actually went over the wire — but they also store what you hand them.
• Extension points worth knowing: the container binding is the seam for testing (bind your own fake of the client contract) and for multi-tenant overrides. If the package dispatches events around requests, prefer those over subclassing — subclassing a package class is the least stable form of extension and is the first thing to break in a minor release.
• Debugging checklist when a call fails: (1) php artisan tinker resolve the client — does it construct? (2) dump config('metronome') — are the keys populated post-config:cache? (3) fire the same payload through Http::fake() in a test — is your payload valid? (4) only then look at the package internals. This order isolates config, payload, and transport before you start reading vendor code.