PHPackages                             mnapoli/simple-s3 - 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. mnapoli/simple-s3

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

mnapoli/simple-s3
=================

Simple, single-file and dependency-free AWS S3 client

1.2.4(1w ago)3914.4k↑1871.2%4MITPHPPHP >=8.0

Since Aug 11Pushed 6mo ago3 watchersCompare

[ Source](https://github.com/mnapoli/simple-s3)[ Packagist](https://packagist.org/packages/mnapoli/simple-s3)[ GitHub Sponsors](https://github.com/mnapoli)[ RSS](/packages/mnapoli-simple-s3/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (6)Dependencies (10)Versions (8)Used By (0)

Simple, single-file and dependency-free AWS S3 client.

Why?
----

[](#why)

In some scenarios we want the **simplest and lightest S3 client** possible. For example in [Bref](https://bref.sh)'s runtime core we don't want to embed the full AWS SDK.

If you need more, you can use the official AWS SDK for PHP, or this great alternative: [Async AWS](https://async-aws.com).

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

[](#installation)

This package can be installed via Composer:

```
composer require mnapoli/simple-s3
```

However, this package offers a guarantee that **all logic will be self-contained** into the `src/SimpleS3.php` file. If you want to take advantage of that, you can either:

- download the `SimpleS3.php` file and copy it into your application,
- or install the package via Composer and copy `vendor/mnapoli/simple-s3/src/SimpleS3.php` in your application (best because Composer will let you constrain the major version).

Usage
-----

[](#usage)

```
use Mnapoli\SimpleS3;

$region = 'us-east-1'; // or whatever region you prefer

// Instantiate from AWS credentials in environment variables, for example on AWS Lambda
$s3 = SimpleS3::fromEnvironmentVariables($region);

$s3->put('my-bucket', '/object.json', json_encode(['hello' => 'world']));

[$status, $objectBody] = $s3->get('my-bucket', '/object.json');
echo $objectBody;

$s3->delete('my-bucket', '/object.json');
```

You can also instantiate the class by providing AWS credentials explicitly:

```
$s3 = new SimpleS3($accessKeyId, $secretKey, $sessionToken, $region);
```

Any error (400, 403, 404, 500…) will be thrown as an exception. Sometimes a 404 is expected and we don't want a generic exception: look at the `getIfExists()` example below.

Note: only a subset of the AWS S3 API is supported by this package (CRUD files in a bucket basically).

Examples
--------

[](#examples)

`$s3->get()` will throw an exception if the key doesn't exist. You can use `getIfExists()` to get an empty `$body` instead:

```
[$status, $body] = $s3->getIfExists('my-bucket', $key);
if ($status === 404) {
    echo 'Not found';
} else {
    echo $body;
}
```

Get an object only if it was changed:

```
[$status, $body, $responseHeaders] = $s3->get('my-bucket', $key, [
    'If-None-Match' => $previousEtag,
]);
if ($status === 304) {
    echo 'Object up to date!';
} else {
    $newObjectBody = $body;
    $newEtag = $responseHeaders['ETag'];
}
```

### Body/Stream Helpers

[](#bodystream-helpers)

`getBody()` and `getStream()` were added for convenience when fetching objects.

Get a file’s contents as a string:

```
$contents = $s3->getBody($bucket, 'path/to/file.jpg');
// $contents is the raw object body (string).
```

Stream a file directly to output:

```
[$status, $stream, $headers] = $s3->getStream($bucket, 'path/to/video.mp4');

header('Content-Type: ' . ($headers['Content-Type'] ?? 'application/octet-stream'));
header('Content-Length: ' . ($headers['Content-Length'] ?? ''));
fpassthru($stream);
fclose($stream); // important to close the file the function opened
```

Upload from a resource (stream):

```
$fp = fopen('/path/to/local/file.mp4', 'rb');

$headers = [
    'Content-Type' => 'video/mp4',
    // Optional but recommended if size is known:
    'content-length' => (string) filesize('/path/to/local/file.mp4'),
];

$s3->put($bucket, 'uploads/file.mp4', $fp, $headers);
fclose($fp); // close the file you opened
```

Upload from a string:

```
$s3->put($bucket, 'uploads/hello.txt', 'Hello world', [
    'Content-Type' => 'text/plain',
]);
```

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance81

Actively maintained with recent releases

Popularity41

Moderate usage in the ecosystem

Community13

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 71.9% 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 ~242 days

Recently: every ~44 days

Total

7

Last Release

12d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/329a6111724074f5388e95dd41a03ccf3c43f4bfe1ecf27c94c9efc6f7823228?d=identicon)[mnapoli](/maintainers/mnapoli)

---

Top Contributors

[![mnapoli](https://avatars.githubusercontent.com/u/720328?v=4)](https://github.com/mnapoli "mnapoli (23 commits)")[![dconco](https://avatars.githubusercontent.com/u/118613296?v=4)](https://github.com/dconco "dconco (9 commits)")

---

Tags

awsaws-s3phps3s3aws

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mnapoli-simple-s3/health.svg)

```
[![Health](https://phpackages.com/badges/mnapoli-simple-s3/health.svg)](https://phpackages.com/packages/mnapoli-simple-s3)
```

###  Alternatives

[league/flysystem

File storage abstraction for PHP

13.6k694.3M2.8k](/packages/league-flysystem)[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k555.0M2.8k](/packages/aws-aws-sdk-php)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k293.8M1.2k](/packages/league-flysystem-aws-s3-v3)[aws/aws-sdk-php-laravel

A simple Laravel 9/10/11/12/13 service provider for including the AWS SDK for PHP.

1.7k39.1M90](/packages/aws-aws-sdk-php-laravel)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2921.7M63](/packages/creocoder-yii2-flysystem)[async-aws/s3

S3 client, part of the AWS SDK provided by AsyncAws.

6117.0M60](/packages/async-aws-s3)

PHPackages © 2026

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