Laravel Tolt Laravel Package

Getting Started

• Install via Composer using the package name from the README, then let Laravel auto-discover the service provider.
• Publish any package config (php artisan vendor:publish --tag=tolt-config or the tag documented by the package) and review config/tolt.php.
• Add credentials to .env — typically TOLT_API_KEY, plus any sandbox/base-URL setting the package exposes. Never commit real keys.
• Read the package README first, then inspect the service provider bindings, config file, and the client/resource classes. That tells you whether to inject a client, use a facade, or call resource-specific classes.
• First practical use case: capture a referral, create or update the Tolt customer, generate/retrieve a referral link, and read back commissions. Build this as a small end-to-end spike before wiring it into registration or checkout.
• Verify sandbox/live behaviour immediately. Make one read call (programs or partners) and one write call (customer or link) before building larger flows.

Implementation Patterns

• Keep package calls out of controllers. Wrap them in application services or action classes, e.g. CreateToltCustomer, ResolveReferralLink, SyncToltCommission, so the rest of the app depends on your interface rather than the package API.
• Persist external IDs on local models: tolt_partner_id, tolt_customer_id, tolt_link_id, tolt_click_id, tolt_commission_id, tolt_transaction_id. Add unique indexes where the external ID should be unique.
• Referral capture: middleware or a registration listener reads the referral parameter, stores it in session/cookie with an expiry, and attaches it to the user after signup. Queue the remote customer creation so registration stays fast.
• Commission and transaction sync: use a scheduled command plus webhooks if supported. Upsert by external ID and keep a local ledger of what was synced, when, and the raw response for reconciliation.
• Promotion codes: validate early for UX, but revalidate at order placement. Cache program/promotion-code lookups briefly and invalidate on relevant webhook or sync events.
• Use Laravel's HTTP client fakes in tests. Build contract-style tests around your wrapper, not around every package method, so package upgrades are easier to absorb.
• Dispatch your own domain events (ReferralCaptured, CommissionRecorded) from the integration layer. This keeps Tolt concerns isolated and lets notifications, analytics, and accounting react without coupling to the package.
• For multi-tenant apps, resolve credentials per tenant at runtime if the package supports it; otherwise instantiate/configure a client per tenant and avoid singleton assumptions.

Gotchas and Tips

• Run php artisan config:clear after changing Tolt environment values; cached config is a common source of "wrong key/URL" confusion.
• Treat API keys as server-side secrets. Do not expose them through Inertia props, Livewire public properties, or frontend JS.
• Confirm sandbox versus production behaviour before testing money flows. Mixing keys across environments can create real partners, customers, or commissions.
• Pagination and rate limits are the usual failure points. Use the package's paginator/iterator where available, add retry with backoff for 429/5xx responses, and respect Retry-After.
• Money values: check whether commissions/transactions are returned in minor units, decimals, or strings. Store amounts in integer minor units plus currency; avoid floats.
• Mutating calls should be idempotent from your side. Use your own idempotency key or a local "already synced" guard before creating customers, commissions, or transactions.
• Webhooks, if supported, need CSRF exclusion, raw-body signature verification, duplicate handling, and a queue. Assume at-least-once delivery and make handlers idempotent.
• Expect eventual consistency. A click or conversion may not appear as a commission immediately; design sync/reconciliation jobs instead of relying on synchronous reads after writes.
• Validate nullable/optional API fields defensively. New affiliate platforms often return sparse objects for clicks, links, or promotion codes, and missing keys can break strict DTO mapping.
• Wrap the package behind your own interface even at 1.0.0. The initial release surface may still evolve; an adapter layer limits upgrade pain and gives you a place to add logging, metrics, and fallbacks.
• Extension points to review early: custom HTTP middleware, configurable base URL, event/listener hooks, and publishable config. These are where you add tracing, tenant resolution, and environment switching without forking the package.