README

Trawbit OSS PHP SDK (`trawbit/oss`)

The official, beginner-friendly PHP SDK & Laravel integration for Trawbit OSS (Object Storage Service).
Store files, create buckets, generate secure expiring download links, and manage object versions with just a few lines of code.

📖 Table of Contents

What is Trawbit OSS?
Prerequisites
Step 1: Get Your API Keys
Step 2: Installation
Beginner Quickstart: Pure PHP
Beginner Quickstart: Laravel Framework
Step-by-Step Practical Tutorials
Error Handling Made Simple
Complete API Cheatsheet
Need Help?

🌟 What is Trawbit OSS?

Trawbit OSS (Object Storage Service) is a cloud storage platform where you can store files (images, videos, PDFs, backups) and access them through high-speed cloud URLs or secure private APIs.

With this SDK, you don't need to write complex HTTP requests. You can upload and download files in PHP with simple, intuitive functions.

📋 Prerequisites

PHP 8.1 or higher installed on your machine or server.
Composer package manager installed.
A free account on Trawbit OSS.

🔑 Step 1: Get Your API Keys

Before writing code, you need your API Key credentials:

Log in to your dashboard at oss.trawbit.app.
Go to Security > API Keys in the sidebar.
Click Create API Key.
Copy your Key ID (pk_live_...) and Secret Key (psk_live_...).

⚠️ Security Tip: Never share your secret key or commit it directly into public Git repositories. Always use environment variables (.env).

📦 Step 2: Installation

Open your terminal in your project root directory and run:

composer require trawbit/oss

🚀 Beginner Quickstart: Pure PHP

Here is the shortest, complete working script to upload a file in standard PHP:

<?php

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

use Trawbit\Storage\TrawbitClient;
use Trawbit\Storage\Exceptions\TrawbitException;

// 1. Connect to Trawbit OSS
$client = new TrawbitClient(
    keyId: 'pk_live_your_key_id',
    secretKey: 'psk_live_your_secret_key'
);

try {
    // 2. Upload a file to your bucket
    $response = $client->upload(
        bucket: 'my-bucket',
        file: __DIR__ . '/photo.jpg',
        prefix: 'uploads/2026',
        visibility: 'public'
    );

    echo "✅ File uploaded successfully!\n";
    echo "Public URL: " . $response['object']['public_url'] . "\n";

} catch (TrawbitException $e) {
    echo "❌ Upload failed: " . $e->getMessage() . "\n";
}

⚡ Beginner Quickstart: Laravel Framework

If you are using Laravel (10, 11, or 12), setup takes less than 60 seconds.

1. Publish the Configuration File

Run this Artisan command:

php artisan vendor:publish --tag=trawbit-config

This creates a new file at config/trawbit.php.

2. Add Credentials to your `.env` File

Open your .env file and add:

TRAWBIT_KEY_ID=pk_live_your_key_id
TRAWBIT_SECRET_KEY=psk_live_your_secret_key
TRAWBIT_DEFAULT_BUCKET=my-bucket

3. Use in Any Controller or Route

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Trawbit\Storage\Laravel\Facades\TrawbitStorage;

class ProfileController extends Controller
{
    public function uploadAvatar(Request $request)
    {
        $request->validate([
            'avatar' => 'required|image|max:10240', // Max 10MB
        ]);

        // Upload the incoming HTTP file directly
        $result = TrawbitStorage::upload(
            bucket: 'user-avatars',
            file: $request->file('avatar')->getRealPath(),
            prefix: 'avatars/' . auth()->id(),
            visibility: 'public'
        );

        $avatarUrl = $result['object']['public_url'];

        // Save URL to user in database
        auth()->user()->update(['avatar_url' => $avatarUrl]);

        return back()->with('success', 'Avatar updated!');
    }
}

💡 Step-by-Step Practical Tutorials

1. Upload an Image or File

// Upload a local file (supports files up to 500MB)
$result = $client->upload(
    bucket: 'customer-assets',
    file: '/path/to/document.pdf',
    prefix: 'documents/2026',        // Optional folder
    visibility: 'private',           // 'private' (default) or 'public'
    metadata: ['user_id' => 42]      // Optional custom info
);

echo "Saved key: " . $result['object']['key']; 
// Output: documents/2026/document.pdf

2. Create a Temporary Expiring Download Link

If your bucket or file is private, you can generate a secure temporary link (like for paid invoices or private customer files) that expires automatically:

// Generate a link valid for 30 minutes
$presigned = $client->generatePresignedUrl(
    bucket: 'customer-assets',
    key: 'documents/2026/document.pdf',
    expiresInMinutes: 30
);

echo "Expiring Download Link: " . $presigned['url'];
// User can click this link to download the private file for the next 30 minutes!

3. Save Text or CSV Content Directly (Without Saving to Disk)

If you generate a report, JSON file, or CSV dynamically in memory:

$csvData = "Order ID,Customer,Total\n#101,John Doe,$50.00\n#102,Jane Smith,$120.00";

$client->putContent(
    bucket: 'reports-bucket',
    content: $csvData,
    filename: 'orders-today.csv',
    prefix: 'exports/daily',
    visibility: 'private'
);

echo "CSV Report stored in cloud!";

4. Download a File to Your Server

// Option A: Download raw content into a PHP variable
$fileData = $client->download('my-bucket', 'reports/orders.csv');

// Option B: Stream directly into a file on your disk
$client->downloadToFile(
    bucket: 'my-bucket',
    key: 'reports/orders.csv',
    destinationFilePath: '/local/path/saved-orders.csv'
);

5. Copy, Move, or Delete Files

