README

PHP SDK for VaultSens. API key + secret authentication with file upload, folder management, and image transform helpers.

Install

composer require vaultsens/sdk

Quick start

use VaultSens\VaultSensClient;

$client = new VaultSensClient(
    'https://api.vaultsens.com',
    'your-api-key',
    'your-api-secret'
);

$result = $client->uploadFile('./photo.png', 'hero', 'low', null, 'photo.png', 'image/png');
echo $result['data']['_id'];  // file ID
echo $result['data']['url'];  // public URL

API reference

new VaultSensClient(baseUrl, apiKey, apiSecret)

Use setAuth($apiKey, $apiSecret) to set credentials after construction.

Files

uploadFile($filePath, $name = null, $compression = null, $folderId = null, $filename = null, $mimeType = null)

Upload a single file.

$result = $client->uploadFile(
    './photo.png',
    'my-image',   // optional display name stored with the file
    'medium',     // optional compression level applied server-side
    'folder-id',  // optional folder to place the file in
    'photo.png',  // optional multipart filename sent to VaultSens
    'image/png'   // optional explicit MIME type
);

Parameters

uploadFiles(array $filePaths, $name = null, $compression = null, $folderId = null, $filenames = null, $mimeTypes = null)

Upload multiple files in one request. Accepts the same parameters as uploadFile.

$result = $client->uploadFiles(
    ['./a.png', './b.jpg'],
    null,
    'low',
    'folder-id',
    ['a.png', 'b.jpg'],
    ['image/png', 'image/jpeg']
);

listFiles($folderId = null)

List all files. Pass $folderId to filter by folder, or "root" for files not in any folder.

$all     = $client->listFiles();
$inDir   = $client->listFiles('folder-id');
$atRoot  = $client->listFiles('root');

getFileMetadata($fileId)

$meta = $client->getFileMetadata('file-id');

updateFile($fileId, $filePath, $name = null, $compression = null, $filename = null, $mimeType = null)

Replace a file's content. Accepts $name and $compression — $folderId is not supported (file stays in its current folder).

$client->updateFile('file-id', './new-photo.png', null, 'high', 'new-photo.png', 'image/png');

deleteFile($fileId)

$client->deleteFile('file-id');

buildFileUrl($fileId, array $options = [])

Build a URL for dynamic image transforms. No network request is made.

$url = $client->buildFileUrl('file-id', [
    'width'   => 800,
    'height'  => 600,
    'format'  => 'webp',
    'quality' => 80,
]);

Transform options

Folders

listFolders()

$result  = $client->listFolders();
$folders = $result['data'];

createFolder($name, $parentId = null)

$result   = $client->createFolder('Marketing');
$folderId = $result['data']['_id'];

// nested folder
$client->createFolder('2024', $folderId);

renameFolder($folderId, $name)

$client->renameFolder('folder-id', 'New Name');

deleteFolder($folderId)

Deletes the folder and moves all its files back to root.

$client->deleteFolder('folder-id');

Metrics

$result = $client->getMetrics();
$data   = $result['data'];
// $data['totalFiles'], $data['totalStorageBytes'], $data['storageUsedPercent'], ...

Error handling

All API errors throw a VaultSensError with an $errorCode, HTTP status code, and message.

use VaultSens\VaultSensError;

try {
    $client->uploadFile('./photo.png');
} catch (VaultSensError $e) {
    echo $e->getMessage();   // human-readable message
    echo $e->getCode();      // HTTP status code
    echo $e->errorCode;      // machine-readable error code

    switch ($e->errorCode) {
        case VaultSensError::FILE_TOO_LARGE:
            echo 'File exceeds your plan limit';
            break;
        case VaultSensError::STORAGE_LIMIT:
            echo 'Storage quota exceeded';
            break;
        case VaultSensError::MIME_TYPE_NOT_ALLOWED:
            echo 'File type not allowed on your plan';
            break;
        case VaultSensError::COMPRESSION_NOT_ALLOWED:
            echo 'Compression level not permitted on your plan';
            break;
        case VaultSensError::FILE_COUNT_LIMIT:
            echo 'File count limit reached';
            break;
        case VaultSensError::FOLDER_COUNT_LIMIT:
            echo 'Folder count limit reached';
            break;
        case VaultSensError::SUBSCRIPTION_INACTIVE:
            echo 'Subscription is not active';
            break;
    }
}

Error codes

License

MIT