Laravel Mention Me Laravel Package

Product Decisions This Supports

• Referral/growth-loop feature scoping: Whether to build an owned "refer a friend" program versus integrating a specialist referral marketing platform. This package is the concrete integration path for the latter — it makes the build-vs-buy comparison real (two-way door: an API wrapper is cheap to remove, the SaaS contract is not).
• Roadmap sequencing for acquisition/growth work: Enables a referral program to land in a single sprint rather than a multi-quarter build, which changes whether referral is a Q-next item or a Q+2 item. It supports shipping a thin v1 (referrer offer → share link → referee attribution → reward) and learning from conversion data before investing in custom logic.
• Feature surface to expose to users: The package's domains map directly to product surfaces — referrer offers (incentive messaging on the account page), share links (invite flows, email/social copy, deep links), referrals (attribution status, "friend joined" states), rewards (reward issuance, redemption visibility), referee (the invited-side experience and their offer). Useful as a checklist when writing stories; anything not covered is a gap to negotiate or build around.
• Where reward truth lives: Reinforces the decision that the referral platform is the system of record for referral state and rewards, and our product reads/mirrors it — a decision that shapes data model, reconciliation jobs, and support tooling before code is written.
• Scope boundary for "growth" experiments: Referral is one loop among several (activation, lifecycle, pricing). This package lets us test the referral loop without committing engineering to fraud detection, attribution windows, or reward accounting — those stay vendor-side, which is the correct buy decision for a non-differentiating capability.
• Internationalisation and market expansion questions: Referee/referrer offer mechanics differ by market; the vendor's configurability (rather than our code) determines launch feasibility in a new region — a decision input for expansion sequencing.
• Support and finance readiness: Reward issuance means money-adjacent operations (liabilities, tax treatment of incentives, abuse). Choosing an integration forces these conversations early, which is a feature of the decision, not a side effect.

When to Consider This Package

Consider it when:

• Referral is a real acquisition channel with a named owner and a target metric. If nobody owns referral conversion, integration work will ship and rot.
• You have (or are willing to buy) a Mention Me account. The package is a client, not a platform; value is entirely contingent on the commercial relationship, contract terms, and the vendor's dashboard configuration.
• You are on a supported Laravel/PHP version and can accept the package's API coverage as-is. At 1.0.0 the surface is a first cut — expect to inspect the source to confirm every endpoint you need (attribution lookup, reward status, webhooks) is actually wrapped.
• Time-to-market beats differentiation. Referral mechanics are well-trodden; a specialist vendor's fraud handling and attribution logic are usually stronger than a homegrown v1.
• You can afford a thin abstraction. Wrap the package behind your own interface so the vendor is swappable and referral state can be mirrored locally for reporting and support.

Look elsewhere or build in-house when:

• You need capabilities the wrapper does not expose — webhook/event ingestion, batch reconciliation, custom attribution rules, or non-standard reward types. A thin client is a starting point, not an SDK guarantee; verify before committing.
• Referral is core to your product's differentiation (e.g., a network-effect or marketplace product where the invite graph is the product). Then vendor lock-in on the graph is a strategic cost you should not pay.
• You are pre-product-market-fit. Instrumenting organic sharing and measuring it is cheaper than a contract plus an integration you will rip out after a pivot.
• Compliance or data-residency constraints prevent sending customer and referee PII to a third party, or require the referral ledger to live in your own systems.
• You are on an unsupported framework/PHP version, or the package has no release cadence, tests, or issue responsiveness. With a 1.0.0 as the only release, treat maintainer velocity and issue history as unknown; a single-maintainer wrapper around a paid API is a real bus-factor risk.
• Alternatively, an official SDK or plain HTTP client is sufficient. If you only need two endpoints, a dependency is overhead — a small service class with Laravel's Http client may be the better call.

Adoption criteria to satisfy before commitment: pinned version in composer.json, credentials via config/env not code, queue-based retries for outbound calls, mirrored referral/reward state in your own DB for reporting and idempotency, feature flag for kill-switch, and a documented fallback if the vendor API is unavailable during checkout or signup.

How to Pitch It (Stakeholders)

To executives: This is a small, well-bounded integration with Mention Me, a specialist referral marketing platform, that lets us launch a refer-a-friend program in weeks rather than quarters. It buys proven attribution and reward mechanics instead of funding a bespoke build, keeps the capability out of our critical path, and — because it is an API client behind our own interface — it is reversible if the channel underperforms. The commercial commitment is the vendor contract, not the code; that is the decision that needs sign-off, and it should be gated on a measured referral-conversion target at the first review.

To engineering: Treat this as a thin HTTP client, not a platform. Do not call it directly from controllers or Blade — put it behind a ReferralService interface so we can swap vendors and so tests do not hit the network. Pin the version, keep credentials in config, wrap outbound calls in queued jobs with retries and a timeout budget, and mirror referral and reward state locally so reporting, support, and idempotency do not depend on live API reads. Assume the 1.0.0 surface is incomplete: audit which endpoints are wrapped against the vendor's API docs before estimating, and own any missing ones ourselves. Keep the whole thing behind a feature flag, and log request/response pairs (redacting PII) so we can debug attribution disputes without a vendor ticket. Before we build: confirm the vendor's webhook/event story and how we reconcile rewards, because that — not the client code — is the actual integration risk.