How to store and manage files on Amazon S3 with PHP class

Like all you know, or not, Amazon S3 is the storage for the internet. It can be used to store and retrieve any amount of data. You can find all needed information about this web service here: http://aws.amazon.com/s3 but basically  I’ll show you, in brief, how to manage data in easy way.

Long  time ago one of my client want it to use S3 servers to store his data.  I didn’t want to reinvent the wheel , so I use already written  PHP class by Donovan Schonknecht (http://undesigned.org.za/). What I’m going to do is use a standard HTML tag (file element) and make a page where people can upload a file to S3 account and retrieve information about the files that have already been uploaded.

But before we’ll start I would like to explain some phrase: bucket. Bucket can be compare to regular main directory. It can contains any type of data. On S3 Amazon all our files are stored in buckets. We can also create, delete, rename these buckets if we like to. In step 5 you will find function to create a new bucket.

Please also bear in mind these 3 access to buckets and files:
-  S3::ACL_PRIVATE – used only in internal operation
-  S3::ACL_PUBLIC_READ  – gain access for all data only for read
-  S3::ACL_PUBLIC_READ_WRITE – gain access for all data for read and write
This is some kind of ACL – Access Control List. These will be used in further steps.

So please follow the steps

Step 1:

-  download PHP class: http://undesigned.org.za/2007/10/22/amazon-s3-php-class
-  create a simple test file called upload.php

Step 2:

Next we’ll have to include S3.php file into upload.php. We can use require_once() php’s function. Before manage files we need access to our S3 server. These are Access Key and Secret Key provided by Amazon (during registration process – https://aws-portal.amazon.com/gp/aws/developer/registration/index.html) . After this we’ve got all needed information to initialize our class.

upload.php
<?php
//include the S3 class
require_once(‘S3.php’);

//AWS access info
define(‘ACCESS_KEY’, ‘__OUR_ACCESS_KEY___’);
define(‘SECRET_KEY’, ‘__OUR_SECRET_KEY__’);
define(‘BUCKET_NAME’, ‘__OUR_BUCKET_NAME_’);

//instantiate the class
$s3 = new S3(ACCESS_KEY,  SECRET_KEY);
?>

Well, now we’ve got created handler to our S3 account. We can easy upload any amount data.

Step 3:

Now we’ll create simple html form for uploading files. Please, don’t forget about enctype=”multipart/form-data”. It’s a very common mistake J. Put this html tags right after php code in file upload.php

<form action=”" method=”post” enctype=”multipart/form-data”>
<input type=”file” name=”file”/>
<input type=”submit” value=”Upload” name=”Submit”>
</form>

As you can see if we left attribute action=’’ empty, the form will post variables into current file and refresh page.

Now please put this code right after where we initiated S3 class.

<?php
//check whether a form was submitted
if(isset($_POST['Submit'])) {
//retreive post variables
$fileName = $_FILES['file']['name'];
$fileTempName = $_FILES['file']['tmp_name']; }
?>

Step 5:

I’ve wrote  some helpful functions (based on S3 class). Please put all these function in new created file functions.php, later it will be included into upload.php.

-  add new bucket

/**
* Adding new bucket
* @param object $s3 S3 handler
* @param string $name bucket’s name
* @param string $access grand rights to created bucket :
*   – ‘ S3::ACL_PRIVATE ‘ (internal Access – by default)
*   – ‘ S3::ACL_PUBLIC_READ‘ (external access – only for read)
*   – ‘ S3::ACL_PUBLIC_READ_WRITE ‘ (external Access – read and write
* @return boolean true/false
**/

function addBucket($s3 = null, $name = null, $access = ‘S3::ACL_PUBLIC_READ’) {
if(!empty($name)  && !empty(($s3)) {
if($s3->putBucket($name, $access)) {
return true;
}
return false;
} else { return false; }
}

- return all files (list them) from choosed bucket

/**
* List bucket’s files
* @param object $s3 S3 handler
* @param string $bucket bucket’s name
* @param $prefix directory name with forward slash in the end
* @return array files array
*/

function listFiles($s3 = null, $bucket = null , $prefix = null) {
$ls = $s3->getBucket($bucket, $prefix);
if(!empty($ls))  {
foreach($ls as $l) {
$fname = str_replace($prefix,”,$l['name']);
if(!empty($fname)) { $rv[] = $fname; }
} }
if(!empty($rv)) { return $rv; }
}

- upload file

/**
* Upload file
* @param object $s3 S3 handler
* @param string $bucket bucket’s name
* @param string $file path with file name (it could be also variable $_FILES[‘file’][‘tmp_name’])
* @param string $descPath path where file should be written
* @param string $descName file name for uploaded file (with extension)
* @return true on success, false on fail
*/

function uploadPhoto($s3 = null, $bucket  = null, $file = null,  $descName = null)  {
if(is_file($file))  {
if(empty($descName))  { return false; }
if(!empty($s3) && !empty($bucket)) {
$s3->putObjectFile($file, $bucket, $descName, S3::ACL_PUBLIC_READ);return true; }
else { return false; }
}
}

Well, it’s time to show you completely upload.php file:

<?php
//include the S3 class
require_once(‘S3.php’);

// include our functions
require_once(‘functions.php’);

//AWS access info
define(‘ACCESS_KEY’, ‘__OUR_ACCESS_KEY___’);
define(‘SECRET_KEY’, ‘__OUR_SECRET_KEY__’);
define(‘BUCKET_NAME’, ‘our-bucket-name’);

//instantiate the class
$s3 = new S3(ACCESS_KEY,  SECRET_KEY);

// please remove this code after first launch, it’s only create new bucket !!!
addBucket($s3, BUCKET_NAME, ‘S3::ACL_PUBLIC_READ’);

//check whether a form was submitted
if(isset($_POST['Submit'])){
//retreive post variables
$fileName = $_FILES['file']['name'];
$fileTempName = $_FILES['file']['tmp_name'];

// upload file to S3
uploadPhoto($s3, BUCKET_NAME, $fileTempName, $fileName):
}
?>

<form action=”" method=”post” enctype=”multipart/form-data”>
<input type=”file” name=”file” />
<input value=”Upload” type=”submit” name=”Submit”>
</form>

<?php

// list all files from S3
listFiles($s3, BUCKET_NAME);

?>

Now when you select a file and hit ‘Upload’ the file will be stored on the amazon server. You can already view it just by entering a URL that looks like this:
http:// our-bucket-name.s3.amazoneaws.com/yourfile.ext.

I hope this little tutorial will help to know better service like S3 Amazon.

Tags: Amazon, php, programming, S3

This entry was posted on Friday, March 12th, 2010 at 12:31 and is filed under Developers. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

Comments (2) to “How to store and manage files on Amazon S3 with PHP class”

• 
  21 April 2010 at 21:40, Cleveland Ferrarotti says

  So very true, thanks for the post! How to store and manage files on Amazon S3 with PHP class | PGS Software was a wonderful read.
• 
  8 August 2010 at 23:14, automotive tires says

  gives use a perfect web page decent Gives thanks for the working hard to help everyone