PHPackages padosoft/laravel-invitations - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. padosoft/laravel-invitations ActiveLibrary[Authentication & Authorization](/categories/authentication) padosoft/laravel-invitations ============================ Enterprise invite-by-code, referral, rewards, waitlist & anti-abuse system for Laravel — multi-tenant, concurrency-safe, idempotent, GDPR-ready. v1.0.1(1mo ago)1693↓50%1MITPHPPHP ^8.3CI failing Since Jun 23Pushed 1mo ago1 watchersCompare [ Source](https://github.com/padosoft/laravel-invitations)[ Packagist](https://packagist.org/packages/padosoft/laravel-invitations)[ Docs](https://github.com/padosoft/laravel-invitations)[ RSS](/packages/padosoft-laravel-invitations/feed)WikiDiscussions main Synced 2w ago READMEChangelog (3)Dependencies (20)Versions (4)Used By (1) [![Laravel Invitations](resources/banner.png)](resources/banner.png)Laravel Invitations =================== [](#laravel-invitations) **The enterprise invite‑by‑code, referral, rewards, waitlist & anti‑abuse suite for Laravel.** Multi‑tenant · concurrency‑safe · idempotent redemption · GDPR‑ready · tri‑surface (PHP + HTTP API + MCP) [![Latest Version on Packagist](https://camo.githubusercontent.com/25b13e817de91f96e0554d143d6ce3a3396bec64de18a84fe312c8e749dc4dd1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7061646f736f66742f6c61726176656c2d696e7669746174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/padosoft/laravel-invitations)[![Tests](https://camo.githubusercontent.com/0980dca078a74bd7efc0051481f153641cd62d9186022bfb8659051282928443/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7061646f736f66742f6c61726176656c2d696e7669746174696f6e732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/padosoft/laravel-invitations/actions)[![PHP](https://camo.githubusercontent.com/81088cc0e783512c3c17c6d72b8ee7299ac7be0ac9b68992d5557dc3c69cd9bb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e332d3737376262343f7374796c653d666c61742d737175617265)](https://www.php.net)[![Laravel](https://camo.githubusercontent.com/cbef5a2edd6eb43b4547ed337ee084403e443037560cbc25099582d9c7530263/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313225323025374325323031332d6666326432303f7374796c653d666c61742d737175617265)](https://laravel.com)[![License](https://camo.githubusercontent.com/04f66a710a3e37a79d806b18477bfc438df0737361f5bc30ac520cb6cfecf4c4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7061646f736f66742f6c61726176656c2d696e7669746174696f6e732e7376673f7374796c653d666c61742d737175617265)](LICENSE) > ⚠️ **Active development toward `v1.0.0`.** The engine is production‑proven (extracted from a shipping app) and fully tested; the public API may still shift before the `v1.0.0` tag. 📖 **Full documentation:** **[doc.laravel-invitations.padosoft.com](https://doc.laravel-invitations.padosoft.com)**— deep, academic guides on atomic redemption, multi‑tenancy, anti‑abuse, K‑factor analytics, the tri‑surface API, GDPR, and the architecture decision records. --- 🚀 AI vibe‑coding pack included ------------------------------ [](#-ai-vibecoding-pack-included) This repo ships a complete AI pair‑programming kit: [`CLAUDE.md`](CLAUDE.md) (engineering invariants - quality gates), [`AGENTS.md`](AGENTS.md), and the design/roadmap docs under [`docs/`](docs). Point Claude Code, Cursor, or Copilot at the repo and they inherit the package's rules (atomic redemption, tenant scoping, fail‑open fraud, GRANT‑never‑REVOKE) automatically. --- Why this package ---------------- [](#why-this-package) Every Laravel invite/referral package on the market stops at "generate a code, mark it used." None of them solve the problems that actually bite in production: - **They over‑redeem under load.** The popular packages increment a use‑counter with a check‑then‑write and *no lock* — two concurrent redemptions both pass the "1 seat left" check. That's a free‑code / over‑capacity bug at best. - **They're single‑tenant.** Codes are globally unique, so two customers can never share an intuitive code, and rows leak across tenant boundaries. - **They store invitee emails forever** with no erasure path — a GDPR liability. - **They have no events, no fraud controls, no analytics, and no API/MCP surface.** `padosoft/laravel-invitations` is built the other way around: correctness, multi‑tenancy, privacy and observability first. ✨ Highlights ------------ [](#-highlights) - 🎟️ **Invite codes** — random, vanity, and **cryptographically signed** (Crockford Base32, no confusable characters), with expiry, max‑uses and per‑user limits. - ⚛️ **Atomic, idempotent, concurrency‑safe redemption** — a single conditional `UPDATE … WHERE current_uses < max_uses` that flips state in the same statement, backed by a `UNIQUE(code_id, redeemer_id)` index. `current_uses` can **never** exceed `max_uses`; a replay is a no‑op, never a double‑grant — even under a thundering herd. - 🏢 **Multi‑tenant by design** — every table is tenant‑scoped; two tenants can share the same human code. Single‑tenant apps get a zero‑config default. - 🎁 **Referral graph + double‑sided rewards** with a DB‑backed idempotency key (no double‑grants). - 📨 **Email invitations** — idempotent send/accept lifecycle, "who accepted vs. who didn't". - 🛡️ **Fail‑open anti‑abuse** — weighted velocity / disposable‑email / honeypot / blacklist scoring that surfaces a generic `rate_limited` (never a probing oracle) and stores **HMAC‑hashed** PII only. A detector fault never blocks a real user; seat safety is the atomic claim's job. - 🔑 **Per‑invite entitlement grants** — an invite can grant a role and project access on redemption, across one *or several* tenants. **GRANT‑never‑REVOKE**: it only ever raises access. - 📈 **Virality analytics** — K‑factor, acceptance / conversion rates, time‑to‑redeem percentiles, reconciled against the canonical rows (not a drifting rollup). - 🔔 **Events** on every lifecycle transition. - 🔒 **GDPR** — in‑place PII anonymization that **preserves aggregates** + a scheduled prune command. - 🧩 **Tri‑surface** — the same core is reachable from **PHP** (services + Artisan), a **REST API**(RBAC‑gated, publishable routes), and **MCP** tools. - 🤝 **Vendor‑neutral** — works on plain Fortify/Breeze; `spatie/laravel-permission`, `laravel/fortify`and `laravel/mcp` are optional, first‑class integrations. How it compares --------------- [](#how-it-compares) Capability**laravel‑invitations**doormanmateusjunges/invite‑codespdazcom/referralstaldres/waitlistInvite codes (max‑uses)✅✅✅——**Concurrency‑safe redemption**✅❌❌——**Idempotent replay**✅❌❌⚠️⚠️**Multi‑tenant scoping**✅❌❌❌❌Vanity / signed codes✅❌⚠️—⚠️Email invitations✅✅⚠️❌⚠️Referral graph + double‑sided rewards✅❌❌⚠️ referrer‑only❌**Anti‑abuse / fraud**✅❌❌⚠️ self‑ref only❌Per‑invite role/entitlement grant✅❌❌❌❌Virality analytics (K‑factor)✅❌❌❌❌GDPR erasure✅❌❌❌✅Events / hooks✅❌✅✅✅HTTP API + **MCP** surface✅❌❌❌❌Requirements ------------ [](#requirements) - PHP `^8.3` - Laravel `^12.0 | ^13.0` Installation ------------ [](#installation) ``` composer require padosoft/laravel-invitations php artisan migrate ``` Make your user model invitation‑aware: ``` use Illuminate\Foundation\Auth\User as Authenticatable; use Padosoft\Invitations\Concerns\InteractsWithInvitations; use Padosoft\Invitations\Contracts\InvitedAccount; class User extends Authenticatable implements InvitedAccount { use InteractsWithInvitations; // reads `email` + auth guard for the engine } ``` Publish the config (optional): ``` php artisan vendor:publish --tag=invitations-config ``` Quick start ----------- [](#quick-start) **Generate codes** (PHP): ``` use Padosoft\Invitations\Services\CodeGenerator; $code = app(CodeGenerator::class)->generateRandom(['max_uses' => 100]); $batch = app(CodeGenerator::class)->generateBatch(500); // 500 distinct codes ``` **Redeem a code** — atomic, idempotent, fraud‑gated: ``` use Padosoft\Invitations\Services\RedemptionService; $result = app(RedemptionService::class)->redeem($rawCode, $user, [ 'ip' => $request->ip(), 'fingerprint' => $request->header('X-Device'), ]); if ($result->ok) { // $result->already === true on an idempotent replay (no second grant) // $result->redemption, $result->referral } else { // $result->error: invalid | expired | exhausted | revoked | ineligible | rate_limited } ``` **Over the REST API** (routes auto‑register; attach your own auth/RBAC via config): ``` POST /api/invitations/redeem { "code": "Q7K92MNP" } POST /api/invitations/validate { "code": "Q7K92MNP" } # advisory, writes nothing GET /api/admin/invitations/metrics POST /api/admin/invitations/codes { "count": 50, "max_uses": 1 } ``` **Over MCP** — register the bundled tools on your server: ``` // app/Mcp/Servers/YourServer.php public array $tools = [ \Padosoft\Invitations\Mcp\Tools\InviteValidateCodeTool::class, \Padosoft\Invitations\Mcp\Tools\InviteGenerateCodesTool::class, \Padosoft\Invitations\Mcp\Tools\InviteMetricsTool::class, ]; ``` Architecture ------------ [](#architecture) ``` flowchart LR Caller["PHP · HTTP API · MCP · CLI"] --> RS[RedemptionService] RS -->|validate| CV[CodeValidator] RS -->|fail-open gate| FD[FraudDetector] RS -->|atomic UPDATE + UNIQUE| DB[(invite_codes / invite_redemptions)] RS -->|attribute| REF[ReferralService] --> RE[RewardEngine] RS -->|GRANT-never-REVOKE| PROV[Provisioner*] RS -->|fire once| EV([CodeRedeemed event]) MS[MetricsService] --> DB ``` Loading `*` Provisioners are pluggable: the `SpatiePermissionProvisioner` (role grant) ships by default; a host adds its own under the `invitations.provisioners` tag. Host integration seams ---------------------- [](#host-integration-seams) The engine never hard‑codes your app. Three small seams keep it vendor‑neutral: SeamDefaultOverride when…`Contracts\TenantResolver`single‑tenant (`'default'`)you're multi‑tenant — bind your own resolver`Contracts\Provisioner` (tag `invitations.provisioners`)`SpatiePermissionProvisioner` (role)you grant more on redemption (e.g. team/project membership)`Contracts\InvitedAccount``InteractsWithInvitations` traityour user model stores email differently``` // A multi-tenant host, in a service provider: $this->app->bind(\Padosoft\Invitations\Contracts\TenantResolver::class, MyTenantResolver::class); $this->app->tag([MyProjectMembershipProvisioner::class], 'invitations.provisioners'); ``` Events ------ [](#events) `CodeRedeemed` (fired **once**, on a fresh claim — never on an idempotent replay), `InvitationSent`, `InvitationAccepted`. Listen to grant perks, send a welcome, or update your own projections. GDPR ---- [](#gdpr) PII (ip / fingerprint / recipient) is stored hashed or anonymizable. The scheduled sweep anonymizes rows past the retention window **in place** — `current_uses`, funnel counts and K‑factor are untouched: ``` php artisan invite:prune-pii --days=90 ``` Configuration ------------- [](#configuration) All knobs live in `config/invitations.php` and are env‑overridable — code alphabet/length, signing key, PII retention, anti‑abuse thresholds/velocity/blocklists, and the route prefix + per‑surface middleware (attach your RBAC gate to `invitations.routes.admin_middleware`). Web admin panel --------------- [](#web-admin-panel) [`padosoft/laravel-invitations-admin`](https://github.com/padosoft/laravel-invitations-admin) ships a polished **React + Tailwind** admin SPA over this package's API — a virality dashboard plus campaigns, codes, invitations (who accepted vs. who didn't), referral graph, reward ledger, waitlist and anti‑abuse review. Default‑OFF, host‑gated, prebuilt assets (no JS toolchain to install). For apps that already run their own React SPA, the screens can be adapted natively instead of cross‑mounting. [![Invitations & Growth admin — virality dashboard](resources/laravel-invitations-admin-dashboard-dark.png)](resources/laravel-invitations-admin-dashboard-dark.png) Testing ------- [](#testing) ``` composer test # PHPUnit (Testbench) composer analyse # PHPStan composer check # format + analyse + test ``` License ------- [](#license) MIT © [Padosoft](https://www.padosoft.com). See [LICENSE](LICENSE). ### Health Score 47 — FairBetter than 93% of packages Maintenance93 Actively maintained with recent releases Popularity21 Limited adoption so far Community11 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 95.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~5 days Total 3 Last Release 35d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/10467699?v=4)[Lorenzo](/maintainers/lopadova)[@lopadova](https://github.com/lopadova) --- Top Contributors [![lopadova](https://avatars.githubusercontent.com/u/10467699?v=4)](https://github.com/lopadova "lopadova (22 commits)")[![ImgBotApp](https://avatars.githubusercontent.com/u/31427850?v=4)](https://github.com/ImgBotApp "ImgBotApp (1 commits)") --- Tags invitationinvitation-systemlaravellaravel-packagereferralreferral-systemlaravelmulti-tenantrewardsInviteinvitationsreferralwaitlistgrowthinvite-codesk-factor ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/padosoft-laravel-invitations/health.svg) ``` [![Health](https://phpackages.com/badges/padosoft-laravel-invitations/health.svg)](https://phpackages.com/packages/padosoft-laravel-invitations) ``` ### Alternatives [spatie/laravel-permission Permission handling for Laravel 12 and up 13.0k107.5M1.6k](/packages/spatie-laravel-permission)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M353](/packages/psalm-plugin-laravel)[spatie/laravel-health Monitor the health of a Laravel application 88212.7M182](/packages/spatie-laravel-health)[laravel/ai The official AI SDK for Laravel. 1.1k4.6M282](/packages/laravel-ai)[masterix21/laravel-licensing Laravel licensing package with polymorphic assignment to any model, activation keys, expirations/renewals, and seat control via LicenseUsage. Supports offline verification with public-key–signed tokens, a CLI to generate/rotate/revoke keys, and an extensible architecture via config and contracts. 1614.1k4](/packages/masterix21-laravel-licensing)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 46273.9k](/packages/harris21-laravel-fuse) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)