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.3(3mo ago)3897↓50%4MITPHPPHP >=8.0

Since Aug 11Pushed 3mo 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 1mo ago

READMEChangelog (6)Dependencies (5)Versions (7)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

47

—

FairBetter than 94% of packages

Maintenance82

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity56

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 ~256 days

Recently: every ~296 days

Total

6

Last Release

96d 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.6k639.1M2.2k](/packages/league-flysystem)[aws/aws-sdk-php

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

6.2k511.3M2.2k](/packages/aws-aws-sdk-php)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.6k263.6M790](/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.7k35.6M75](/packages/aws-aws-sdk-php-laravel)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M62](/packages/creocoder-yii2-flysystem)[async-aws/s3

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

5714.0M32](/packages/async-aws-s3)

PHPackages © 2026

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