README

aS3StreamWrapper: a better Amazon S3 stream wrapper for PHP 

ABOUT

This is an Amazon S3 stream wrapper. It lets your PHP code use
fopen(), file_put_contents(), opendir(), readdir(), closedir(),
stat(), copy() and friends via Amazon S3. Unlike most wrappers there 
is full support for subdirectories (not just directory listings of 
entire buckets).

LIMITATIONS

Be aware that files are buffered entirely in memory which will lead to
out of memory errors on files larger than your PHP memory limit. 
For our use cases this currently makes a lot of sense, but
perhaps we'll add support for buffering on the local drive instead 
as an option specified when registering a protocol or creating 
a stream context. It's not hard compared to the stuff we've
covered already.

UNUSUAL FEATURES

* You can make subdirectories and sub-subdirectories (most S3
wrappers don't support S3's native features for listing things
with a prefix and a limit)
* You can register the wrapper more than once under different names
* You can subclass and extend the wrapper class properly
* Caching support for fast read access to the first 8K of each file
* Extensive unit tests

USAGE

Registering the stream wrapper is easy:

$wrapper = new aS3StreamWrapper();
$wrapper->register(array('protocol' => 's3', 
  'acl' => AmazonS3::ACL_PUBLIC, 
  'key' => 'your key id',
  'secretKey' => 'your secret key',
  'region' => AmazonS3::REGION_US_W1));

Now you can open files over S3 with, for instance:

fopen("s3://bucketname/subdir/filename.txt", "w");

Note that the first directory level is the bucket name.
You must use mkdir() to create a new bucket. Calling
mkdir() and rmdir() for subdirectories belong the bucket
level is not really necessary but we support it so that
your code works naturally.

See lib/wrapper/aS3StreamWrapperTest.php for extensive examples 
of proper usage.

Note that you can register *more than one* protocol name,
with *different* options. Which means that you can copy 
files from region to region or with different ACL settings
(public vs. private).

Many (but not all) PHP functions accept stream wrapper URLs.
See:

http://php.net/manual/en/book.stream.php

For the official PHP documentation on this. There are 
many 

Our stream wrapper class is in lib/wrapper along with 
its tests. lib/vendor contains a recent snapshot of the
official AWS PHP SDK from Amazon. 

CACHING

S3 is great at delivering content to end users 
and scaling the storage of content in general, but you don't want to do 
many reads of entire S3 objects in rapid succession just to peek at 
their headers to determine image dimensions, file type, etc. The 
optional cache feature addresses this problem. You supply the cache
object.

In addition to the options demonstrated above and in the tests, 
you can specify a 'cache'  option, which must point to a cache object 
that supports get($key), set($key, $data, $timeout-in-seconds), 
has($key) and remove($key) methods (hint: any subclass of sfCache is 
cool). This cache is used to  store the first 8K of every file and also 
the results of stat(). 

Consider using memcache or even a MySQL cache that is fast and local 
to your servers. Of course, all of your servers must use the cache
consistently to get consistent results.

SYMFONY

Although we built this for Symfony and Apostrophe, the wrapper has 
no dependencies on Symfony or Apostrophe. But if you add this
folder to your plugins/ folder in a Symfony 1.x project and
add it to ProjectConfiguration in the usual way, you'll be able
to autoload the stream wrapper. Just FYI. 

WARNING

Use at your own risk. There is no warranty, express or implied.

LICENSE

Copyright 2011 P'unk Avenue LLC. Released under the BSD license.

Built for Apostrophe: apostrophenow.com

CONTACT

Questions? Contact us via http://github.com/punkave

Also follow us at http://punkave.com/ and @punkave