root/plugins/sfAmazonS3FSPlugin/README

 = sfAmazonS3FS - transparent use of Amazon S3 for your local file system = 


'''What it is'''
Abstracts the Amazon Simple Storage Service(S3) allowing you to treat S3
like a local file system. Using a cache you get the speed of the local FS
with the reliability of S3. This works on distributed systems and clusters
as S3 will act as the master file system while the local machine maintains
a cache.

'''The sfAmazonS3File object'''
An sfAmazonS3File object should be thought of as a typical file on your 
local file system not as an S3 object. When instantiated if the file exists
on S3 and not on the local file system it will be copied to the local FS.
Any actions after that will use the cached file.


'''Features:'''
- Maintains cache of files locally
- Put / Get / Delete files in S3 is totally transparent
- Get file data, file path, or escaped url
- Get files from request and put them in S3

'''Planned Features:'''
- Zip files for S3
- Make file additions atomic (if it fails adding to S3 don't put in cache)

'''Installation'''
app.yml.dist - copy contents to app.yml and add your amazon keys and select
a default bucket where your files will be stored. You can override these
settings by passing the constructor the keys and bucket info if you prefer

config.php.dist - copy contents to config.php. This file controls where 
files will be stored locally. By default they are put in:
web/uploads/sfAmazonS3FS. To make sure web/uploads is writable run:
'symfony fix-perms'

pear install Crypt_HMAC
pear install HTTP_Request

'''Dependencies'''
Pear Packages
 - Crypt_HMAC
 - HTTP_Request
 - pecl/Fileinfo
 
'''Exmaples:'''

//Create a file from a form submission
{{{
  $fileName = '/you/can/have/many/subfolders/file.txt';
  sfAmazonS3File::getNewInstance($fileName)->addFromRequest('agent_photo');
}}}

//Retrieve a file
{{{
  $fileName = '/you/can/have/many/subfolders/file.txt';
  $f = sfAmazonS3File::getNewInstance($fileName);
  echo $f->getURL();  // URL to file
  echo $f->getPath(); // Absolute path to local file
}}}

//Delete file
{{{
  $fileName = '/you/can/have/many/subfolders/file.txt';
  sfAmazonS3File::getNewInstance($fileName)->delete();
}}}