hernol/uploadthing-php

A high-quality PHP client for the UploadThing v6 REST API

2.0.1 2026-02-19 19:49 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/log: ^1.0|^2.0|^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• php-http/mock-client: ^1.0
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0
• rector/rector: ^1.0

MIT

• Hernol

• php
• API-Client
• webhooks
• multipart
• rest-api
• file-upload
• chunked-upload
• presigned-urls
• uploadthing
• v6-api

README

A simplified, Laravel-focused PHP client for the UploadThing v6 REST API.

Features

• ✅ V6 API Compatible: Uses UploadThing v6 /uploadFiles endpoint
• ✅ Type-safe: Full PHP 8.1+ type declarations and strict typing
• ✅ Laravel-focused: Designed specifically for Laravel applications
• ✅ Environment-based configuration: Simple configuration via environment variables
• ✅ File uploads: Upload files using presigned S3 URLs
• ✅ Webhook verification: HMAC-SHA256 signature validation with timestamp tolerance
• ✅ Simple API: Clean, straightforward interface

Quick Start

Installation

composer require hernol/uploadthing-php

Configuration

Set your environment variables in your .env file:

UPLOADTHING_API_KEY=ut_sk_your_api_key_here
UPLOADTHING_BASE_URL=https://api.uploadthing.com
UPLOADTHING_API_VERSION=v6
UPLOADTHING_TIMEOUT=30
UPLOADTHING_CALLBACK_URL=https://your-app.com/webhook
UPLOADTHING_CALLBACK_SLUG=your-slug

Basic Usage

Upload a File

<?php

use UploadThing\Resources\Uploads;

$uploads = new Uploads();
$file = $uploads->uploadFile('/path/to/file.jpg');

if ($file) {
    echo "File uploaded: {$file->name}\n";
    echo "File URL: {$file->url}\n";
    echo "File ID: {$file->id}\n";
}

Upload with Custom Name and MIME Type

<?php

use UploadThing\Resources\Uploads;

$uploads = new Uploads();
$file = $uploads->uploadFile(
    '/path/to/image.jpg',
    'my-custom-name.jpg',
    'image/jpeg'
);

Handle Webhooks

<?php

use UploadThing\Resources\Webhooks;

$webhooks = new Webhooks();

// Handle webhook from Laravel request
$event = $webhooks->handleWebhook(
    $request->getContent(),
    $request->headers->all(),
    env('UPLOADTHING_WEBHOOK_SECRET')
);

echo "Event type: {$event->type}\n";
echo "Event data: " . json_encode($event->data) . "\n";

Handle Webhook from PHP Globals

<?php

use UploadThing\Resources\Webhooks;

$webhooks = new Webhooks();
$event = $webhooks->handleWebhookFromGlobals(
    env('UPLOADTHING_WEBHOOK_SECRET')
);

V6 API Endpoint

The client uses the UploadThing v6 /uploadFiles endpoint which:

1. Prepares the upload and returns S3 presigned URL data
2. Uploads the file to S3 using multipart form data
3. Finalizes the upload via polling (retries up to 5 times with 1-second delays)

Error Handling

<?php

use UploadThing\Exceptions\ApiException;
use UploadThing\Exceptions\AuthenticationException;
use UploadThing\Exceptions\RateLimitException;
use UploadThing\Exceptions\ValidationException;

try {
    $file = $uploads->uploadFile('/path/to/file.jpg');
} catch (AuthenticationException $e) {
    echo "Invalid API key: " . $e->getMessage();
} catch (RateLimitException $e) {
    echo "Rate limited, retry after: " . $e->getRetryAfter() . "s";
} catch (ValidationException $e) {
    echo "Validation error: " . $e->getMessage();
} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage();
    echo "Error Code: " . $e->getErrorCode();
}

Examples

See the examples folder for complete usage examples:

• Basic File Upload
• Upload with Custom Options
• Webhook Handling
• Webhook Handler Utility
• Webhook Verifier
• Laravel Controller Example
• Error Handling

Documentation

• 📖 Usage Guide
• ⚡ Laravel Integration

Requirements

• PHP 8.1 or higher
• Composer
• UploadThing API key

Supported PHP Versions

PHP Version	Support
8.1	✅ Full support
8.2	✅ Full support
8.3	✅ Full support

Laravel Integration

Service Provider (Optional)

You can create a service provider to bind the resources:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use UploadThing\Resources\Uploads;
use UploadThing\Resources\Webhooks;

class UploadThingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(Uploads::class, function () {
            return new Uploads();
        });

        $this->app->singleton(Webhooks::class, function () {
            return new Webhooks();
        });
    }
}

Usage in Controllers

<?php

namespace App\Http\Controllers;

use UploadThing\Resources\Uploads;
use Illuminate\Http\Request;

class FileController extends Controller
{
    public function upload(Request $request, Uploads $uploads)
    {
        $file = $request->file('file');
        $uploaded = $uploads->uploadFile(
            $file->getPathname(),
            $file->getClientOriginalName(),
            $file->getMimeType()
        );

        return response()->json(['file' => $uploaded]);
    }
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Security

If you discover a security vulnerability, please see our Security Policy.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.