Laravel Partnerstack Laravel Package

Getting Started

1. Install the package with Composer and publish its config:

   composer require <vendor>/laravel-partnerstack
   php artisan vendor:publish --tag=partnerstack-config
   

2. Add credentials to .env using the names documented in config/partnerstack.php. Clear cached config after changing them:

   php artisan config:clear
   

3. Look first at:
   • The package README for exact resource/method names.
   • config/partnerstack.php for auth, base URL, and environment options.
   • The service provider and facade/client binding to see what is resolvable from the container.
   • The resource/endpoint classes for partnerships, customers, transactions, deals, actions, rewards, leads, groups, and webhooks.
   • Any published webhook route, middleware, or signature-verification class.

A sensible first use case is a read-only smoke test: resolve the client in php artisan tinker or a temporary Artisan command and list partnerships or customers. Verify credentials and response shape before wiring writes or webhooks. Then add one webhook endpoint in a non-production environment and confirm signature verification and payload logging.

Implementation Patterns

• Inject the client, use the facade sparingly. In application code, constructor-inject the package client or a small adapter around it. Use the facade for tinker sessions, one-off commands, and prototypes.
• Wrap the package behind your own service. Expose methods like syncCustomer(), recordTransaction(), or listActivePartnerships() rather than letting controllers call package resource methods directly. This limits upgrade pain from a 1.0 package.
• Use queue jobs for writes and bulk reads. Creating customers, recording transactions, and syncing rewards should run in jobs with retries and backoff. Keep API calls out of synchronous web requests except for low-latency reads.
• Persist PartnerStack IDs and raw payloads. Upsert local records by the PartnerStack resource ID, and keep the raw JSON in a payload column for debugging and replay. Map into your own DTOs/models for domain use.
• Handle pagination explicitly. Use the package’s pagination helpers or iterate pages until exhausted. Avoid assuming a single response contains all customers, transactions, or leads.
• Webhook flow: define a dedicated route, exclude it from CSRF, read the raw request body, verify the signature with the package’s verifier/middleware, persist the event with its event ID, then dispatch a job. Return 2xx quickly and process asynchronously.
• Make webhook handling idempotent. Store the PartnerStack event ID or a hash of the payload and skip duplicates. Webhook providers retry; your handler must tolerate repeated delivery.
• Schedule reconciliation syncs. Use scheduled commands to pull transactions, rewards, and leads periodically. Webhooks are not a complete replacement for backfill or recovery after downtime.
• Testing: override package config in tests, use Laravel’s Http::fake() for HTTP-level fakes, and keep fixture payloads for webhook signature tests. Assert that your adapter maps package responses into your own models correctly.
• Integration tip: after syncing a customer, transaction, or reward, fire your own domain events so the rest of the application does not depend on the package’s response format.

Gotchas and Tips

• This is a 1.0 release. Pin the version in composer.json, read the changelog before upgrading, and keep package calls behind an adapter. Expect possible API-surface adjustments as the package matures.
• Config caching bites. If credentials or base URLs seem ignored in production, run php artisan config:clear or rebuild the config cache.
• Environment separation. Confirm whether the config supports sandbox/test versus production base URLs. Do not point tests or local development at production PartnerStack data.
• Auth details matter. Use the exact credential names from the published config. Do not assume public/secret key naming; check the README and config comments.
• Do not retry non-idempotent POSTs blindly. Retries are useful for reads and idempotent writes, but creating customers or transactions can duplicate records. Use idempotency keys if the API supports them, or reconcile by external ID.
• Respect rate limits. Watch for 429 responses and Retry-After headers. Use exponential backoff and avoid large synchronous loops in a single request.
• Webhook signatures are computed over the raw body. If you verify against $request->all() or a reserialized array, verification can fail. Read the raw content and verify before JSON decoding.
• Unknown webhook events should not crash the endpoint. Log them, persist if useful, and return success. New event types can appear without a package release.
• Money and timestamps need care. Transaction and reward amounts may be in minor units or strings; statuses may be enums with unknown future values. Cast defensively and preserve the raw payload.
• Debugging: enable HTTP client logging locally, inspect the package exception’s response body and status code, and log PartnerStack request IDs if exposed. Never log API secrets, webhook signatures, or full customer PII.
• Extension points: prefer published config, container bindings, custom HTTP client/Guzzle middleware, and package events over editing vendor files. If the package exposes macros or custom base URLs, use those for testing and proxies.
• Secure the webhook route. Restrict it where possible, verify signatures, and avoid exposing it through permissive middleware. Treat every webhook payload as untrusted until verified.