# DocFast PHP SDK

Official PHP client for the [DocFast](https://docfast.dev) HTML/Markdown to PDF API.

## Requirements

- PHP 8.1+
- ext-curl
- ext-json

## Installation

```bash
composer require docfast/docfast-php
```

## Quick Start

```php
use DocFast\Client;

$client = new Client('df_pro_your_api_key');

// HTML to PDF
$pdf = $client->html('<h1>Hello World</h1>');
file_put_contents('output.pdf', $pdf);
```

## Usage

### HTML to PDF

```php
$pdf = $client->html('<h1>Hello</h1><p>My document</p>');
```

### HTML with CSS

```php
$pdf = $client->html(
    '<h1>Styled</h1>',
    'h1 { color: navy; font-family: Georgia; }'
);
```

### HTML with PDF Options

```php
use DocFast\PdfOptions;

$options = new PdfOptions();
$options->format = 'Letter';
$options->landscape = true;
$options->margin = ['top' => '20mm', 'bottom' => '20mm', 'left' => '15mm', 'right' => '15mm'];
$options->printBackground = true;

$pdf = $client->html('<h1>Report</h1>', null, $options);
```

### Markdown to PDF

```php
$pdf = $client->markdown('# Hello World\n\nThis is **bold** text.');
```

### URL to PDF

```php
$pdf = $client->url('https://example.com');
```

### Headers and Footers

```php
$options = new PdfOptions();
$options->displayHeaderFooter = true;
$options->headerTemplate = '<div style="font-size:10px;text-align:center;width:100%">My Document</div>';
$options->footerTemplate = '<div style="font-size:10px;text-align:center;width:100%">Page <span class="pageNumber"></span>/<span class="totalPages"></span></div>';
$options->margin = ['top' => '40mm', 'bottom' => '20mm'];

$pdf = $client->html($html, null, $options);
```

### Custom Page Size

```php
$options = new PdfOptions();
$options->width = '8.5in';
$options->height = '11in';
$options->scale = 0.8;

$pdf = $client->html($html, null, $options);
```

### Templates

```php
// List templates
$templates = $client->templates();

// Render a template
$pdf = $client->renderTemplate('invoice', [
    'company' => 'Acme Corp',
    'items' => [['name' => 'Widget', 'price' => 9.99]],
]);
```

## PDF Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `format` | string | `"A4"` | Page size: A4, Letter, Legal, A3, A5, Tabloid |
| `landscape` | bool | `false` | Landscape orientation |
| `margin` | array | `null` | Margins with top/bottom/left/right keys (CSS units) |
| `printBackground` | bool | `true` | Print background graphics |
| `filename` | string | `null` | Suggested filename |
| `headerTemplate` | string | `null` | HTML header template |
| `footerTemplate` | string | `null` | HTML footer template |
| `displayHeaderFooter` | bool | `false` | Show header/footer |
| `scale` | float | `1` | Rendering scale (0.1–2.0) |
| `pageRanges` | string | `null` | Pages to print (e.g. "1-3,5") |
| `preferCSSPageSize` | bool | `false` | Prefer CSS @page size |
| `width` | string | `null` | Custom paper width |
| `height` | string | `null` | Custom paper height |

## Error Handling

```php
use DocFast\DocFastException;

try {
    $pdf = $client->html('<h1>Test</h1>');
} catch (DocFastException $e) {
    echo "Error: {$e->getMessage()} (status: {$e->statusCode})\n";
}
```

## Configuration

```php
// Custom base URL
$client = new Client('key', 'https://staging.docfast.dev');

// Custom timeout (seconds)
$client = new Client('key', 'https://docfast.dev', 120);
```

## Laravel Integration

See the [DocFast Laravel package](../laravel/) for a dedicated Laravel integration with facades, config, and service provider.

## Links

- [Documentation](https://docfast.dev/docs)
- [API Reference](https://docfast.dev/openapi.json)
- [Get an API Key](https://docfast.dev)