Zend Framework: Zend_Service_Amazon_S3 Component Proposal

Proposed Component Name	Zend_Service_Amazon_S3
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Amazon_S3
Proposers	Justin Plock Alexander Veremyev (Zend liaison) Stanislav Malyshev
Revision	1.0 - 10 March 2008: Initial revision. 1.1 - 31 December 2008: Revised code committed into laboratory SVN 2.0 - 25 February 2009: Revised the API and finalized the laboratory implementation (wiki revision: 14)

This component will implement the Amazon S3 API
This component will use Zend_Http_Client to communicate with S3
This component will provide the API to use Amazon S3 directly
This component will implement a user-based stream wrapper for S3 (s3://)
This component will allow using multiple S3 accounts

4. Dependencies on Other Framework Components

Zend_Http_Client

5. Theory of Operation

This component will provide Amazon S3 API allowing to store and retrieve data from the Amazon S3 service.

Also, this component will be utilized using the stream_wrapper_register() PHP method to register a new user-based stream interface to S3. This allows the user to utilize existing fread(), fwrite(), fclose(), mkdir(), rmdir(), and stat() methods to directly interface with S3 buckets and objects.

6. Milestones / Tasks

Milestone 1: [DONE] Design notes will be published here
Milestone 2: [DONE] Working prototype checked into the laboratory supporting use cases
Milestone 3: [DONE] Unit tests exist, work, and are checked into SVN.
Milestone 4: [DONE] Initial documentation exists.
Milestone 5: Proposal accepted and moved to incubator
Milestone 6: The component is accepted as part of ZF core

7. Class Index

Zend_Service_Amazon_S3
Zend_Service_Amazon_S3_Stream

8. Use Cases

9. Class Skeletons

/**
 * Amazon S3 PHP connection class
 *
 * @category   Zend
 * @package    Zend_Service
 * @subpackage Amazon_S3
 * @copyright  Copyright (c) 2005-2008, Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Service_Amazon_S3 extends Zend_Service_Abstract 
{
    /**
     * @var string Amazon Access Key
     */
    protected static $default_accessKey = null;

    /**
     * @var string Amazon Secret Key
     */
    protected static $default_secretKey = null;
    
    /**
     * Store for stream wrapper clients
     *
     * @var array
     */
    protected static $_wrapperClients = array();

    const S3_ENDPOINT = 'http://s3.amazonaws.com';
    
    const S3_ACL_PRIVATE = 'private';
    const S3_ACL_PUBLIC_READ = 'public-read';
    const S3_ACL_PUBLIC_WRITE = 'public-read-write';
    const S3_ACL_AUTH_READ = 'authenticated-read';
    
    const S3_ACL_HEADER = 'x-amz-acl';
    const S3_CONTENT_TYPE_HEADER = 'Content-Type';
    
    /**
     * @var string Amazon Secret Key
     */
    protected $_secretKey;

    /**
     * @var string Amazon Access Key
     */
    protected $_accessKey;
    
    /**
     * Set the keys to use when accessing S3.
     *
     * @param  string $access_key
     * @param  string $secret_key
     * @return void
     */
    public static function setKeys($access_key, $secret_key)
    {
    }

    /**
     * Create Amazon S3 client.
     *
     * @param  string $access_key
     * @param  string $secret_key
     * @return void
     */
    public function __construct($access_key=null, $secret_key=null) {
    }
    
    /**
     * Add a new bucket
     *
     * @param  string $bucket
     * @return boolean
     */
    public function createBucket($bucket)
    {
    }

    /**
     * Checks if a given bucket name is available
     *
     * @param  string $bucket
     * @return boolean
     */
    public function isBucketAvailable($bucket)
    {
    }

    /**
     * Checks if a given object exists
     *
     * @param  string $object
     * @return boolean
     */
    public function isObjectAvailable($object)
    {
    }

    /**
     * Remove a given bucket. All objects in the bucket must be removed prior
     * to removing the bucket.
     *
     * @param  string $bucket
     * @return boolean
     */
    public function removeBucket($bucket)
    {
    }

    /**
     * Get metadata information for a given object
     *
     * @param  string $object
     * @return array
     */
    public function getInfo($object)
    {
    }

    /**
     * List the S3 buckets
     *
     * @return array|false
     */
    public function getBuckets()
    {
    }
    
    /**
     * Remove all objects in the bucket.
     *
     * @param string $bucket
     * @return boolean
     */
    public function cleanBucket($bucket) {
    }

    /**
     * List the objects in a bucket.
     * 
     * Provides the list of object keys that are contained in the bucket. 
     *
     * @param  string $bucket
     * @return array|false
     */
    public function getObjectsByBucket($bucket)
    {
    }

    /**
     * Get an object
     *
     * @param  string $object
     * @return string|false
     */
    public function getObject($object)
    {
    }

    /**
     * Upload an object by a PHP string
     *
     * @param  string $object Object name
     * @param  string $data Object data
     * @param  [array] $meta Metadata
     * @return boolean
     */
    public function putObject($object, $data, $meta = null)
    {
    }

    /**
     * Put file to S3 as object
     *
     * @param string $path File name
     * @param string $object Object name
     * @param [array] $meta Metadata
     * @return boolean
     */
    public function putFile($path, $object, $meta=null)
    {
    }
    
    /**
     * Remove a given object
     *
     * @param  string $object
     * @return boolean
     */
    public function removeObject($object)
    {
    }

    /**
     * Make a request to Amazon S3
     *
     * TODO: support bucket.s3.amazon.com style
     * 
     * @param  string $method
     * @param  string $path
     * @param  array  $params
     * @param  array  $headers
     * @param  string $data
     * @return Zend_Http_Response
     */
    public function _makeRequest($method, $path='', $params=null, $headers=array(), $data=null)
    {
    }

    /**
     * Register this object as stream wrapper
     *
     * @param string $name
     */
    public function registerStreamWrapper($name="s3")
    {
    }
    
    /**
     * Unregister this object as stream wrapper
     *
     * @param string $name
     */
    public function unregisterStreamWrapper($name="s3")
    {
    }
}

