> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Official Zavu SDK for PHP

<Warning>
  **Server-side only** — This SDK is designed for server-side environments (Laravel, Symfony, PHP scripts). Never use it in browser/frontend code as this exposes your API key. See [Frontend Integration](/authentication#frontend-integration) for the proxy pattern.
</Warning>

The official Zavu SDK for PHP provides a clean interface to the Zavu API with full type support.

## Installation

```bash theme={null}
composer require zavudev/sdk
```

## Requirements

* PHP 8.1 or higher
* Composer

## Quick Start

```php theme={null}
<?php

use Zavudev\Client;

$client = new Client(
    apiKey: getenv('ZAVUDEV_API_KEY')
);

$result = $client->messages->send([
    'to' => '+14155551234',
    'text' => 'Hello from Zavu!',
]);

echo "Message sent: " . $result->message->id . "\n";
```

## Configuration

### Initialize the Client

```php theme={null}
use Zavudev\Client;

// Basic initialization
$client = new Client(
    apiKey: getenv('ZAVUDEV_API_KEY')
);

// With custom base URL
$client = new Client(
    apiKey: 'zv_live_xxx',
    baseURL: 'https://api.zavu.dev'
);
```

### Environment Variables

We recommend storing your API key in environment variables:

```php theme={null}
$client = new Client(
    apiKey: getenv('ZAVUDEV_API_KEY')
);
```

## Accessing Response Headers

Use `->withRawResponse()` to access the full HTTP response including headers:

```php theme={null}
$response = $client->messages->withRawResponse()->send([
    'to' => '+14155551234',
    'text' => 'Hello!',
]);

$remaining = $response->headers['X-RateLimit-Remaining'];
echo "Remaining requests: $remaining\n";

$result = $response->parse();
echo "Message ID: " . $result->message->id . "\n";
```

## Error Handling

```php theme={null}
use Zavudev\Client;
use Zavudev\APIError;
use Zavudev\ZavudevError;

$client = new Client(
    apiKey: getenv('ZAVUDEV_API_KEY')
);

try {
    $client->messages->send([
        'to' => 'invalid-number',
        'text' => 'Hello',
    ]);
} catch (APIError $e) {
    echo "Status: " . $e->status . "\n";
    echo "Message: " . $e->getMessage() . "\n";
} catch (ZavudevError $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
```

### Error Types

| Error Code | Description                |
| ---------- | -------------------------- |
| `400`      | Invalid request parameters |
| `401`      | Invalid or missing API key |
| `403`      | Insufficient permissions   |
| `404`      | Resource not found         |
| `429`      | Rate limit exceeded        |

## Retries

The SDK supports automatic retries with configurable backoff:

```php theme={null}
$client = new Client(
    apiKey: 'zv_live_xxx',
    maxRetries: 3
);

$result = $client->messages->send([
    'to' => '+14155551234',
    'text' => 'Hello!',
]);
```

## Laravel Integration

For Laravel applications, set your API key in `.env`:

```
ZAVUDEV_API_KEY=zv_live_xxx
```

Use the SDK in your controllers or services:

```php theme={null}
use Zavudev\Client;

class MessageController extends Controller
{
    private Client $zavu;

    public function __construct()
    {
        $this->zavu = new Client(
            apiKey: config('services.zavu.key')
        );
    }

    public function send(Request $request)
    {
        $result = $this->zavu->messages->send([
            'to' => $request->input('to'),
            'text' => $request->input('text'),
        ]);

        return response()->json(['messageId' => $result->message->id]);
    }
}
```

## Symfony Integration

For Symfony applications, configure the API key as a parameter:

```yaml theme={null}
# config/services.yaml
parameters:
    zavudev_api_key: '%env(ZAVUDEV_API_KEY)%'
```

```php theme={null}
use Zavudev\Client;

class MessageService
{
    private Client $zavu;

    public function __construct(string $zavudevApiKey)
    {
        $this->zavu = new Client(
            apiKey: $zavudevApiKey
        );
    }

    public function send(string $to, string $text): string
    {
        $result = $this->zavu->messages->send([
            'to' => $to,
            'text' => $text,
        ]);

        return $result->message->id;
    }
}
```