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)`

Parameter	Type	Description
`$baseUrl`	`string`	Your VaultSens API base URL
`$apiKey`	`string\|null`	API key
`$apiSecret`	`string\|null`	API secret

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

Parameter	Type	Description
`$filePath`	`string`	Path to the file on disk
`$name`	`string\|null`	Display name stored with the file
`$compression`	`string\|null`	Server-side compression: `'none'` \| `'low'` \| `'medium'` \| `'high'`. Must be allowed by your plan
`$folderId`	`string\|null`	ID of the folder to place the file in. Omit for root
`$filename`	`string\|null`	Multipart filename to send. Defaults to `basename($filePath)`
`$mimeType`	`string\|null`	Explicit MIME type. If omitted, the SDK detects from the file or falls back to the filename extension

`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

Key	Type	Description
`width`	`int?`	Output width in pixels
`height`	`int?`	Output height in pixels (fit: inside, aspect ratio preserved)
`format`	`string?`	Output format e.g. `'webp'`, `'jpeg'`, `'png'`
`quality`	`int?`	Compression quality `1–100`

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

Constant	Status	Description
`FILE_TOO_LARGE`	413	File exceeds plan's `maxFileSizeBytes`
`STORAGE_LIMIT`	413	Total storage quota exceeded
`FILE_COUNT_LIMIT`	403	Plan's `maxFilesCount` reached
`MIME_TYPE_NOT_ALLOWED`	415	File type blocked by plan
`COMPRESSION_NOT_ALLOWED`	403	Compression level not permitted by plan
`SUBSCRIPTION_INACTIVE`	402	User subscription is not active
`FOLDER_COUNT_LIMIT`	403	Plan's `maxFoldersCount` reached
`EMAIL_ALREADY_REGISTERED`	400	Duplicate email on register
`EMAIL_NOT_VERIFIED`	403	Login attempted before verifying email
`INVALID_CREDENTIALS`	400	Wrong email or password
`INVALID_OTP`	400	Bad or expired verification code
`UNAUTHORIZED`	401	Missing or invalid credentials
`NOT_FOUND`	404	Resource not found
`UNKNOWN`	—	Any other error

License

MIT

fluxsave / sdk

Maintainers

Package info

Statistics

Security