class Zend_Service_Amazon_S3_Stream
{
    /**
     * @var boolean Write the buffer on fflush()?
     */
    private $_writeBuffer = false;

    /**
     * @var integer Current read/write position
     */
    private $_position = 0;

    /**
     * @var integer Total size of the object as returned by S3 (Content-length)
     */
    private $_objectSize = 0;

    /**
     * @var string File name to interact with
     */
    private $_objectName = null;

    /**
     * @var string Current read/write buffer
     */
    private $_objectBuffer = null;

    /**
     * @var array Available buckets
     */
    private $_bucketList = array();
    
    private $_s3;

    /**
     * Open the stream
     *
     * @param  string  $path
     * @param  string  $mode
     * @param  integer $options
     * @param  string  $opened_path
     * @return boolean
     */
    public function stream_open($path, $mode, $options, $opened_path)
    {
    }

    /**
     * Close the stream
     *
     * @return void
     */
    public function stream_close()
    {
    }

    /**
     * Read from the stream
     *
     * @param  integer $count
     * @return string
     */
    public function stream_read($count)
    {
    }

    /**
     * Write to the stream
     *
     * @param  string $data
     * @return integer
     */
    public function stream_write($data)
    {
    }

    /**
     * End of the stream?
     *
     * @return boolean
     */
    public function stream_eof()
    {
    }

    /**
     * What is the current read/write position of the stream
     *
     * @return integer
     */
    public function stream_tell()
    {
    }

    /**
     * Update the read/write position of the stream
     *
     * @param  integer $offset
     * @param  integer $whence
     * @return boolean
     */
    public function stream_seek($offset, $whence)
    {
    }

    /**
     * Flush current cached stream data to storage
     *
     * @return boolean
     */
    public function stream_flush()
    {
    }

    /**
     * Returns data array of stream variables
     *
     * @return array
     */
    public function stream_stat()
    {
    }

    /**
     * Attempt to delete the item
     *
     * @param  string $path
     * @return boolean
     */
    public function unlink($path)
    {
    }

    /**
     * Attempt to rename the item
     *
     * @param  string  $path_from
     * @param  string  $path_to
     * @return boolean False
     */
    public function rename($path_from, $path_to)
    {
    }

    /**
     * Create a new directory
     *
     * @param  string  $path
     * @param  integer $mode
     * @param  integer $options
     * @return boolean
     */
    public function mkdir($path, $mode, $options)
    {
    }

    /**
     * Remove a directory
     *
     * @param  string  $path
     * @param  integer $options
     * @return boolean
     */
    public function rmdir($path, $options)
    {
    }

    /**
     * Attempt to open a directory
     *
     * @param  string $path
     * @param  integer $options
     * @return boolean
     */
    public function dir_opendir($path, $options)
    {
    }

    /**
     * Return array of URL variables
     *
     * @param  string $path
     * @param  integer $flags
     * @return array
     */
    public function url_stat($path, $flags)
    {
    }

    /**
     * Return the next filename in the directory
     *
     * @return string
     */
    public function dir_readdir()
    {
    }

    /**
     * Reset the directory pointer
     *
     * @return boolean True
     */
    public function dir_rewinddir()
    {
    }

    /**
     * Close a directory
     *
     * @return boolean True
     */
    public function dir_closedir()
    {
    }
}

Page Operations

Browse Space

Zend_Service_Amazon_S3 - Justin Plock

Labels

Zend Framework: Zend_Service_Amazon_S3 Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria