Laravel Mention Me Laravel Package

Getting Started

This is the initial 1.0.0 release, so there's no migration or upgrade path to worry about — you're greenfield. Budget time for reading the package source rather than assuming a mature SDK, since 1.0.0 ships with no accumulated docs or deprecation history.

Minimal path:

1. composer require the package (pin it exactly — see Gotchas), then php artisan vendor:publish --tag=mention-me-config (confirm the tag in the README; if no tag is documented, check the service provider's publishes() call in src/).
2. Set credentials in .env: you'll need at minimum a partner code / API key and a base URL. Mention Me runs separate sandbox and production environments — start pointed at sandbox and never share keys between them.
3. Run php artisan config:cache (or config:clear in local) after editing .env. A stale config cache with the wrong base URL is the single most common "why is it hitting live?" bug.
4. Look first at: the published config file (that's the real API surface — base URL, timeout, retry, credentials), the root client/service class, and the facade accessor if one is registered. Those three tell you 90% of the shape.

First use case to wire up: render a referrer's share link. On a customer's account or post-purchase thank-you page, fetch their referral offer and share link, then display it. That's a single outward call, needs no webhook, no attribution, and proves credentials + config + HTTP layer end-to-end before you touch money-adjacent reward flows.

Implementation Patterns

Persist the third-party identity locally. Add a nullable, indexed mention_me_customer_id to users (or your customer model) via migration. Every subsequent call — offers, share links, referrals, rewards — keys off it. Re-deriving it by email each time is slow and brittle when emails change.

Resolve the client from the container, don't new it. Inject it into a small domain service (ReferralService, MentionMeAccount) rather than calling the facade from controllers. This gives you one seam to fake in tests and one place to add logging later.

Wrap outbound calls in queued jobs. Referral and reward calls are third-party-bound and will occasionally be slow. Use a job with $tries, $backoff, and — critically — an idempotency key derived from your own domain event (order ID, user ID + event type) so a retry after a timeout doesn't double-count a referral or re-issue a reward.

Model the flows as your own events. Emit ReferralAttributed, RewardIssued, etc. from your service layer, mapping the API response into your vocabulary. The package's response objects are an integration detail; your app shouldn't reference them from a listener three layers deep. This also makes a future package swap a single-class change.

Use the standard lifecycle hooks:

• On registration / first order — create or upsert the customer record, store the returned ID.
• On referee signup or order — submit the referral/attribution event with the referee's details.
• On display pages — fetch referrer offer + share link. Cache this briefly (5–15 min) keyed by customer ID; it's marketing copy that changes rarely and it's on a hot page.
• On reward webhooks (if the package ships a handler) — register the route, verify the signature, return 200 immediately, and dispatch a job to do the work.

Integration tips:

• Most Laravel SDKs sit on Illuminate\Support\Http; verify by checking the source, because if so you get Http::fake(), Http::preventStrayRequests(), and middleware for free. Record real sandbox responses once into tests/Fixtures/ and replay them.
• Bind an interface (or the concrete client) to a fake in TestCase::setUp so your feature tests never touch the network.
• Add a custom HTTP middleware for request/response logging with PII redaction — invaluable during the first integration and safe to leave on in staging.
• Set explicit timeout and connect_timeout in config. The defaults (often none) will let a slow third party hold your PHP workers.

Gotchas and Tips

Sandbox vs production is a config trap. Separate keys and separate base URLs. Guard against a staging box pointing at live by asserting on the base URL in a boot-time check or a test, not by hoping.

Idempotency is on you. Nothing in an initial 1.0.0 release guarantees the API call is safe to retry. A network timeout after the server processed a referral is the classic double-reward bug. Send your own idempotency key if the API supports one; if not, check-then-write and accept a small race, or make the reward grant idempotent on your side with a unique constraint.

Errors may not throw. Check whether the package throws on 4xx/5xx or returns a result object with an error state. Handle connection exceptions separately from API errors — one is retryable, the other usually isn't. A 422 from a malformed referee payload will never succeed on retry; don't burn your queue on it.

Locale and currency are explicit parameters, not server defaults. Mention Me offers differ by market (UK/EU/US). Pass the customer's locale and currency rather than letting the server's APP_LOCALE decide, or you'll quote a UK offer to a US customer.

PII and consent. Names, emails, and order values are going to a third party. Confirm you have consent for referral marketing, keep it out of logs, and know your deletion path — a GDPR erasure request has to reach Mention Me too, not just your DB.

Webhook routes need exempting. If the package registers a route, it must bypass CSRF (validateCsrfTokens(except: [...]) in bootstrap/app.php on Laravel 11+). Verify the signature before parsing the body semantically, and make the handler idempotent — you will receive duplicates.

Config cache after every env change, and remember env() calls inside package config only resolve when un-cached. If a package config file reads env('MENTION_ME_KEY') directly and you're cached, that's fine, but a config() read of a non-published key silently returns null rather than erroring — add a boot-time guard that fails loudly on missing credentials.

Extension points to look for: publishable config, a bindable client interface (swap for a fake or a local mock server), HTTP middleware for logging, and a configurable base URL. If the base URL isn't configurable, you cannot point tests at a stub server — that's a hard blocker worth opening an issue for.

On versioning: 1.0.0 is the first cut. Pin ~1.0.0 or an exact version in composer.json and read the CHANGELOG before every bump until the maintainers establish a stability track record. Pre-2.0 minor releases in young packages frequently carry breaking changes despite semver.