README

This package is designed to build the necessary AWS signature (v4), policy and form inputs for sending files directly to Amazon's S3 service. This is especially useful when uploading from cloud platforms and help to build 'twelve factor apps'.

This project was sprouted from this blog post which might help explain how the code works and how to set it up. The blog post also has lots of useful comments, which might help you out if you're having problems.

Supports PHP 7.2+ (if you need php 5.5+ use v1.*)

Install

This package can be installed using Composer by running:

composer require eddturtle/direct-upload

Usage

Once we have the package installed we can make our uploader object like so: (remember to add your S3 details)

Option 1: Specify AWS Credentials

<?php

use EddTurtle\DirectUpload\Signature;

// Require Composer's autoloader
require_once __DIR__ . "/vendor/autoload.php";

$uploader = new Signature(
    "YOUR_S3_KEY",
    "YOUR_S3_SECRET",
    "YOUR_S3_BUCKET",
    "eu-west-1"
);

OR Option 2: Use Environment Variables (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)

<?php

use EddTurtle\DirectUpload\SignatureAuto;

// Require Composer's autoloader
require_once __DIR__ . "/vendor/autoload.php";

$uploader = new SignatureAuto("YOUR_S3_BUCKET", "eu-west-1");

More info on finding your region @ http://amzn.to/1FtPG6r

Then, using the object we've just made, we can generate the form's url and all the needed hidden inputs.

<form action="<?php echo $uploader->getFormUrl(); ?>" method="POST" enctype="multipart/form-data">

    <?php echo $uploader->getFormInputsAsHtml(); ?>
    <input type="file" name="file">

</form>

Example

We have an example project setup, along with the JavaScript, to demonstrate how the whole process will work.

S3 CORS Configuration

When uploading a file to S3 through the browser it's important that the bucket has a CORS configuration that's open to accepting files from elsewhere. Here's an example CORS setup:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedMethod>PUT</AllowedMethod>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

Options

Options can be passed into the Signature class as a fifth parameter, below is a list of possible options which can be overwritten.

For example:

$uploader = new SignatureAuto("", "", [
    'acl' => 'public-read',
    'max_file_size' => 10,
    'encryption' => true,
    'additional_inputs' => [
        'Content-Disposition' => 'attachment'
    ]
]);

Available Signature Methods

Contributing

Contributions via pull requests are welcome. The project is built with PSR 1+2 coding standards, if any code is submitted it should adhere to this and come with any applicable tests for code changed/added. Where possible also keep one pull request per feature.

Running the tests is as easy as running:

vendor/bin/phpunit

Licence

This project is licenced under the MIT licence, which you can view in full within the LICENCE file of this repository.

eddturtle / direct-upload

Maintainers

Details