#PHP SDK

The Pixault PHP SDK provides image URL construction, uploads, and management. Available as pixault/pixault-php on Packagist.

Source on GitHub

#Installation

composer require pixault/pixault-php

Requires PHP 8.1+ and the curl extension.

#Configuration

use Pixault\Pixault;
$pixault = new Pixault([
    'client_id'     => 'px_cl_your_client_id',
    'client_secret' => 'pk_your_secret_key',
    'base_url'      => 'https://img.pixault.io',  // optional default
    'project'        => 'myapp',
]);

#URL Builder

Generate transform URLs without making HTTP requests:

$url = $pixault->url('img_01JKXYZ')
    ->width(800)
    ->height(600)
    ->fit('cover')
    ->quality(85)
    ->format('webp')
    ->build();
// → "https://img.pixault.io/myapp/img_01JKXYZ/w_800,h_600,fit_cover,q_85.webp"

#Methods

#Named Transforms

$url = $pixault->url('img_01JKXYZ')
    ->transform('thumbnail')
    ->format('webp')
    ->build();

#Upload

// Upload from file path
$image = $pixault->upload('/path/to/photo.jpg', [
    'alt'  => 'Team photo',
    'tags' => ['team', 'retreat'],
]);
echo $image['id'];   // "img_01JKXYZ123"
echo $image['url'];  // "https://img.pixault.io/myapp/img_01JKXYZ123/original.jpg"
// Upload from stream
$stream = fopen('/path/to/photo.jpg', 'r');
$image = $pixault->uploadStream($stream, 'photo.jpg', [
    'alt' => 'Uploaded via stream',
]);

#Image Management

// List images
$result = $pixault->listImages(['limit' => 20, 'tag' => 'nature']);
foreach ($result['images'] as $image) {
    echo $image['id'] . ': ' . $image['alt'] . "\n";
}
// Get metadata
$metadata = $pixault->getImage('img_01JKXYZ');
// Update metadata
$pixault->updateImage('img_01JKXYZ', [
    'alt'  => 'Updated description',
    'tags' => ['updated', 'tags'],
]);
// Delete
$pixault->deleteImage('img_01JKXYZ');

#List & Search Images

// List all images
$result = $pixault->listImages('my-project');
// Search by text
$matches = $pixault->listImages('my-project', ['search' => 'hero']);
// Filter by category
$tattoos = $pixault->listImages('my-project', ['category' => 'tattoo-flash']);
// Paginate
$page2 = $pixault->listImages('my-project', [], 50, $result['nextCursor']);

#Folder Management

// List folders
$folders = $client->listFolders();
// Create a folder
$client->createFolder('portfolio/landscapes');
// Delete a folder
$client->deleteFolder('portfolio/landscapes');
// List images in a specific folder
$result = $client->listImages(['folder' => 'portfolio/landscapes']);

#Named Transforms

// Create
$pixault->createTransform('thumbnail', [
    'parameters' => ['w' => 200, 'h' => 200, 'fit' => 'cover'],
    'locked'     => ['w', 'h', 'fit'],
]);
// List
$transforms = $pixault->listTransforms();

#Laravel Integration

// config/services.php
'pixault' => [
    'client_id'     => env('PIXAULT_CLIENT_ID'),
    'client_secret' => env('PIXAULT_CLIENT_SECRET'),
    'project'        => env('PIXAULT_PROJECT', 'default'),
],
// AppServiceProvider
$this->app->singleton(Pixault::class, function () {
    return new Pixault(config('services.pixault'));
});
// In a controller
public function upload(Request $request, Pixault $pixault)
{
    $file = $request->file('image');
    $image = $pixault->upload($file->getRealPath(), [
        'alt' => $request->input('alt'),
    ]);
    return response()->json($image, 201);
}

#Error Handling

use Pixault\Exceptions\PixaultApiException;
use Pixault\Exceptions\QuotaExceededException;
use Pixault\Exceptions\RateLimitException;
try {
    $pixault->upload('/path/to/photo.jpg');
} catch (QuotaExceededException $e) {
    echo "Storage quota exceeded: " . $e->getMessage();
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->retryAfter} seconds";
} catch (PixaultApiException $e) {
    echo "API error ({$e->getCode()}): {$e->getMessage()}";
}

#WordPress Integration

See the WordPress Integration Guide for using Pixault as a media library replacement.