README

Table of Contents

• Introduction
• Installation
• Usage
  • Create a Client
    • Server client
    • Upload client
  • Upload a File
  • Multiple Files
  • File Methods
  • Manual Flow
  • Errors
  • Laravel
• Testing
• Changelog
• Credits
• License

Introduction

PHP client & Laravel storage adapter for Byteship.

Installation

You can install the package via composer:

composer require devhammed/byteship-php

Usage

The first thing you need to do is to get an API key at Byteship. You'll find more info at the Byteship Docs.

Create a Client

Create the client with a full project API key only on trusted server code. Browser code should use a short-lived upload token minted by your backend.

Server client

use Devhammed\Byteship\Client;

$byteship = new Client(apiKey: $_ENV['BYTESHIP_API_KEY']);

Upload client

use Devhammed\Byteship\Client;

$byteship = new Client(uploadToken: 'bsut_...');

Keep API keys server-side!

Never ship a bship_... project API key to the browser. Use createUploadToken on your server and pass the returned bsut_... token to frontend code.

Upload a File

Use upload when you want the SDK to create the upload session, send the bytes to storage, complete the upload, and return the ready file.

use Devhammed\Byteship\Client;
use Devhammed\Byteship\Enums\Visibility;
use Devhammed\Byteship\ValueObjects\UploadProgress;

$byteship = new Client(apiKey: $_ENV['BYTESHIP_API_KEY']);

$file = fopen('photo.jpg', 'rb');

$uploaded = $byteship->upload(
    $file,
    path: 'uploads/photo.jpg',
    visibility: Visibility::Public,
    metadata: [
        'user_id' => '123',
    ],
    onProgress: function (UploadProgress $progress) {
        echo round($progress->percent).'% uploaded';
    },
);

echo "#{$uploaded->id} - {$uploaded->url}";

Multiple Files

Use uploadMany for batches. Each result keeps the original file, a status, and either the uploaded file or a Byteship\Error.

use Devhammed\Byteship\Client;
use Devhammed\Byteship\Enums\Visibility;
use Devhammed\Byteship\Enums\UploadManyResultStatus;
use Devhammed\Byteship\ValueObjects\UploadManyProgress;
use Devhammed\Byteship\ValueObjects\UploadInput;

$byteship = new Client(apiKey: $_ENV['BYTESHIP_API_KEY']);

$files = [
    new UploadInput(fopen('photo-1.jpg', 'rb')),
    new UploadInput(fopen('photo-2.jpg', 'rb')),
    new UploadInput(fopen('photo-3.jpg', 'rb')),
    new UploadInput(fopen('photo-4.jpg', 'rb')),
    new UploadInput(fopen('photo-5.jpg', 'rb')),
    new UploadInput(fopen('photo-6.jpg', 'rb')),
];

$results = $byteship->uploadMany(
    $files,
    concurrency: 3,
    pathPrefix: 'gallery',
    visibility: Visibility::Public,
    metadata: [
        'user_id' => '123',
    ],
    onFileProgress: function (UploadManyProgress $progress) {
        echo '#'.$progress->index.': '.round($progress->percent).'% uploaded';
    },
);

$uploaded = array_map(
    fn($item) => $item->result,
    array_filter($results, fn($item) => $item->status === UploadManyResultStatus::Fulfilled),
);

File Methods

Server clients can read file metadata, create temporary URLs for private files, download file, and delete stored files when the credential has the required scope.

use Devhammed\Byteship\Client;

$byteship = new Client(apiKey: $_ENV['BYTESHIP_API_KEY']);

$fileResponse = $byteship->getFile('uploads/photo.jpg');

echo 'File Status: '.$fileResponse->file->status;

$signedResponse = $byteship->createSignedUrl(
    $fileResponse->file->path,
    expiresInSeconds: 10 * 60,
);

echo 'Signed URL: '.$signedResponse->signedUrl->url;

$stream = $byteship->downloadFile($fileResponse->file->path);

file_put_contents('photo.jpg', $stream);

