PHPackages                             forepath/laravel-s3-server - 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. [File & Storage](/categories/file-storage)
4. /
5. forepath/laravel-s3-server

ActiveLibrary[File & Storage](/categories/file-storage)

forepath/laravel-s3-server
==========================

Lightweight Laravel-compatible S3 protocol server

v1.3.0(9mo ago)2192[1 issues](https://github.com/forepath/laravel-s3-server/issues)1MITPHPPHP ^8.1CI passing

Since Jul 19Pushed 9mo agoCompare

[ Source](https://github.com/forepath/laravel-s3-server)[ Packagist](https://packagist.org/packages/forepath/laravel-s3-server)[ RSS](/packages/forepath-laravel-s3-server/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (11)Used By (1)

Laravel S3 Server
=================

[](#laravel-s3-server)

[![Latest Version on Packagist](https://camo.githubusercontent.com/773fcce1c27d4cff5be629af4d93b7e961f0345d8337f67fd6c61d89ced23cdc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f666f7265706174682f6c61726176656c2d73332d7365727665722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/forepath/laravel-s3-server)[![Tests](https://camo.githubusercontent.com/f0aba850196806fd4e416614ef0f2092ab6900f81c1139d7151f9fb5707f604d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f666f7265706174682f6c61726176656c2d73332d7365727665722f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/forepath/laravel-s3-server/actions)[![Total Downloads](https://camo.githubusercontent.com/79393f9d0cf9a59411594201210f82b2c5c2429b27ced4958d0ba782ec3c2b69/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f666f7265706174682f6c61726176656c2d73332d7365727665722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/forepath/laravel-s3-server)[![License](https://camo.githubusercontent.com/85608360f3f60cbbcd476cf12a6322a5685a970d84fc37a53fe66f6176c98a4c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f666f7265706174682f6c61726176656c2d73332d7365727665722e7376673f7374796c653d666c61742d737175617265)](https://github.com/forepath/laravel-s3-server/blob/main/LICENSE)

A lightweight, Laravel-compatible Amazon S3 protocol server that allows you to run your own S3-compatible storage service within your Laravel application. Perfect for development, testing, or self-hosted storage solutions.

Features
--------

[](#features)

- 🔐 **Full S3 Protocol Support** - Compatible with AWS S3 API v4
- 🔐 **Secure Authentication** - AWS Signature Version 4 (AWS4-HMAC-SHA256) authentication
- 💾 **Database-Backed Credentials** - Store and manage S3 credentials in your database
- 🔒 **Bucket-Level Access Control** - Restrict credentials to specific buckets for enhanced security
- 🔒 **Encrypted Storage** - Secret keys are automatically encrypted using Laravel's encryption
- 🔒 **Flexible Storage Drivers** - File-based storage with extensible driver system
- 🛡️ **Laravel Integration** - Seamless integration with Laravel's service container
- ⚡ **Lightweight** - Minimal overhead, maximum performance
- 🔒 **Production Ready** - Built with security and reliability in mind

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10, 11, or 12
- Database (MySQL, PostgreSQL, SQLite, etc.)

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

[](#installation)

You can install the package via Composer:

```
composer require forepath/laravel-s3-server
```

Quick Start
-----------

[](#quick-start)

### 1. Publish Configuration

[](#1-publish-configuration)

Publish the configuration file to customize the S3 server settings:

```
php artisan vendor:publish --provider="LaravelS3Server\S3ServiceProvider" --tag="s3server-config"
```

### 2. Run Migrations

[](#2-run-migrations)

Run the migrations to create the necessary database tables:

```
php artisan migrate
```

This will create the `s3_access_credentials` table with support for bucket restrictions.

### 3. Create S3 Credentials

[](#3-create-s3-credentials)

Add S3 credentials to your database:

```
use LaravelS3Server\Models\S3AccessCredential;

S3AccessCredential::create([
    'access_key_id' => 'AKIAIOSFODNN7EXAMPLE',
    'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    'description' => 'Development credentials',
    'bucket' => null, // Optional: restrict to specific bucket
]);
```

### 4. Start Using S3

[](#4-start-using-s3)

Your S3 server is now available at `/s3/{bucket}/{key}` and supports all standard S3 operations!

Configuration
-------------

[](#configuration)

The configuration file is located at `config/s3server.php`:

```
return [
    // Enable/disable authentication
    'auth' => true,

    // Authentication driver class
    'auth_driver' => LaravelS3Server\Drivers\DatabaseAuthenticationDriver::class,

    // Storage driver class
    'storage_driver' => LaravelS3Server\Drivers\FileStorageDriver::class,
];
```

### Authentication Settings

[](#authentication-settings)

- `auth`: Set to `false` to disable authentication (not recommended for production)
- `auth_driver`: The authentication driver class to use

### Storage Settings

[](#storage-settings)

- `storage_driver`: The storage driver class to use for file operations

Usage
-----

[](#usage)

### S3 API Endpoints

[](#s3-api-endpoints)

The package automatically registers the following S3-compatible endpoints:

MethodEndpointDescription`PUT``/s3/{bucket}/{key}`Upload an object`GET``/s3/{bucket}/{key}`Download an object`GET``/s3/{bucket}`List bucket contents`DELETE``/s3/{bucket}/{key}`Delete an object### Using with AWS CLI

[](#using-with-aws-cli)

Configure AWS CLI to use your local S3 server:

```
aws configure set aws_access_key_id AKIAIOSFODNN7EXAMPLE
aws configure set aws_secret_access_key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws configure set region us-east-1
aws configure set endpoint_url http://localhost:8000/s3
```

### Using with AWS SDK

[](#using-with-aws-sdk)

```
use Aws\S3\S3Client;

$s3Client = new S3Client([
    'version' => 'latest',
    'region'  => 'us-east-1',
    'endpoint' => 'http://localhost:8000/s3',
    'use_path_style_endpoint' => true,
    'credentials' => [
        'key'    => 'AKIAIOSFODNN7EXAMPLE',
        'secret' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    ],
]);

// Upload a file
$s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'example.txt',
    'Body'   => 'Hello, World!',
]);

// Download a file
$result = $s3Client->getObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'example.txt',
]);

echo $result['Body'];
```

### Managing Credentials

[](#managing-credentials)

#### Creating Credentials

[](#creating-credentials)

```
use LaravelS3Server\Models\S3AccessCredential;

// Create a new credential with access to any bucket
$credential = S3AccessCredential::create([
    'access_key_id' => 'AKIAIOSFODNN7EXAMPLE',
    'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    'description' => 'Development credentials',
    'bucket' => null, // null means access to any bucket
]);

// Create a credential restricted to a specific bucket
$restrictedCredential = S3AccessCredential::create([
    'access_key_id' => 'AKIAIOSFODNN7EXAMPLE2',
    'secret_access_key' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY2',
    'description' => 'Production credentials for user-uploads bucket',
    'bucket' => 'user-uploads', // Only access to 'user-uploads' bucket
]);
```

#### Bucket Restrictions

[](#bucket-restrictions)

The S3 server supports bucket-level access control. You can restrict credentials to access only specific buckets:

- **No Restriction**: Set `bucket` to `null` to allow access to any bucket
- **Single Bucket**: Set `bucket` to a specific bucket name to restrict access to only that bucket
- **Security**: Credentials with bucket restrictions will receive 401 Unauthorized when trying to access other buckets

#### Listing Credentials

[](#listing-credentials)

```
// Get all credentials
$credentials = S3AccessCredential::all();

// Find by access key ID
$credential = S3AccessCredential::where('access_key_id', 'AKIAIOSFODNN7EXAMPLE')->first();
```

#### Updating Credentials

[](#updating-credentials)

```
$credential = S3AccessCredential::where('access_key_id', 'AKIAIOSFODNN7EXAMPLE')->first();
$credential->update([
    'description' => 'Updated description',
]);
```

#### Deleting Credentials

[](#deleting-credentials)

```
$credential = S3AccessCredential::where('access_key_id', 'AKIAIOSFODNN7EXAMPLE')->first();
$credential->delete();
```

Architecture
------------

[](#architecture)

### Authentication Drivers

[](#authentication-drivers)

The package uses a driver-based authentication system. The default `DatabaseAuthenticationDriver` authenticates requests using credentials stored in the database.

#### Custom Authentication Driver

[](#custom-authentication-driver)

Create a custom authentication driver by implementing the `AuthenticationDriver`:

```