PHPackages a2zwebltd/laravel-affiliate - 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. [API Development](/categories/api) 4. / 5. a2zwebltd/laravel-affiliate ActiveLibrary[API Development](/categories/api) a2zwebltd/laravel-affiliate =========================== Generic affiliate / revenue-share engine for Laravel: opt-in workflow, monthly commission closure, admin adjustments, partner-initiated payout requests, Blade+Alpine and Livewire dashboards. v1.1.2(1mo ago)045↓75%MITPHPPHP ^8.2CI failing Since Apr 30Pushed 1mo agoCompare [ Source](https://github.com/a2zwebltd/laravel-affiliate)[ Packagist](https://packagist.org/packages/a2zwebltd/laravel-affiliate)[ Docs](https://github.com/a2zwebltd/laravel-affiliate)[ RSS](/packages/a2zwebltd-laravel-affiliate/feed)WikiDiscussions main Synced 1w ago READMEChangelog (6)Dependencies (9)Versions (7)Used By (0) Laravel Affiliate ================= [](#laravel-affiliate) Generic affiliate / revenue-share engine for Laravel β€” opt-in workflow, monthly commission closure, admin adjustments, partner-initiated payout requests, immutable commission statements, Blade+Alpine and Livewire dashboards. Features -------- [](#features) - πŸ”— **Cookie + query-param attribution**: First-touch or last-touch, configurable lifetime. - πŸ“… **Monthly closure**: Idempotent close-month job snapshots commission rates per row; recalculation safe. - 🧾 **Immutable commission statements**: Auto-generated, PDF-rendered, stamped with issuing-entity snapshot. - πŸ’Έ **Partner-initiated payouts**: Self-serve payout requests with PDF invoice upload + admin approval flow. - βš–οΈ **Admin adjustments**: Internal-only revenue corrections, applied at the partner's commission rate. - 🎨 **Drop-in UI**: Blade + Alpine partner dashboard, plus optional Livewire forms. - πŸ› οΈ **Nova-ready**: Resources, actions, and a single-line `NovaIntegration::resources()` registration. - 🌍 **i18n**: Every user-facing string is wrapped in `__()` and ready for the host app's translation pipeline. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 12 or 13 - `barryvdh/laravel-dompdf` ^3.1 (PDF statements) - `rinvex/countries` ^9.1 (country dropdown on the apply form) - *(optional)* `laravel/nova` ^5 β€” admin resources & actions - *(optional)* `livewire/livewire` ^3 / ^4 β€” reactive partner forms Installation ------------ [](#installation) ``` composer require a2zwebltd/laravel-affiliate ``` The service provider is auto-discovered. Publish migrations and run them: ``` php artisan vendor:publish --tag=affiliate-migrations php artisan migrate ``` Optionally publish config and views: ``` php artisan vendor:publish --tag=affiliate-config php artisan vendor:publish --tag=affiliate-views ``` Quick Start ----------- [](#quick-start) ### 1. Implement `RevenueResolver` in your app [](#1-implement-revenueresolver-in-your-app) The package never queries your billing system directly β€” you implement a thin adapter: ``` use A2ZWeb\Affiliate\Contracts\RevenueResolver; class StripeRevenueResolver implements RevenueResolver { public function revenueCentsForUserMonth(int $userId, int $year, int $month): int { // Sum realised revenue (paid invoices) for $userId in (year, month). return (int) Invoice::query() ->where('user_id', $userId) ->whereYear('paid_at', $year) ->whereMonth('paid_at', $month) ->sum('amount_cents'); } } ``` Bind it in `config/affiliate.php`: ``` 'resolvers' => [ 'revenue' => \App\Affiliate\StripeRevenueResolver::class, 'referred_user_info' => null, // optional ], ``` ### 2. Add the affiliate concern to your User model [](#2-add-the-affiliate-concern-to-your-user-model) ``` use A2ZWeb\Affiliate\Concerns\HasAffiliateProgram; class User extends Authenticatable { use HasAffiliateProgram; } ``` This adds `affiliatePartner()` and `affiliateLink()`. ### 3. Capture attribution on signup [](#3-capture-attribution-on-signup) In your registration controller (or a `Registered` listener): ``` use A2ZWeb\Affiliate\Services\ReferralAttributor; app(ReferralAttributor::class)->attributeNewUser($user, $request); ``` The cookie is set automatically by the `affiliate.capture` middleware whenever a visitor lands on a page with `?aff=CODE`. ### 4. Schedule monthly closure [](#4-schedule-monthly-closure) In `routes/console.php` (or `app/Console/Kernel.php`): ``` Schedule::command('affiliate:close-month') ->monthlyOn(1, '02:00') ->onOneServer(); ``` That's it β€” once a partner is approved and you ship referral codes, the engine will close commissions on the 1st of each month. Usage Examples -------------- [](#usage-examples) ### Manual referral attachment (Nova action) [](#manual-referral-attachment-nova-action) When a referral was missed (cookie cleared, signup race, manual import), use the **Attach referral** action on the AffiliatePartner Nova resource: 1. Open the partner detail page in Nova. 2. Run `Attach referral` β€” provide an email *or* user ID, optional `attributed_at` (for backdating), and tick "Recalculate" to trigger the monthly closer for past months. 3. The action enforces the `referred_user_id` UNIQUE constraint and config-driven self-referral / first-touch rules. Programmatic equivalent: ``` use A2ZWeb\Affiliate\Services\ReferralAttributor; use Illuminate\Support\Carbon; $referral = app(ReferralAttributor::class)->manuallyAttach( $partner, $referredUser, Carbon::parse('2026-02-15'), ); ``` ### Recalculate a single partner [](#recalculate-a-single-partner) ``` php artisan affiliate:recalc-partner 1234 ``` Re-runs `MonthlyCloser` for partner user `1234` β€” picks up new referrals, adjustments, or rate overrides without touching other partners. ### Issue a commission statement [](#issue-a-commission-statement) Statements are generated when an admin marks a payout request as approved (or via the `Generate statement for period` Nova action). Once issued they are **immutable** β€” corrections happen via `AffiliateAdjustment` rows, never by editing the statement. ``` use A2ZWeb\Affiliate\Services\CommissionStatementGenerator; $statement = app(CommissionStatementGenerator::class)->generateForPartner( $partner, Carbon::parse('2026-02-01')->startOfMonth(), Carbon::parse('2026-02-01')->endOfMonth(), ); ``` Nova Integration ---------------- [](#nova-integration) If `laravel/nova` is installed, register the resources in your `NovaServiceProvider`: ``` use A2ZWeb\Affiliate\Nova\NovaIntegration; protected function resources(): void { Nova::resources(NovaIntegration::resources()); } protected function gates(): void { // ...your existing setup... Nova::mainMenu(fn (Request $request) => [ // ... NovaIntegration::menuSection(), ]); } ``` Resources registered: - `AffiliatePartner` β€” applications, status, payout details, audit trail. - `AffiliateCommission` β€” read-only monthly rows. - `AffiliateReferral` β€” read-only attribution log. - `AffiliatePayoutRequest` β€” partner-initiated payouts with approval/reject/mark-paid actions. - `AffiliateCommissionStatement` (+ `AffiliateCommissionStatementLine`) β€” issued statements with PDF download. - `AffiliateAdjustment` β€” admin-only revenue corrections. Bundled actions: `Approve`, `Reject`, `Suspend`, `Recalculate commissions`, `Generate statement for period`, `Attach referral`, `Approve payout`, `Reject payout`, `Mark as paid`, `Issue statement`, `Mark statement paid`, `Cancel statement`. Configuration ------------- [](#configuration) All keys in `config/affiliate.php` can be overridden by environment variables. A few highlights: EnvDefaultDescription`AFFILIATE_REVENUE_SHARE_BP``3000`Default commission rate in basis points (3000 = 30%).`AFFILIATE_MIN_REFERRED_USERS``2`Number of paying referrals required before a user can apply.`AFFILIATE_MIN_PAYOUT_CENTS``5000`Minimum balance required to request a payout.`AFFILIATE_ATTRIBUTION``first_touch``first_touch` or `last_touch`.`AFFILIATE_WINDOW_MODE``lifetime``lifetime` or `windowed`.`AFFILIATE_WINDOW_MONTHS``12`When `windowed`, how many months a referral keeps generating commissions.`AFFILIATE_COOKIE_TTL_DAYS``60`Attribution cookie lifetime.`AFFILIATE_ADMIN_EMAIL`β€”Address that receives admin notifications.`AFFILIATE_LAYOUT``layouts.app`Blade layout used by partner pages.`AFFILIATE_NOVA_USER_RESOURCE``App\Nova\User`Class used for `BelongsTo` user fields.Per-partner rate overrides live on `affiliate_partners.revenue_share_bp` and take precedence over the global default for *future* commissions; historical rows keep their snapshot rate. Architecture ------------ [](#architecture) ### Data model [](#data-model) ``` users ──< affiliate_partners β”‚ β”‚ β”‚ β”œβ”€β”€< affiliate_referrals ──> users (referred) β”‚ β”œβ”€β”€< affiliate_commissions (one per partner+referral+month) β”‚ β”œβ”€β”€< affiliate_adjustments (admin-only revenue correction rows) β”‚ └──< affiliate_payout_requests β”‚ β”‚ β”‚ └──< affiliate_commission_statements β”‚ β”‚ β”‚ └──< affiliate_commission_statement_lines └──< affiliate_terms_acceptances (versioned ToS audit log) ``` ### Lifecycle [](#lifecycle) 1. **Visit** β€” `affiliate.capture` middleware reads `?aff=CODE` and sets a cookie. 2. **Signup** β€” host app calls `ReferralAttributor::attributeNewUser()` which writes an `affiliate_referrals` row (subject to UNIQUE on `referred_user_id`). 3. **Application** β€” qualifying user submits the apply form; `AffiliatePartner` row is created with `status=pending`. 4. **Decision** β€” admin approves/rejects via Nova; partner email is dispatched. 5. **Monthly close** β€” `affiliate:close-month` iterates approved partners, sums revenue from `RevenueResolver`, computes commission rows. 6. **Payout request** β€” partner self-serves; admin approves; `MarkPayoutRequestPaid` action runs the `PayoutCompletionWorkflow` which issues an immutable PDF statement. ### Key services [](#key-services) ServiceResponsibility`ReferralAttributor`Cookie/code attribution; `manuallyAttach()` for admin tools.`MonthlyCloser`Idempotent close-month + per-partner recalc.`CommissionCalculator`Per-partner-month β†’ commission cents.`CommissionStatementGenerator` / `CommissionStatementIssuer`Draft β†’ issue lifecycle.`PayoutRequestService` / `PayoutCompletionWorkflow`Approve/reject/pay flows.`EligibilityChecker`"Can this user apply?" gate.`PartnerStatistics`Cached KPI feed for the partner dashboard.Routes ------ [](#routes) By default the package mounts a `dashboard/affiliate` route group with `web,auth` middleware: RouteNamePurpose`GET /``affiliate.dashboard`Partner dashboard (state-aware: no-partner / pending / approved / rejected / suspended).`GET /apply``affiliate.apply.show`Apply form.`POST /apply``affiliate.apply.store`Submit application.`PATCH /payout-details``affiliate.payout-details.update`Edit payout details after approval.`POST /payouts``affiliate.payouts.store`Request payout.`DELETE /payouts/{request}``affiliate.payouts.cancel`Cancel pending payout request.`GET /statements/{statement}``affiliate.statements.show`Partner-facing statement detail.`GET /statements/{statement}/download``affiliate.statements.download`Signed PDF download.Disable the default routes by setting `affiliate.routes.enabled = false` and registering your own. Localization ------------ [](#localization) Every user-facing string passes through `__()` β€” including Nova labels, notification subjects, Livewire flash messages, and the PDF statement template. The package ships no language files; the host app is expected to extract keys via its own pipeline (e.g. a `translate:extract` artisan command). Run your extractor over the package's `src/` and `resources/views/` paths to harvest all keys. Testing ------- [](#testing) ``` composer test ``` The test suite uses Pest + Orchestra Testbench and exercises the full closure lifecycle with stub revenue resolvers. Contributing ------------ [](#contributing) Issues and PRs are welcome. Please open a discussion before tackling large changes β€” the engine has a few non-obvious invariants (idempotent closure, immutable statements) that are easy to break. Security -------- [](#security) Found a vulnerability? Please email **** rather than opening a public issue. Credits ------- [](#credits) - [A2Z Web Ltd](https://a2zweb.co) - [Dawid Makowski](https://github.com/makowskid) (maintainer) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). See the `license` field in `composer.json`. ### Health Score 42 β€” FairBetter than 88% of packages Maintenance92 Actively maintained with recent releases Popularity11 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~0 days Total 6 Last Release 39d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2b500dd3d9b470b50b1ed911cd24a6fdcce51dd97dceb4f97879f727a14495a8?d=identicon)[dawid-makowski](/maintainers/dawid-makowski) --- Top Contributors [![makowskid](https://avatars.githubusercontent.com/u/6271194?v=4)](https://github.com/makowskid "makowskid (6 commits)") --- Tags laravelpayoutsreferralaffiliatepartnerscommissionrevenue-share ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/a2zwebltd-laravel-affiliate/health.svg) ``` [![Health](https://phpackages.com/badges/a2zwebltd-laravel-affiliate/health.svg)](https://phpackages.com/packages/a2zwebltd-laravel-affiliate) ``` ### Alternatives [unopim/unopim UnoPim Laravel PIM 10.1k2.2k](/packages/unopim-unopim)[statamic/cms The Statamic CMS Core Package 4.8k3.5M901](/packages/statamic-cms)[darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 2.9k36.4M124](/packages/darkaonline-l5-swagger)[bagisto/bagisto Bagisto Laravel E-Commerce 26.9k169.0k9](/packages/bagisto-bagisto)[knuckleswtf/scribe Generate API documentation for humans from your Laravel codebase.✍ 2.3k13.5M59](/packages/knuckleswtf-scribe)[krayin/laravel-crm Krayin CRM 22.6k33.4k1](/packages/krayin-laravel-crm) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)