Laravel Affiliate Laravel Package

Getting Started

1. Install the package and run composer require a2zweb/affiliate (check the namespace against your lockfile).
2. Publish config and assets:

   php artisan vendor:publish --tag=affiliate-config
   php artisan vendor:publish --tag=affiliate-views        # publishes blade + livewire overrides
   php artisan vendor:publish --tag=affiliate-migrations
   php artisan migrate
   

3. First thing to check on v1.3.0+: open config/affiliate_statements.php and set a real issuing entity. Without AFFILIATE_STATEMENTS_ENTITY_CODE and AFFILIATE_STATEMENTS_LEGAL_NAME (env-driven), any payout generation, issuing, or completion throws IssuingEntityNotConfigured. The pre-1.3.0 Acme Ltd. placeholder is explicitly rejected.
4. Browse the package source in vendor/a2zweb/affiliate/ — start with src/Support/IssuingEntity.php, src/Exceptions/IssuingEntityNotConfigured.php, the RevenueResolver classes, and the resources/views/{blade,livewire} trees. The resources/boost/guidelines/core.blade.php guideline and the affiliate-integration skill (if you use Laravel Boost) are the fastest orientation for AI-assisted work.
5. First useful flow: register a referral partner (attribution kicks in automatically via the package's global middleware and Registered event listener — no affiliate.capture alias to wire up), then visit the partner statement page at the default affiliate::partner-statement view (now shipped in-package) to confirm the pipeline end-to-end.

Implementation Patterns

• Attribution is hands-off. The package registers global middleware plus a Registered event listener. You do not need to add a route middleware alias or call a capture helper in your auth controllers. If you previously wired affiliate.capture manually, remove that — it's no longer the documented path.
• View overrides. Publish and edit in the correct destination directories:
  • Blade: resources/views/vendor/affiliate/* (overrides affiliate::*)
  • Livewire: resources/views/vendor/affiliate-livewire/* Use --tag=affiliate-views-blade or --tag=affiliate-views-livewire to publish only one tree. This is the correct pattern for skinning the partner statement without forking the package.
• Statement view. affiliate.partner_statement_view defaults to affiliate::partner-statement, which ships with the package. You only need a host view if you want a custom layout — leave the config value blank to inherit the default rather than duplicating it.
• Custom revenue logic. Extend or bind your own RevenueResolver in a service provider. Confirm signatures against the real RevenueResolver methods (the README example was corrected in 1.3.0) — do not copy older blog snippets that reference stub method names.
• Payout lifecycle. Model this as generate → issue → complete. Each step now validates the issuing entity, so the config must be correct before any step, not just before rendering the statement. Wrap payout batch jobs in try/catch for IssuingEntityNotConfigured and fail loudly to the operator rather than silently skipping.
• Referral thresholds. The threshold compares against all referrals (not just qualified/converted ones) per the corrected README — audit your gating logic if you built business rules around the previous interpretation.
• Laravel Boost integration. The shipped guidelines/core.blade.php and affiliate-integration skill are the canonical examples to point new hires (or AI assistants) at — they mirror current method names and config keys.

Gotchas and Tips

• Breaking: placeholder issuing entity is now fatal. affiliate_statements.issuing_entity defaults to null in 1.3.0. Generation, issuance, and payout completion all throw IssuingEntityNotConfigured and log an error while code or legal_name is empty or still holds a pre-1.3.0 placeholder. Payout completion checks before marking the request paid, so a misconfigured deployment can leave requests stuck — set the env vars first, then retry.
• Published config is a trap. If you published config/affiliate_statements.php on an older version, the file still contains Acme Ltd. defaults. Either delete it (env-driven defaults handle everything) or scrub every placeholder field. The validator specifically rejects the old Acme values, so the error will point you at the file.
• View publish path changed in 1.3.0. Old command copied into vendor/affiliate/{blade,livewire} — a path Laravel never reads. Move:
  • resources/views/vendor/affiliate/blade/* → resources/views/vendor/affiliate/*
  • resources/views/vendor/affiliate/livewire/* → resources/views/vendor/affiliate-livewire/* Delete unmodified copies; they'll shadow future package updates once they finally take effect.
• Silent override bug is fixed — if your customizations "never worked" pre-1.3.0, the cause was the bad publish path. Re-publish with the new tags, then re-apply your diffs.
• Empty config ≠ error. An empty affiliate.partner_statement_view falls back to the shipped view (new in 1.3.0). Don't set it to '' expecting an error; use null/unset for "default", or point it at your own view.
• Debugging entity failures. The exception is thrown alongside an error-level log — check storage/logs/laravel.log for the specific field that failed validation (IssuingEntity reports which of code, legal_name, address, country, company number, tax note is missing/placeholder).
• Upgrade checklist for existing installs:
  1. Set AFFILIATE_STATEMENTS_ENTITY_CODE and AFFILIATE_STATEMENTS_LEGAL_NAME (+ address/country/company number/tax note) in .env.
  2. Remove or scrub any published config/affiliate_statements.php containing Acme defaults.
  3. Move published views to the new paths and delete untouched copies.
  4. Drop the affiliate.capture alias if you added one following older docs.