// Copy a file (fast server-side copy without downloading)
$client->copyObject(
    sourceBucket: 'my-bucket',
    sourceKey: 'photos/photo.png',
    destinationKey: 'backups/photo-backup.png'
);

// Move or rename a file
$client->moveObject(
    bucket: 'my-bucket',
    sourceKey: 'photos/photo.png',
    destinationKey: 'photos/new-name.png'
);

// Delete a file
$client->deleteObject('my-bucket', 'photos/new-name.png');

🛡️ Error Handling Made Simple

When an error occurs (such as an invalid key, missing file, or exceeded quota), the SDK throws a TrawbitException. You can catch it easily to display user-friendly error messages:

use Trawbit\Storage\Exceptions\TrawbitException;

try {
    $client->upload('my-bucket', '/path/to/file.png');
} catch (TrawbitException $e) {
    // 1. Human readable message
    echo "Error: " . $e->getMessage() . "\n";

    // 2. HTTP Status Code (e.g. 401, 403, 404, 422)
    echo "HTTP Status: " . $e->getStatusCode() . "\n";

    // 3. Error Code identifier (e.g. UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR)
    echo "Error Code: " . $e->getErrorCode() . "\n";

    // 4. Form validation errors (if any)
    if ($e->hasValidationErrors()) {
        foreach ($e->getValidationErrors() as $field => $messages) {
            echo "Field '{$field}': " . implode(', ', $messages) . "\n";
        }
    }
}

📋 Complete API Cheatsheet

Task	Pure PHP Method	Laravel Facade Method
Get Account Info	`$client->getProfile()`	`TrawbitStorage::getProfile()`
List Buckets	`$client->listBuckets()`	`TrawbitStorage::listBuckets()`
Create Bucket	`$client->createBucket('name', 'private')`	`TrawbitStorage::createBucket('name', 'private')`
Delete Bucket	`$client->deleteBucket('name')`	`TrawbitStorage::deleteBucket('name')`
List Objects	`$client->listObjects('bucket', ['prefix' => 'img/'])`	`TrawbitStorage::listObjects('bucket', ['prefix' => 'img/'])`
Upload File	`$client->upload('bucket', '/path/file.png')`	`TrawbitStorage::upload('bucket', $path)`
Put Raw String	`$client->putContent('bucket', $str, 'file.txt')`	`TrawbitStorage::putContent('bucket', $str, 'file.txt')`
Get Object Info	`$client->getObject('bucket', 'key')`	`TrawbitStorage::getObject('bucket', 'key')`
Download to String	`$client->download('bucket', 'key')`	`TrawbitStorage::download('bucket', 'key')`
Download to Disk	`$client->downloadToFile('bucket', 'key', '/save/path')`	`TrawbitStorage::downloadToFile('bucket', 'key', '/save/path')`
Presigned URL	`$client->generatePresignedUrl('bucket', 'key', 60)`	`TrawbitStorage::generatePresignedUrl('bucket', 'key', 60)`
Delete File	`$client->deleteObject('bucket', 'key')`	`TrawbitStorage::deleteObject('bucket', 'key')`
Copy File	`$client->copyObject('b1', 'src', 'dst')`	`TrawbitStorage::copyObject('b1', 'src', 'dst')`
Move/Rename File	`$client->moveObject('b1', 'src', 'dst')`	`TrawbitStorage::moveObject('b1', 'src', 'dst')`
Object Versions	`$client->getVersions('bucket', 'key')`	`TrawbitStorage::getVersions('bucket', 'key')`
CDN Access Tokens	`$client->createObjectToken('bucket', 'key', 'Token Name')`	`TrawbitStorage::createObjectToken('bucket', 'key', 'Token Name')`

🤝 Need Help?

📚 Full API Documentation: https://oss.trawbit.app/api/docs
💬 Support Email: support@trawbit.app
🐛 Issue Tracker: GitHub Issues

📄 License

Open-source licensed under the MIT License.

trawbit / oss

Maintainers

Package info

Statistics

Security

README

Trawbit OSS PHP SDK (`trawbit/oss`)

📖 Table of Contents

🌟 What is Trawbit OSS?

📋 Prerequisites

🔑 Step 1: Get Your API Keys

📦 Step 2: Installation

🚀 Beginner Quickstart: Pure PHP

⚡ Beginner Quickstart: Laravel Framework

1. Publish the Configuration File

2. Add Credentials to your `.env` File

3. Use in Any Controller or Route

💡 Step-by-Step Practical Tutorials

1. Upload an Image or File

2. Create a Temporary Expiring Download Link

3. Save Text or CSV Content Directly (Without Saving to Disk)

4. Download a File to Your Server

5. Copy, Move, or Delete Files

🛡️ Error Handling Made Simple

📋 Complete API Cheatsheet

🤝 Need Help?

📄 License

trawbit / oss

Maintainers

Package info

Statistics

Security

README

Trawbit OSS PHP SDK (trawbit/oss)

📖 Table of Contents

🌟 What is Trawbit OSS?

📋 Prerequisites

🔑 Step 1: Get Your API Keys

📦 Step 2: Installation

🚀 Beginner Quickstart: Pure PHP

⚡ Beginner Quickstart: Laravel Framework

1. Publish the Configuration File

2. Add Credentials to your .env File

3. Use in Any Controller or Route

💡 Step-by-Step Practical Tutorials

1. Upload an Image or File

2. Create a Temporary Expiring Download Link

3. Save Text or CSV Content Directly (Without Saving to Disk)

4. Download a File to Your Server

5. Copy, Move, or Delete Files

🛡️ Error Handling Made Simple

📋 Complete API Cheatsheet

🤝 Need Help?

📄 License

Trawbit OSS PHP SDK (`trawbit/oss`)

2. Add Credentials to your `.env` File