PHPackages                             devhammed/byteship-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. devhammed/byteship-php

ActiveLibrary[API Development](/categories/api)

devhammed/byteship-php
======================

PHP client for the Byteship Upload API.

0.0.2(1mo ago)10MITPHPPHP ^8.3CI passing

Since May 7Pushed 1mo agoCompare

[ Source](https://github.com/devhammed/byteship-php)[ Packagist](https://packagist.org/packages/devhammed/byteship-php)[ Docs](https://github.com/devhammed/byteship-php)[ RSS](/packages/devhammed-byteship-php/feed)WikiDiscussions develop Synced 1w ago

READMEChangelog (2)Dependencies (15)Versions (3)Used By (0)

Byteship PHP
============

[](#byteship-php)

[![Latest Version on Packagist](https://camo.githubusercontent.com/26f299bb803c6066063759d51c1948716197c6157e0d793a2086df0df496d243/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64657668616d6d65642f62797465736869702d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/devhammed/byteship-php)[![GitHub Tests Action Status](https://camo.githubusercontent.com/fbbd33a994abaf1c4f38c43d567e4ba9b041e55f8cd40d6dd12855b964e398ba/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f64657668616d6d65642f62797465736869702d7068702f72756e2d74657374732e796d6c3f6272616e63683d646576656c6f70266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/devhammed/byteship-php/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/f33dacbdbda3ea075b0cc2a6a8d2ed574cc1ce427acd8b699c1091c68481184f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f64657668616d6d65642f62797465736869702d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/devhammed/byteship-php)[![Laravel Compatibility](https://camo.githubusercontent.com/95ed0e810af629988f57ef43496623ced404bbba48d093a280bd4e56b300ee6d/68747470733a2f2f62616467652e6c61726176656c2e636c6f75642f62616467652f64657668616d6d65642f62797465736869702d706870)](https://packagist.org/packages/devhammed/byteship-php)

Table of Contents
-----------------

[](#table-of-contents)

- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
    - [Create a Client](#create-a-client)
        - [Server client](#server-client)
        - [Upload client](#upload-client)
    - [Upload a File](#upload-a-file)
    - [Multiple Files](#multiple-files)
    - [File Methods](#file-methods)
    - [Manual Flow](#manual-flow)
    - [Errors](#errors)
    - [Laravel](#laravel)
- [Testing](#testing)
- [Changelog](#changelog)
- [Credits](#credits)
- [License](#license)

Introduction
------------

[](#introduction)

PHP client & Laravel storage adapter for [Byteship](https://byteship.dev).

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require devhammed/byteship-php
```

Usage
-----

[](#usage)

The first thing you need to do is to get an API key at [Byteship](https://byteship.dev/console). You'll find more info at the [Byteship Docs](https://byteship.dev/docs).

### Create a Client

[](#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

[](#server-client)

```
use Devhammed\Byteship\Client;

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

#### Upload client

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Credits
-------

[](#credits)

- [Hammed Oyedele](https://github.com/devhammed)
- [Byteship](https://byteship.dev)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance93

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b6f8e2de94053cb1252063a069ee6e79f92a4edf613c0fb746e5ef271f45b3e5?d=identicon)[devhammed](/maintainers/devhammed)

---

Top Contributors

[![devhammed](https://avatars.githubusercontent.com/u/22827908?v=4)](https://github.com/devhammed "devhammed (54 commits)")

---

Tags

laravelHammed Oyedelebyteship-php

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/devhammed-byteship-php/health.svg)

```
[![Health](https://phpackages.com/badges/devhammed-byteship-php/health.svg)](https://phpackages.com/packages/devhammed-byteship-php)
```

###  Alternatives

[spatie/laravel-health

Monitor the health of a Laravel application

88011.3M149](/packages/spatie-laravel-health)[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k9.9M87](/packages/dedoc-scramble)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.3M41](/packages/spatie-laravel-pdf)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

815320.5k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client

Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof.

5019.3k](/packages/simplestats-io-laravel-client)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3913.7k](/packages/rawilk-profile-filament-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)