PHPackages                             incursus/laravel-s3-tools - 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. incursus/laravel-s3-tools

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

incursus/laravel-s3-tools
=========================

This Laravel package contains additional functionality not currently in Laravel for interfacing with Amazon's S3 service, including managing versioned objects.

v1.0.2(6y ago)3382.3k8[1 PRs](https://github.com/sburkett/laravel-s3-tools/pulls)MITPHPPHP >7.1.3

Since Mar 24Pushed 5y agoCompare

[ Source](https://github.com/sburkett/laravel-s3-tools)[ Packagist](https://packagist.org/packages/incursus/laravel-s3-tools)[ RSS](/packages/incursus-laravel-s3-tools/feed)WikiDiscussions master Synced yesterday

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

 [![](https://github.com/sburkett/laravel-s3-tools/raw/master/doc/laravel-s3-tools-logo.png)](https://github.com/sburkett/laravel-s3-tools/raw/master/doc/laravel-s3-tools-logo.png)

Overview
========

[](#overview)

This Laravel package contains additional functionality not currently in Laravel for interfacing with Amazon's S3 service. In particular, there are methods for dealing with versioned objects within S3. It simply extends the existing core classes to add support for versioning in S3, and is tied into the `Storage` facade for convenience. It was designed to be a drop-in replacement, and is backwards compatible with the core functionality, so there shouldn't be any conflicts. I developed this package originally for my own need to deal with versioned objects in S3 and wanted the convenience of Laravel's `Storage` facade.

With this package, you can easily:

- Manage versioned objects stored in S3
    - Get a list of versions for a given object stored in S3
    - Retrieve a specific version of an object stored in S3
    - Delete a specific version of an object stored in S3
- Set or clear Amazon S3/API option values
- Execute other Amazon S3/API commands against your objects

Other methods and conveniences may be added in the future, depending largely upon either my own needs, or suggestions from the community. Pull requests, bug reports, etc. are welcome! :)

NOTE: Yes, I know that you can make use of the underlying Amazon S3 API package to do these sorts of things. But I wanted the convenience of tying them into the `Storage` facade, as well as for some potential additional functionality down the road. So, if you'd rather do this:

```
// Instantiate an Amazon S3 client.
$s3 = new S3Client([
	'version' => 'latest',
	'region'  => 'us-west-2'
]);

// Fetch the latest version of a file
try {
    $s3->putObject([
        'Bucket' => 'my-bucket',
        'Key'    => 'myfile.png',
				'VersionId' => 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz'
    ]);
} catch (Aws\S3\Exception\S3Exception $e) {
    echo "There was an error retrieving the file.\n";
}
```

... instead of this:

```
$file = Storage::disk('s3-tools')->getVersion($versionId)->get('myfile.png');
```

... then that's on you. Have fun. :)

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

[](#requirements)

This package assumes you have already installed the following packages:

- [league/flysystem](https://github.com/thephpleague/flysystem)
- [league/flysystem-aws-s3-v3](https://github.com/thephpleague/flysystem-aws-s3-v3)
- [aws/aws-sdk-php](https://github.com/aws/aws-sdk-php)

Laravel should already have the `league/flysystem` package installed, but you may need to install the others. I've added them as dependencies to this package, so it should be all automatic for you anyway.

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

[](#installation)

You can install the package via composer:

```
composer require incursus/laravel-s3-tools
```

Once it is installed, you will need to add the service provider, as usual, to your `config/app.php` file (for pre 5.5 versions of Laravel that do not support auto-discovery):

```
	...
	'providers' => [
		...
		Incursus\LaravelS3Tools\S3ToolsServiceProvider::class,
		...
	],
	...
```

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

[](#configuration)

### Environment Variables

[](#environment-variables)

#### AWS Environment Variables

[](#aws-environment-variables)

The `laravel-s3-tools` package makes use of the existing AWS/S3 configuration within Laravel, so if you've already configured your app to use S3, you are good to go! Of course, provided you are using the most recent AWS/S3 config statements (these were changed not too long ago in Laravel). To make sure, check your `.env` file for the following:

```
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=
AWS_BUCKET=

```

If you aren't sure what value to use in `AWS_DEFAULT_REGION`, [check this page](https://docs.aws.amazon.com/general/latest/gr/rande.html) for more information (use the value shown in the `Region` column in the table on that page.

#### S3 Tools Disk Name

[](#s3-tools-disk-name)

By default, this package will use a disk name of `s3-tools`. If you'd like to rename it to something else, you can use the `S3_TOOLS_DISK_NAME` environment variable in your `.env` file, as show below.

```
S3_TOOLS_DISK_NAME="diskname"

```

### Disk Configuration

[](#disk-configuration)

The `laravel-s3-tools` package requires that you setup a new disk configuration in your `config/filesystems.php` file. It's pretty simple, really. Just copy the entry below and paste it into your `config/filesystems.php` file. It will automatically look in your `.env` file for a custom disk name, and if not found, will fall back to the default value of simply `s3-tools`. This disk name will be the disk you use in the `Storage` facade whenever you want to utilize the functionality of this package. Th new disk configuration can also be used for normal, non-versioned S3 operations, or you can just use the original 's3' configuration for that. Up to you!

So, your `config/filesystems.php` file should look something like this:

```