Composer installation
Install the published package from Packagist and run it on PHP 8.1+ with the bundled Guzzle-based HTTP transport or your own compatible client.
SDK library
Browse the docs by language.
Python, TypeScript, and PHP are live now. Each route documents the same Dilnaka upload lifecycle in the conventions of its own runtime.
Python SDK
Environment-driven setup, direct-to-S3 uploads, and the current Python reference implementation.
TypeScript SDK
Node 18+ uploads, typed file helpers, and fetch injection for tests or custom runtimes.
PHP SDK
Composer installation, PHP 8.1+, Guzzle transport, and the same Dilnaka file lifecycle.
Rust SDK
Async Rust uploads, strongly typed responses, multipart streaming, and structured errors.
Documentation
Dilnaka PHP SDK
PHP SDK for uploading files through the Dilnaka Upload API. The client resolves configuration from constructor options first, then environment variables, then .env, requests a presigned upload URL from your Dilnaka backend, uploads directly to S3, and finally completes the file record.
Direct-to-S3 upload
The SDK reads the local file path, creates a presigned upload with your Dilnaka backend, uploads to S3, and then completes the file record.
Shared backend contract
The PHP client hits the same upload, file lookup, access URL, and delete endpoints as the Python and TypeScript SDKs.
Setup
Install from Composer
Install the published Dilnaka package from Packagist. The package targets PHP 8.1+, uses PSR-4 autoloading, and ships a Guzzle-based transport by default.
Package: packagist.org/packages/dilnaka/dilnaka
bash
composer require dilnaka/dilnakaMinimum runtime: PHP 8.1+. The default dependencies include guzzlehttp/guzzle and vlucas/phpdotenv.
Configuration
Configure .env
The SDK only needs your API key in .env. It is built specifically for Dilnaka Storage.
Required .env
DILNAKA_API_KEY=dlk_dev_your_api_key_hereOptional .env override
DILNAKA_TIMEOUT=60
DILNAKA_MULTIPART_THRESHOLD=104857600
DILNAKA_UPLOAD_TIMEOUT=300Optional: set DILNAKA_TIMEOUT (default 60) for the JSON API request timeout in seconds.
Set DILNAKA_MULTIPART_THRESHOLD (default 104857600, i.e. 100 MB) to control when uploads switch to the multipart flow.
Set DILNAKA_UPLOAD_TIMEOUT (default 300) for the per-part transfer timeout in seconds. It is intentionally larger than the API timeout so large chunks over slow links do not time out.
Core flow
Basic upload
Instantiate the client with defaults and upload a local file path with one method call.
php
upload('./test-upload.txt');
echo $uploaded->id . PHP_EOL;
echo $uploaded->key . PHP_EOL;
echo $uploaded->status . PHP_EOL;Alternate setup
Explicit configuration
Pass constructor options directly when you want to avoid environment files, change the timeout, or inject a custom HTTP client implementation.
php
'dlk_dev_your_api_key_here',
'timeout' => 60,
]);
$uploaded = $client->upload('./avatar.png', [
'folder' => 'avatars',
'metadata' => ['source' => 'profile-settings'],
]);
var_dump($uploaded);Large files
Large file uploads
The same upload() call handles files of any size. Small files use a single presigned PUT. Files at or above the multipart threshold (100 MB by default) automatically switch to a resumable S3 multipart upload that streams the file in chunks and retries a failed part instead of discarding the whole transfer.
php
upload('./course-bundle.zip');
// Tune per call: force multipart above 25 MB and allow 10 minutes per part.
$uploaded = $client->upload('./course-bundle.zip', [
'multipartThreshold' => 25 * 1024 * 1024,
'uploadTimeout' => 600,
]);
echo $uploaded->id . ' ' . $uploaded->status . PHP_EOL;The multipart flow streams the file from disk one part at a time, so memory stays flat even for multi-gigabyte uploads. Each part is retried with a fresh presigned URL if it fails, and a transfer that cannot finish is aborted automatically so it never leaves a dangling upload on the bucket.
For direct control, the lower-level methods are also available:
createMultipartUpload(...)starts the upload and returns the part layout.presignMultipartParts($fileId, $partNumbers)returns presigned PUT URLs per part.completeMultipartUpload($fileId, $parts)finalizes the upload from part ETags.abortMultipartUpload($fileId)cancels an in-progress upload.
Python-style aliases (create_multipart_upload, presign_multipart_parts, and related) are shipped as well.
Read access
Request file access URLs
Use getFileAccessUrl($fileId, $expiresIn = null) when your app needs a temporary download or preview URL.
php
getFileAccessUrl('file_123', 600);
echo $access->fileId . PHP_EOL;
echo $access->url . PHP_EOL;
echo $access->expiresIn . PHP_EOL;
echo $access->isTemporary ? 'temporary' : 'permanent';If you omit expiresIn, the SDK requests the default access URL returned by your backend. The method rejects values less than or equal to zero.
API surface
Available methods
php
$client = new Dilnaka([
'apiKey' => 'dlk_dev_your_api_key_here',
'timeout' => 60,
'envFile' => __DIR__ . '/.env',
'httpClient' => $customHttpClient,
]);
$client->upload($filePath, $options = []);
$client->createPresignedUpload($filename, $contentType, $size, $folder = 'uploads', $metadata = null);
$client->completeUpload($fileId);
$client->createMultipartUpload($filename, $contentType, $size, $folder = 'uploads', $metadata = null);
$client->presignMultipartParts($fileId, $partNumbers);
$client->completeMultipartUpload($fileId, $parts);
$client->abortMultipartUpload($fileId);
$client->listFiles();
$client->getFile($fileId);
$client->getFileAccessUrl($fileId, $expiresIn = null);
$client->deleteFile($fileId);Primary names
Use the camelCase methods in normal PHP code: createPresignedUpload, getFileAccessUrl, and the other typed helpers.
Migration aliases
Python-style aliases are also shipped for migration convenience: list_files(), get_file(), and related helpers.
Backend contract
Expected backend endpoints
The PHP SDK uses the same Caspian endpoints as the Python and TypeScript SDKs.
txt
POST /v1/uploads/presign
POST /v1/uploads/complete
POST /v1/uploads/multipart/create
POST /v1/uploads/multipart/parts
POST /v1/uploads/multipart/complete
POST /v1/uploads/multipart/abort
GET /v1/files
GET /v1/files/{file_id}
GET /v1/files/{file_id}/access-url?expiresIn=1200
DELETE /v1/files/{file_id}When you pass expiresIn to getFileAccessUrl, the SDK appends it as a query parameter on the access URL endpoint.
API payloads
Presign and complete response shapes
json: presign response
{
"fileId": "clx_file_id",
"fileKey": "uploads/2026/05/clx_file_id-test.txt",
"uploadUrl": "https://s3-presigned-url",
"expiresIn": 300,
"method": "PUT",
"headers": {
"Content-Type": "text/plain"
}
}json: complete response
{
"fileId": "clx_file_id",
"status": "uploaded",
"key": "uploads/2026/05/clx_file_id-test.txt",
"originalName": "test.txt",
"contentType": "text/plain",
"size": 94,
"publicUrl": null
}json: access-url response
{
"fileId": "clx_file_id",
"url": "https://s3-presigned-url",
"expiresIn": 1200,
"isTemporary": true
}Examples
Common usage patterns
Temporary file access URL
getFileAccessUrl(
'maext0cfjsquw2mu9o597fb9',
1200,
);
echo $access->url . PHP_EOL;
echo $access->expiresIn . PHP_EOL;Delete file
deleteFile($fileId);
var_dump($result);Upload file
upload('./test-upload.txt', [
'folder' => 'uploads',
]);
echo "Uploaded file:" . PHP_EOL;
echo " id: {$uploaded->id}" . PHP_EOL;
echo " key: {$uploaded->key}" . PHP_EOL;
echo " status: {$uploaded->status}" . PHP_EOL;
echo " size: {$uploaded->size}" . PHP_EOL;
echo " contentType: {$uploaded->contentType}" . PHP_EOL;Large file upload
upload('./course-bundle.zip', [
'folder' => 'courses',
'uploadTimeout' => 600,
]);
echo $uploaded->id . ' ' . $uploaded->status . ' ' . $uploaded->size . PHP_EOL;File list
listFiles() as $file) {
echo $file->id . ' | ' . $file->status . ' | ' . $file->key . PHP_EOL;
}Security
Security model
The SDK never receives AWS credentials. It only receives a temporary presigned upload URL from your Dilnaka backend.
Your backend remains responsible for API key validation, scope checking, file validation, S3 key generation, metadata persistence, upload completion verification, and temporary read URL expiration.