Dilnaka | PHP SDK

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/dilnaka

Minimum 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_here

Optional .env override

DILNAKA_TIMEOUT=60

Optional: set DILNAKA_TIMEOUT if you want a custom request timeout.

Core flow

Basic upload

Instantiate the client with defaults and upload a local file path with one method call.

php

<?php

require __DIR__ . '/vendor/autoload.php';

use Dilnaka\Dilnaka;

$client = new Dilnaka();

$uploaded = $client->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

<?php

use Dilnaka\Dilnaka;

$client = new Dilnaka([
    'apiKey' => 'dlk_dev_your_api_key_here',
    'timeout' => 60,
]);

$uploaded = $client->upload('./avatar.png', [
    'folder' => 'avatars',
    'metadata' => ['source' => 'profile-settings'],
]);

var_dump($uploaded);

Read access

Request file access URLs

Use getFileAccessUrl($fileId, $expiresIn = null) when your app needs a temporary download or preview URL.

php

<?php

use Dilnaka\Dilnaka;

$client = new Dilnaka();

$access = $client->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->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
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

<?php

use Dilnaka\Dilnaka;

$client = new Dilnaka();

$access = $client->getFileAccessUrl(
    'maext0cfjsquw2mu9o597fb9',
    1200,
);

echo $access->url . PHP_EOL;
echo $access->expiresIn . PHP_EOL;

Delete file

<?php

use Dilnaka\Dilnaka;

$client = new Dilnaka();

$fileId = 'maext0cfjsquw2mu9o597fb9';
$result = $client->deleteFile($fileId);

var_dump($result);

Upload file

<?php

use Dilnaka\Dilnaka;

$client = new Dilnaka();

$uploaded = $client->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;

File list

<?php

use Dilnaka\Dilnaka;

$client = new Dilnaka();

foreach ($client->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.

Browse the docs by language.

Python SDK

TypeScript SDK

PHP SDK

Dilnaka PHP SDK

Composer installation

Direct-to-S3 upload

Shared backend contract