README

A comprehensive PHP SDK for the Partnerize Partner API, built with Guzzle HTTP client.

Features

✅ Full coverage of all Partnerize Partner API endpoints (v1, v2, v3)
✅ Type-safe request/response DTOs with PHP 8.2+ native types
✅ Synchronous and asynchronous methods (Guzzle promises)
✅ Comprehensive error handling with typed exceptions
✅ Automatic JSON serialization/deserialization
✅ Pagination helpers for standard and cursor-based pagination
✅ Automatic retry logic for idempotent requests
✅ Rate limit detection and handling
✅ PSR-4 autoloading and PSR-12 coding standards
✅ Laravel integration support

Requirements

PHP 8.1 or higher
Guzzle HTTP Client 7.0 or higher

Installation

Install via Composer:

composer require partnerize/sdk-php

Or install directly from GitHub:

composer require luizsilva-dev/partnerize-partner-sdk-php

Quick Start

Basic Configuration

<?php

use Partnerize\SDK\PartnerizeClient;
use Partnerize\SDK\Config\Configuration;

// Create configuration
$config = new Configuration(
    applicationKey: 'your_application_key',
    userApiKey: 'your_user_api_key'
);

// Initialize client
$client = new PartnerizeClient($config);

Retrieving Campaigns

// List all campaigns
$campaigns = $client->campaigns()->list();

foreach ($campaigns->getCampaigns() as $campaign) {
    echo "Campaign: {$campaign->title}\n";
}

Creating a Tracking Link

use Partnerize\SDK\Models\TrackingLink\CreateTrackingLinkRequest;

$request = new CreateTrackingLinkRequest(
    campaignId: '111111l13',
    destinationUrl: 'https://example.com/product'
);

$trackingLink = $client->trackingLinks()->create($request);
echo "Tracking URL: {$trackingLink->getUrl()}\n";

Retrieving Conversions Report

use Partnerize\SDK\Models\Reporting\ConversionsReportRequest;

$request = new ConversionsReportRequest(
    startDate: new \DateTime('2024-01-01'),
    endDate: new \DateTime('2024-01-31')
);

$report = $client->reporting()->conversions($request);

foreach ($report->getConversions() as $conversion) {
    echo "Conversion ID: {$conversion->conversionId}, Amount: {$conversion->saleValue}\n";
}

Listing Partners/Participations

$partnerId = '111111l3';
$participations = $client->participations()->list($partnerId);

foreach ($participations->getParticipations() as $participation) {
    echo "Campaign: {$participation->campaignInfo->title}\n";
}

Pagination

Standard Pagination

use Partnerize\SDK\Pagination\StandardPaginator;

// Automatic pagination through all results
$paginator = new StandardPaginator(
    fn($offset, $limit) => $client->campaigns()->list($offset, $limit)
);

foreach ($paginator as $campaign) {
    echo "Campaign: {$campaign->title}\n";
}

Cursor-Based Pagination

use Partnerize\SDK\Pagination\CursorPaginator;

$paginator = new CursorPaginator(
    fn($cursorId, $limit) => $client->reporting()->conversions(
        new ConversionsReportRequest(
            startDate: new \DateTime('2024-01-01'),
            endDate: new \DateTime('2024-01-31'),
            cursorId: $cursorId,
            limit: $limit
        )
    )
);

foreach ($paginator as $conversion) {
    // Process conversion
}

Error Handling

use Partnerize\SDK\Exceptions\ApiException;
use Partnerize\SDK\Exceptions\AuthenticationException;
use Partnerize\SDK\Exceptions\RateLimitException;
use Partnerize\SDK\Exceptions\ValidationException;

try {
    $campaigns = $client->campaigns()->list();
} catch (AuthenticationException $e) {
    // Handle authentication errors
    echo "Auth failed: {$e->getMessage()}\n";
} catch (RateLimitException $e) {
    // Handle rate limiting
    echo "Rate limited. Retry after: {$e->getRetryAfter()} seconds\n";
} catch (ValidationException $e) {
    // Handle validation errors
    foreach ($e->getErrors() as $error) {
        echo "Validation error: {$error['message']}\n";
    }
} catch (ApiException $e) {
    // Handle general API errors
    echo "API Error [{$e->getStatusCode()}]: {$e->getMessage()}\n";
}

Asynchronous Requests

use GuzzleHttp\Promise\Utils;

// Execute multiple requests concurrently
$promises = [
    'campaigns' => $client->campaigns()->listAsync(),
    'partner' => $client->partnerManagement()->getDetailsAsync(),
];

$results = Utils::unwrap($promises);

// Access results
$campaigns = $results['campaigns'];
$partnerDetails = $results['partner'];

Laravel Integration

Register Service Provider

Add to config/app.php:

'providers' => [
    // ...
    Partnerize\SDK\Bridge\Laravel\PartnerizeServiceProvider::class,
],

'aliases' => [
    // ...
    'Partnerize' => Partnerize\SDK\Bridge\Laravel\PartnerizeFacade::class,
],

Configuration

Publish configuration file:

php artisan vendor:publish --provider="Partnerize\SDK\Bridge\Laravel\PartnerizeServiceProvider"

Add to .env:

PARTNERIZE_APPLICATION_KEY=your_application_key
PARTNERIZE_USER_API_KEY=your_user_api_key

Usage in Laravel

use Partnerize\SDK\PartnerizeClient;

class CampaignController extends Controller
{
    public function __construct(
        private PartnerizeClient $partnerize
    ) {}

    public function index()
    {
        $campaigns = $this->partnerize->campaigns()->list();
        return view('campaigns.index', compact('campaigns'));
    }
}

// Or using Facade
use Partnerize;

$campaigns = Partnerize::campaigns()->list();

Advanced Configuration

use GuzzleHttp\Client;
use Partnerize\SDK\Config\Configuration;
use Partnerize\SDK\PartnerizeClient;

// Custom Guzzle client with additional options
$httpClient = new Client([
    'timeout' => 30,
    'connect_timeout' => 10,
    'verify' => true,
]);

$config = new Configuration(
    applicationKey: 'your_application_key',
    userApiKey: 'your_user_api_key',
    baseUrl: 'https://api.partnerize.com', // Optional: override base URL
    maxRetries: 3, // Optional: configure retry attempts
    retryDelay: 1000 // Optional: delay between retries in milliseconds
);

$client = new PartnerizeClient($config, $httpClient);

Webhook Verification

use Partnerize\SDK\Webhook\WebhookVerifier;

$verifier = new WebhookVerifier('your_webhook_secret');

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PARTNERIZE_SIGNATURE'] ?? '';

if ($verifier->verify($payload, $signature)) {
    // Process webhook
    $data = json_decode($payload, true);
} else {
    http_response_code(401);
    exit('Invalid signature');
}

Testing

Run unit tests:

composer test

Run static analysis:

composer phpstan

Check coding standards:

composer phpcs

Run all checks:

composer check

License

MIT License. See LICENSE file for details.

Support

For API documentation and support, visit:

API Documentation: https://api-docs.partnerize.com/partner/
GitHub Issues: https://github.com/luizsilva-dev/partnerize-partner-sdk-php/issues
Support Email: support@partnerize.com

luizsilva-dev / partnerize-partner-sdk-php

Maintainers

Details