Perforce Chronicle 2012.2/486814
API Documentation
Public Member Functions | Protected Member Functions | Protected Attributes

P4Cms_AssetHandler_S3 Class Reference

Provide an Amazon S3 backend for Asset Handling. More...

Inheritance diagram for P4Cms_AssetHandler_S3:
P4Cms_AssetHandlerInterface

List of all members.

Public Member Functions

 __construct (array $options=null)
 Constructor allows passing options for accessKey, secretKey or bucket.
 exists ($id)
 Check if the given ID exists in storage.
 getAccessKey ()
 Returns the s3 access key.
 getBucket ()
 Returns the bucket to store objects under.
 getSecretKey ()
 Returns the s3 access key.
 isOffsite ()
 Used to determine if the asset handler will be storing assets offsite or not.
 put ($id, $data)
 Store the passed data using indicated ID.
 setAccessKey ($key)
 Used to set the s3 access key.
 setBucket ($bucket)
 Used to set the bucket for storage.
 setSecretKey ($key)
 Used to set the s3 secret key.
 uri ($id)
 Provide a URI for the indicated asset ID.

Protected Member Functions

 _getHeaders ($id)
 This method will provide the appropriate headers for the passed id.
 _getS3Service ()
 Returns the s3 service instance in use.
 _toObjectId ($id)
 Translates a Asset ID to S3 Object ID.

Protected Attributes

 $_accessKey
 $_bucket
 $_s3Service
 $_secretKey

Detailed Description

Provide an Amazon S3 backend for Asset Handling.

Storing generated assets in S3 moves them to a fast cookie free host which should give a speed boost. Further, if you are horizontally scaling your web servers this will provide a shared data store.

Copyright:
2011-2012 Perforce Software. All rights reserved
License:
Please see LICENSE.txt in top-level folder of this distribution.
Version:
2012.2/486814

Constructor & Destructor Documentation

P4Cms_AssetHandler_S3::__construct ( array $  options = null)

Constructor allows passing options for accessKey, secretKey or bucket.

Parameters:
array$optionsOptions to use on this instance 
    {
        foreach ($options ?: array() as $option => $value) {
            $method = 'set' . ucfirst($option);
            if (method_exists($this, $method)) {
                $this->$method($value);
            }
        }
    }

Member Function Documentation

P4Cms_AssetHandler_S3::_getHeaders ( $  id) [protected]

This method will provide the appropriate headers for the passed id.

It ensures the asset is publicly available and properly detects the cssgz and jsgz file extensions to set content encoding/type as needed.

Parameters:
string$idThe id to generate headers for 
    {
        $headers = array(
            Zend_Service_Amazon_S3::S3_ACL_HEADER => Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ
        );

        // the S3 class won't detect our compressed assets
        // correctly so we manually setup the headers here.
        $extension = substr(strrchr($id, '.'), 1);
        if ($extension == 'cssgz') {
            $headers['Content-Type']     = 'text/css';
            $headers['Content-Encoding'] = 'gzip';
        } else if ($extension == 'jsgz') {
            $headers['Content-Type']     = 'text/javascript';
            $headers['Content-Encoding'] = 'gzip';
        }
        
        return $headers;
    }
P4Cms_AssetHandler_S3::_getS3Service ( ) [protected]

Returns the s3 service instance in use.

Returns:
Zend_Service_Amazon_S3 the s3 service instance 
    {
        if (!$this->_s3Service) {
            $this->_s3Service = new Zend_Service_Amazon_S3(
                $this->getAccessKey(), 
                $this->getSecretKey()
            );
        }

        return $this->_s3Service;
    }
P4Cms_AssetHandler_S3::_toObjectId ( $  id) [protected]

Translates a Asset ID to S3 Object ID.

This is a simple task of tacking the bucket name on the front.

Parameters:
string$idThe id to translate to an object ID
Returns:
string The object ID to use for S3 purposes 
    {
        return $this->getBucket() . '/' . $id;
    }
P4Cms_AssetHandler_S3::exists ( $  id)

Check if the given ID exists in storage.

Parameters:
string$idThe ID to test
Returns:
bool true if exists, false otherwise

Implements P4Cms_AssetHandlerInterface.

    {
        $cacheId = 's3_asset_' . md5($id);
        if (P4Cms_Cache::load($cacheId)) {
            return true;
        }

        // if we can retreive meta-data cache result and return true
        $info = $this->_getS3Service()->getInfo($this->_toObjectId($id));
        if ($info) {
            P4Cms_Cache::save(true, $cacheId);
            return true;
        }

        // we don't cache failures as we will, most likely,
        // upload a copy shortly; simply return false
        return false;
    }
P4Cms_AssetHandler_S3::getAccessKey ( )

Returns the s3 access key.

Returns:
string The access key in use 
    {
        return $this->_accessKey;
    }
P4Cms_AssetHandler_S3::getBucket ( )

Returns the bucket to store objects under.

The DEFAULT_BUCKET constant will be used if no value has been provided.

Returns:
string The bucket assets will be stored in 
    {
        return $this->_bucket;
    }
P4Cms_AssetHandler_S3::getSecretKey ( )

Returns the s3 access key.

Returns:
string The secret key in use 
    {
        return $this->_secretKey;
    }
P4Cms_AssetHandler_S3::isOffsite ( )

Used to determine if the asset handler will be storing assets offsite or not.

Assets such as CSS need to know this so they can decide if they need to include the site's url when referencing images.

Returns:
bool true if assets stored offsite, false otherwise

Implements P4Cms_AssetHandlerInterface.

    {
        return true;
    }
P4Cms_AssetHandler_S3::put ( $  id,
$  data 
)

Store the passed data using indicated ID.

Will clobber any existing entry with the same ID.

Parameters:
string$idThe ID to store under
string$dataThe data to store
Returns:
bool True if put was successful, false otherwise

Implements P4Cms_AssetHandlerInterface.

    {
        return $this->_getS3Service()->putObject(
            $this->_toObjectId($id),
            $data,
            $this->_getHeaders($id)
        );
    }
P4Cms_AssetHandler_S3::setAccessKey ( $  key)

Used to set the s3 access key.

Parameters:
string | null$keyThe access key to use
Returns:
P4Cms_AssetHandler_S3 To maintain a fluent interface 
    {
        if (!is_string($key) && !is_null($key)) {
            throw new InvalidArgumentException("Access Key must be a string or null");
        }

        $this->_s3Service = null;
        $this->_accessKey = $key;
        
        return $this;
    }
P4Cms_AssetHandler_S3::setBucket ( $  bucket)

Used to set the bucket for storage.

Parameters:
string | null$bucketThe bucket to store assets under
Returns:
P4Cms_AssetHandler_S3 To maintain a fluent interface 
    {
        if (!is_string($bucket) && !is_null($bucket)) {
            throw new InvalidArgumentException("Bucket must be a string or null");
        }

        $this->_bucket = $bucket;
        
        return $this;
    }
P4Cms_AssetHandler_S3::setSecretKey ( $  key)

Used to set the s3 secret key.

Parameters:
string | null$keyThe secret key to use
Returns:
P4Cms_AssetHandler_S3 To maintain a fluent interface 
    {
        if (!is_string($key) && !is_null($key)) {
            throw new InvalidArgumentException("Secret Key must be a string or null");
        }

        $this->_s3Service = null;
        $this->_secretKey = $key;
        
        return $this;
    }
P4Cms_AssetHandler_S3::uri ( $  id)

Provide a URI for the indicated asset ID.

Parameters:
string$idThe ID to get a URI for
Returns:
string|bool The uri used for the specified asset or false

Implements P4Cms_AssetHandlerInterface.

    {
        return 'http://' . Zend_Service_Amazon_S3::S3_ENDPOINT . '/' . $this->getBucket() . '/' . $id;
    }

Member Data Documentation

P4Cms_AssetHandler_S3::$_accessKey [protected]
P4Cms_AssetHandler_S3::$_bucket [protected]
P4Cms_AssetHandler_S3::$_s3Service [protected]
P4Cms_AssetHandler_S3::$_secretKey [protected]
The documentation for this class was generated from the following file: