Pincho PHP Library

Official PHP client for Pincho push notifications.

Installation

composer require pincho/sdk

Quick Start

use Pincho\Client;

// Auto-load token from PINCHO_TOKEN env var
$client = new Client();
$client->send('Deploy Complete', 'Version 1.2.3 deployed');

// Or provide token explicitly
$client = new Client(token: 'YOUR_TOKEN');
$client->send('Alert', 'Server CPU at 95%');

Features

use Pincho\SendOptions;

// Full parameters
$options = new SendOptions(
    title: 'Deploy Complete',
    message: 'Version 1.2.3 deployed',
    type: 'deployment',
    tags: ['production', 'backend'],
    imageUrl: 'https://example.com/success.png',
    actionUrl: 'https://example.com/deploy/123',
);
$client->send($options);

// AI-powered notifications (NotifAI)
$response = $client->notifai('deployment finished, v2.1.3 is live');
echo $response->notification->title;   // AI-generated
echo $response->notification->message;

// Encrypted messages
$options = new SendOptions(
    title: 'Security Alert',
    message: 'Sensitive data',
    type: 'security',
    encryptionPassword: 'your_password',
);
$client->send($options);

Configuration

// Environment variables (recommended)
// PINCHO_TOKEN - API token (required if not passed to constructor)
// PINCHO_TIMEOUT - Request timeout in seconds (default: 30)
// PINCHO_MAX_RETRIES - Retry attempts (default: 3)

// Or explicit configuration
$client = new Client(
    token: 'YOUR_TOKEN',
    timeout: 60.0,
    maxRetries: 5,
);

Error Handling

use Pincho\Client;
use Pincho\Exceptions\AuthenticationException;
use Pincho\Exceptions\ValidationException;
use Pincho\Exceptions\RateLimitException;

try {
    $client = new Client();
    $client->send('Title', 'Message');
} catch (AuthenticationException $e) {
    echo "Invalid token";
} catch (ValidationException $e) {
    echo "Invalid parameters";
} catch (RateLimitException $e) {
    echo "Rate limited - auto-retry handled this";
}

Automatic retry with exponential backoff for network errors, 5xx, and 429 (rate limit).

Smart Rate Limiting

The library automatically handles rate limits with Retry-After header support:

$client = new Client();
$client->send('Alert', 'Message');

// Check rate limit status after any request
$rateLimit = $client->getLastRateLimit();
if ($rateLimit !== null) {
    echo "Remaining: {$rateLimit->remaining}/{$rateLimit->limit}";
    echo "Resets at: {$rateLimit->reset}";
}

See Advanced Documentation for detailed rate limit monitoring patterns.

Links

• Get Token: App → Settings → Help → copy token
• Documentation: https://pincho.app/help
• Repository: https://github.com/Pincho-App/pincho-php
• Packagist: https://packagist.org/packages/pincho/sdk

License

MIT