PHP Integration

Zyphr doesn't have an official PHP SDK yet, but the REST API is straightforward to use with cURL or Guzzle.

Using cURL (No Dependencies)

<?php

class ZyphrClient
{
    private string $apiKey;
    private string $baseUrl;

    public function __construct(string $apiKey, string $baseUrl = 'https://api.zyphr.dev/v1')
    {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }

    public function request(string $method, string $path, ?array $body = null): array
    {
        $ch = curl_init($this->baseUrl . $path);

        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json',
        ];

        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_CUSTOMREQUEST => $method,
        ]);

        if ($body !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        }

        $response = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $data = json_decode($response, true);

        if ($statusCode >= 400) {
            throw new Exception(
                "API error ({$statusCode}): " . ($data['error']['message'] ?? $response)
            );
        }

        return $data;
    }
}

Using Guzzle

If you prefer Guzzle, install it first:

composer require guzzlehttp/guzzle

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;

$client = new Client([
    'base_uri' => 'https://api.zyphr.dev/v1/',
    'headers' => [
        'X-API-Key' => getenv('ZYPHR_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);

// Send an email
$response = $client->post('emails', [
    'json' => [
        'to' => 'user@example.com',
        'subject' => 'Welcome!',
        'html' => '<h1>Hello from PHP!</h1>',
    ],
]);

$result = json_decode($response->getBody(), true);
echo "Email sent: " . $result['data']['id'] . "\n";

Send an Email

$zyphr = new ZyphrClient(getenv('ZYPHR_API_KEY'));

$result = $zyphr->request('POST', '/emails', [
    'to' => 'user@example.com',
    'subject' => 'Welcome!',
    'html' => '<h1>Hello from PHP!</h1>',
    'text' => 'Hello from PHP!',
    'tags' => ['welcome', 'onboarding'],
]);

echo "Email ID: " . $result['data']['id'] . "\n";

Send with a Template

$result = $zyphr->request('POST', '/emails', [
    'to' => 'user@example.com',
    'template_id' => 'welcome-email',
    'template_data' => [
        'name' => 'John',
        'action_url' => 'https://yourapp.com/activate',
    ],
]);

Send a Push Notification

$result = $zyphr->request('POST', '/push', [
    'user_id' => 'user_123',
    'title' => 'New Message',
    'body' => 'You have a new message',
    'data' => [
        'message_id' => 'msg_456',
    ],
]);

Send an SMS

$result = $zyphr->request('POST', '/sms', [
    'to' => '+14155551234',
    'body' => 'Your verification code is 123456',
]);

echo "SMS ID: " . $result['data']['id'] . "\n";

Send an In-App Notification

$result = $zyphr->request('POST', '/inbox', [
    'subscriber_id' => 'user_123',
    'title' => 'New Comment',
    'body' => 'John commented on your post',
    'action_url' => '/posts/123#comments',
    'category' => 'comments',
]);

Create a Subscriber

$result = $zyphr->request('POST', '/subscribers', [
    'external_id' => 'user_123',
    'email' => 'user@example.com',
    'phone' => '+14155551234',
    'name' => 'John Doe',
    'metadata' => [
        'plan' => 'pro',
    ],
]);

List with Pagination

$result = $zyphr->request('GET', '/emails?page=1&per_page=25&status=delivered');

echo "Page {$result['meta']['page']} of {$result['meta']['total_pages']}\n";
echo "Total: {$result['meta']['total']}\n";

foreach ($result['data'] as $email) {
    echo "- {$email['id']}: {$email['subject']} ({$email['status']})\n";
}

Error Handling

try {
    $result = $zyphr->request('POST', '/emails', [
        'to' => 'invalid-email',
        'subject' => 'Test',
        'html' => '<p>Hi</p>',
    ]);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

For structured error handling with the cURL client:

public function request(string $method, string $path, ?array $body = null): array
{
    // ... same as above, but with detailed error handling:

    if ($statusCode >= 400) {
        $code = $data['error']['code'] ?? 'unknown';

        switch ($code) {
            case 'rate_limited':
                $retryAfter = $data['error']['details']['retry_after'] ?? 60;
                sleep($retryAfter);
                return $this->request($method, $path, $body); // Retry
            case 'validation_error':
                throw new InvalidArgumentException($data['error']['message']);
            case 'unauthorized':
                throw new RuntimeException('Invalid API key');
            default:
                throw new Exception("API error ({$statusCode}): " . $data['error']['message']);
        }
    }

    return $data;
}

Laravel Integration

For Laravel projects, configure the client in a service provider:

// app/Providers/AppServiceProvider.php
use App\Services\ZyphrClient;

public function register(): void
{
    $this->app->singleton(ZyphrClient::class, function () {
        return new ZyphrClient(config('services.zyphr.key'));
    });
}

// config/services.php
'zyphr' => [
    'key' => env('ZYPHR_API_KEY'),
],

// Usage in a controller
class NotificationController extends Controller
{
    public function __construct(private ZyphrClient $zyphr) {}

    public function sendWelcome(Request $request)
    {
        $this->zyphr->request('POST', '/emails', [
            'to' => $request->user()->email,
            'template_id' => 'welcome-email',
            'template_data' => ['name' => $request->user()->name],
        ]);

        return response()->json(['message' => 'Sent']);
    }
}

Requirements

• PHP 8.1 or later
• cURL extension (included in most PHP installations)
• Guzzle 7.x (optional)