echo 'Download Size: '.filesize('photo.jpg');

$deleted = $byteship->deleteFile($fileResponse->file->path);

echo 'File Status: '.$deleted->file->status;

Manual Flow

Use the lower-level methods when you need to own one part of the flow, such as sending the file bytes with a custom upload client.

use Devhammed\Byteship\Client;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\MimeType;
use GuzzleHttp\Psr7\Utils;
use RuntimeException;

$byteship = new Client(apiKey: $_ENV['BYTESHIP_API_KEY']);

$filePath = 'manual/invoice.pdf';
$stream = Utils::streamFor(fopen($filePath, 'rb'));
$byteSize = $stream->getSize() ?? filesize($filePath);
$contentType = MimeType::fromFilename($filePath) ?? 'application/octet-stream';

$created = $byteship->createFileUpload(
    path: $filePath,
    contentType: $contentType,
    byteSize: $byteSize,
);

if (empty($created->upload->url)) {
    throw new RuntimeException('Upload URL missing');
}

$http = new GuzzleClient();

$http->request('PUT', $created->upload->url, [
    'headers' => $created->upload->headers,
    'body' => $stream,
]);

$completed = $byteship->completePathUpload(
    path: $created->file->path,
    uploadId: $created->upload->id,
);

echo $completed->file->status;

Errors

Every SDK API request throws Byteship\Error for non-2xx responses.

use Devhammed\Byteship\Client;
use Devhammed\Byteship\Error;

$byteship = new Client(apiKey: $_ENV['BYTESHIP_API_KEY']);

try {
    $byteship->createUploadToken(
        folder: 'uploads',
        maxUploadBytes: 10 * 1024 * 1024,
    );
} catch (Error $error) {
    echo "Error creating upload token: {$error->getError()} - {$error->getStatus()} - {$error->getMessage()}";
}

Laravel

This package ships with a service provider for Laravel that will automatically setup the client for your application.

To get started, create an environment variable named BYTESHIP_API_KEY in your .env file with your Byteship API key:

BYTESHIP_API_KEY=your-api-key

Then, open config/filesystems.php and add the byteship disk configuration:

return  [
    // ...

    'disks' => [
        'byteship' => [
            'driver' => 'byteship',
            'visibility' => 'public',
            'api_key' => env('BYTESHIP_API_KEY'),
        ],
    ],

    // ...
];

You should now be able to use the Byteship disk in your Laravel application just like any other storage drivers:

use Illuminate\Support\Facades\Storage;

Storage::disk('byteship')->put('hello.txt', 'Hello, Byteship!'); // true/false
Storage::disk('byteship')->get('hello.txt'); // "Hello, Byteship!"
Storage::disk('byteship')->url('hello.txt'); // "https://cdn.byteship.dev/f/12345/hello.txt" (only for public files)
Storage::disk('byteship')->temporaryUrl('hello.txt', now()->addHour()); // "https://cdn.byteship.dev/f/12345/hello.txt?token=secret-token" (only for private files)
Storage::disk('byteship')->temporaryUploadUrl('hello.txt', now()->addHour(), ['byte_size' => 1024]) // ['file_id' => '123', 'upload_id' => '456', 'upload_token' => 'd34db33f', 'url' => 'https://...', 'complete_url' => 'https://...', 'headers' => ['content-type' => 'text/plain']] (use the complete URL + upload ID + upload_token to complete the upload after sending the file to the url + headers)
Storage::disk('byteship')->delete('hello.txt'); // true/false
Storage::disk('byteship')->exists('hello.txt'); // true/false
Storage::disk('byteship')->mimeType('hello.txt'); // "text/plain"
Storage::disk('byteship')->visibility('hello.txt'); // "public" / "private"
Storage::disk('byteship')->size('hello.txt'); // 16

RECOMMENDED: You should set the default disk to byteship inside config/filesystems.php so you won't have to specify the disk name everytime you work with Storage.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Hammed Oyedele
• Byteship
• All Contributors

License

The MIT License (MIT). Please see License File for more information.