PHPackages aiarmada/affiliates - 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. [Utility & Helpers](/categories/utility) 4. / 5. aiarmada/affiliates ActiveLibrary[Utility & Helpers](/categories/utility) aiarmada/affiliates =================== Affiliate attribution, referral tracking, and commission management for Laravel commerce stacks. v13.0.1(1mo ago)06↑1400%2MITPHP Since Mar 18Pushed 1mo agoCompare [ Source](https://github.com/AIArmada/affiliates)[ Packagist](https://packagist.org/packages/aiarmada/affiliates)[ Docs](https://github.com/aiarmada/commerce)[ RSS](/packages/aiarmada-affiliates/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (1)Versions (5)Used By (2) AIArmada Affiliates =================== [](#aiarmada-affiliates) Affiliate attribution, referral tracking, and commission workflows for Laravel commerce teams. The package ships with first-class hooks for **aiarmada/cart** and **aiarmada/vouchers**, but remains completely independent – you can store affiliate programs, manage payouts, and expose APIs without installing other commerce packages. Highlights ---------- [](#highlights) - 🧾 **Programs & Partners** – Model affiliate partners with commission policies, voucher links, metadata, and optional owner scoping for multi-tenant platforms. - 🎯 **Attribution Graph** – Persist cart-level attribution records (cart identifier + instance) with UTM context, device data, and voucher links. - πŸ’° **Commission Engine** – Basis-point and fixed-fee calculations powered by configurable defaults and overridable services. - 🧩 **Composable Integrations** – Drop-in Cart + Voucher bridges automatically attach affiliates the moment a code or voucher is applied. - πŸͺ **Visit Cookies** – Optional middleware captures affiliate clicks before a cart exists, keeping referrals alive across sessions. - πŸ“‘ **Events Everywhere** – `AffiliateAttributed` and `AffiliateConversionRecorded` events make automation straightforward. Installation ------------ [](#installation) ``` composer require aiarmada/affiliates php artisan vendor:publish --tag=affiliates-config php artisan vendor:publish --tag=affiliates-migrations php artisan migrate ``` ### Optional integrations [](#optional-integrations) PackageOutcome`aiarmada/cart`Adds fluent helpers such as `Cart::attachAffiliate('CODE')`, automatic metadata persistence, and conversion recording utilities.`aiarmada/vouchers`Reads voucher metadata to auto-attach affiliates, enabling voucher-driven referral programs.`aiarmada/filament-affiliates`Filament plugin for operating affiliate programs, approvals, and analytics.Both integrations are lazy – the service provider detects presence via `class_exists` ensuring you can run affiliates inside bespoke apps or headless APIs. Core Concepts ------------- [](#core-concepts) ModelPurpose`Affiliate`Canonical partner/program definition with status, commission policy, voucher hints, and optional owner scoping.`AffiliateAttribution`Represents a cart-level session that originated from an affiliate. Stores cart identifier, instance, UTM context, voucher code, agent data, and timestamps.`AffiliateConversion`A recorded commercial event linked to an affiliate (order, subscription, invoice, etc.) complete with commission totals and payout status.### Cart helpers [](#cart-helpers) When `aiarmada/cart` is present the package registers a manager proxy so you can call these fluent methods via the `Cart` facade: ``` Cart::attachAffiliate('AIARMADA42', [ 'utm_source' => 'newsletter', 'landing_url' => url()->current(), ]); Cart::hasAffiliate(); // true Cart::recordAffiliateConversion([ 'external_reference' => 'SO-100234', 'order_reference' => 'SO-100234', // compatibility alias 'subtotal' => $order->subtotal_minor, // optional 'value_minor' => $order->total_minor, 'total' => $order->total_minor, // compatibility alias ]); ``` All metadata lives under a configurable key (defaults to `affiliate`) so normalized cart snapshots and third-party systems can read attribution context without any additional joins. ### Voucher bridge [](#voucher-bridge) Attach metadata to vouchers and the package will automatically hydrate the cart the moment a voucher is applied: ``` $voucher->metadata = [ 'affiliate_code' => 'AIARMADA42', ]; ``` The `AttachAffiliateFromVoucher` listener handles validation, owner scoping, and persistence so staff can run co-branded campaigns without touching application code. Set `default_voucher_code` on an affiliate and the listener will fall back to it when no explicit metadata is present (configurable via `affiliates.integrations.vouchers.match_default_voucher_code`). ### Cookie tracking middleware [](#cookie-tracking-middleware) Activate the `TrackAffiliateCookie` middleware (auto-registered in the `web` group by default) to capture affiliate visits before a cart exists. The middleware: 1. Looks for query parameters such as `aff`, `affiliate`, `ref`, or `referral`. 2. Drops a configurable cookie (defaults to `affiliate_session`). 3. Persists an `AffiliateAttribution` row with UTM metadata, referrer, and device data. 4. Automatically hydrates the cart once the customer starts shopping, ensuring conversions are linked even if the voucher field was never touched. Tweak behaviour via `config/affiliates.php`: ``` 'cookies' => [ 'enabled' => true, 'name' => 'affiliate_session', 'ttl_minutes' => 60 * 24 * 30, 'query_parameters' => ['aff', 'affiliate', 'ref', 'referral'], 'require_consent' => false, 'consent_cookie' => 'affiliate_consent', 'auto_register_middleware' => true, 'respect_dnt' => false, ], ``` Disable auto-registration or alias the middleware manually using the `affiliates.cookie` key if you need to scope tracking to custom route groups or consent flows. Rate limiting and consent - IP rate limits for attribution capture (`tracking.ip_rate_limit.*`). - Self-referral blocking when the current owner matches the affiliate owner. - Consent gate via `cookies.require_consent` with a configurable consent cookie name. Payout batches Use `AffiliatePayoutService` to group conversions into payout batches for exports or provider handoff. Conversions are linked via `affiliate_payout_id`, and payout records store aggregate totals and schedule/paid timestamps. Multi-level uplines are supported via `parent_affiliate_id` on affiliates and `payouts.multi_level.*` config to define commission shares per level. Webhook + link utilities - Optional webhooks for attribution/conversion payloads (`events.dispatch_webhooks` + `webhooks.*` endpoints/headers). - Signed referral links via `AffiliateLinkGenerator` using configurable parameter name, TTL, and signing key. Configuration ------------- [](#configuration) Key options exposed via `config/affiliates.php`: - `table_names` – override table names per tenant or schema layout. - `owner` – plug in a resolver to scope queries per marketplace merchant. - `cart.metadata_key` – customize the metadata key stored on carts. - `integrations.vouchers.metadata_keys` – control which metadata paths are inspected for affiliate codes. - `tracking.block_self_referral` – prevent owners/tenants from crediting their own affiliate code when they are the active owner. - `cookies.require_consent` / `cookies.consent_cookie` – gate tracking behind explicit consent. - `commissions` – default currency, rounding, and approval behaviour. Events ------ [](#events) - `AffiliateAttributed` – fired after a cart is successfully attributed. Includes affiliate + attribution DTOs. - `AffiliateConversionRecorded` – emitted whenever a conversion row is created. Perfect for payouts or Slack alerts. Both events are broadcast through Laravel’s dispatcher and can be toggled via config. Testing ------- [](#testing) ``` composer test -- --group=affiliates ``` > The package ships with unit coverage for the commission calculator and attribution manager. Extend the Pest suite inside `packages/affiliates/tests` for your application specifics. License ------- [](#license) Released under the [MIT license](../../LICENSE). ### Health Score 38 β€” LowBetter than 84% of packages Maintenance96 Actively maintained with recent releases Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity36 Early-stage or recently created project 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 4 Last Release 51d ago Major Versions v1.0.2 β†’ v13.0.12026-03-18 ### Community Maintainers ![](https://www.gravatar.com/avatar/726da4efcb731bc0ebcdd0b7ce64759e1f8dd63f6f771eab335458f6a2f2d3af?d=identicon)[sairiz](/maintainers/sairiz) ### Embed Badge ![Health badge](/badges/aiarmada-affiliates/health.svg) ``` [![Health](https://phpackages.com/badges/aiarmada-affiliates/health.svg)](https://phpackages.com/packages/aiarmada-affiliates) ``` ### Alternatives [icehouse-ventures/laravel-mermaid Simple package to generate diagrams in Laravel using the Mermaid.js library 2630.0k](/packages/icehouse-ventures-laravel-mermaid) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)