View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFDEV:Zend Proposal Zone Template}

{zone-data:component-name}
Zend_Service_Amazon_S3
{zone-data}

{zone-data:proposer-list}
[Travis Swicegood|mailto:development@domain51.com]
[Darby Felton|mailto:darby@zend.com], Zend liaison
{zone-data}

{zone-data:revision}
1.0 - April 3, 2007: Initial draft completed
{zone-data}

{zone-data:overview}
Zend_Service_Amazon_S3 offers a PHP API to Amazon's Simple Storage Service (S3).
{zone-data}

{zone-data:references}
* [Amazon S3|http://www.amazon.com/gp/browse.html?node=16427261]
* [Current Domain51_Service_Amazon_S3 implementation for Solar|http://solarphp-domain51.googlecode.com/svn/trunk/Domain51/Service/Amazon/]
{zone-data}

{zone-data:requirements}
* This component *will* handle connectiosn to Amazon S3
* This component *will* handle creation, modification, and retrieval of S3 "buckets"
* This component *will* handle creation, modification, and retrieval of S3 "objects"
* This component *will* handle requests against S3's "service"
* This component *will* correctly generate a proper hash required to prove authorization to Amazon S3
{zone-data}

{zone-data:dependencies}
* Zend_Http_Client
{zone-data}

{zone-data:operation}

{zone-data}

{zone-data:milestones}

* Milestone 1: \[IN PROGRESS\]Finish creating outline document
* Milestone 2: Working code ported from Domain51_Service_Amazon_S3 to Zend_Service_Amazon_S3
* Milestone 3: Unit tests are ported from current code into existing code
* Milestone 4: Initial documentation exists.

{zone-data}

{zone-data:class-list}
* Zend_Service_Amazon_S3 (main entry point to API)
* Zend_Service_Amazon_S3_Exception
* Zend_Service_Amazon_S3_Bucket
* Zend_Service_Amazon_S3_Object
* Zend_Service_Amazon_S3_Service (possible - a list of all buckets owned by a user)
* Zend_Service_Amazon_S3_Connection
{zone-data}

{zone-data:use-cases}
||UC-01||
{code:php}
// create a bucket and echo out the list of objects in it
$s3 = new Zend_Service_Amazon_S3('accessKey', 'super-secret-hash');
$s3->bucket->put('/my-great-zend-powered-bucket');

var_dump($s3->bucket->get('/my-great-zend-powered-bucket'));

// only show three
var_dump($s3->bucket->get(
'/my-great-zend-powered-bucket',
array('max-keys' => 3)
));
{code}

||UC-02||
{code:php}
// put data in a public object and retrieve it
$s3 = new Zend_Service_Amazon_S3('accessKey', 'super-secret-hash');
$object = $s3->create('object');
$object->setFile('/path/to/file.txt');
$object->name = 'file.txt';
$object->bucket = 'my-great-zend-powered-bucket';
$object->headers['x-amx-acl'] = 'public-read';
$s3->object->put($object);

var_dump($s3->object->get('/my-great-zend-powered-bucket/file.txt'));
{code}

{zone-data}

{zone-data:skeletons}
{code}
<?php
class Zend_Service_Amazon_S3_Exception extends Zend_Exception {}

/**
* Provides an interface for connecting to and manipulating data on Amazon
* Web Service's S3
*
* @internal Implements Strategy pattern to return the appropriate object that is capable
* of performing the requested task.
*/
class Zend_Service_Amazon_S3 {
/**
* Handle instantiation of S3 object
*
* @param string $accessKeyId The access key ID from Amazon Web Services
*
* @param string $secret The secret provided from Amazon Web Services.
*
* @internal $secret is not stored in memory in this object, but instead is
* passed of to other objects that require it to create the proper hash.
* This is only used here to provide a single entry into the service.
*/
public function __construct($accessKeyId, $secret) { }

/**
* A factory for creating a PHP object that represents a certain type of data that
* S3 is aware of (buckets and objects).
*
* @param string $type
*
* @return Zend_Service_Amazon_S3_Value Returns a sub-class of Z_S_A_S3_Value.
*
* @todo Consider renaming to factory()?
*/
public function create($type) { }
}

/**
* Provides an interface for manipulating buckets
*
* @example
* $s3 = new Zend_Service_Amazon_S3('accessKey', 'secret');
* $s3->bucket->put('/my-bucket');
* $bucket = $s3->bucket->get('/my-bucket');
* $s3->bucket->delete('/my-bucket');
*
*/
class Zend_Service_Amazon_S3_Bucket {

/**
* Handle instantiation
*
* @param Zend_Service_Amazon_S3_Connection $connection
*/
public function __construct(Zend_Service_Amazon_S3_Connection $connection) {

}

/**
* Perform put action
*
* @param string $bucket Name of bucket
*
* @return bool
*/
public function put($bucket) {
assert('is_string($bucket)');
}

/**
* Retrieve a bucket, with optionally specified parameters
*
* @param string $bucket Name of bucket
* @param array $parameters Array of parameters to pass in to the request
*
* @return string Raw response body
*
* @todo Allow retrieval of bucket response into containers
*/
public function get($bucket, array $parameters = array()) {
assert('is_string($bucket)');
}

/**
* Delete a bucket
*
* @param string $bucket Name of bucket to delete
*
* @return bool Returns true regardless of actual success as S3 returns
* the same error code on success or failure
*/
public function delete($bucket) {
assert('is_string($bucket)');
}
}

/**
* Provide an interface into S3's objects
*/
class Zend_Service_Amazon_S3_Object {

/**
* Handle instantiation
*
* @param Zend_Service_Amazon_S3_Connection $connection
*/
public function __construct(Zend_Service_Amazon_S3_Connection $connection) {

}

/**
* Perform a put action on an object
*
* @param Zend_Service_Amazon_S3_Value_Object $object Object to store
*
* @return bool True on success
*/
public function put(Zend_Service_Amazon_S3_Value_Object $object) {

}

/**
* Retrieve an object
*
* @param string $path The path of a particular object
* @param array $parameters An associative array of extra parameters for the request
*
* @return Zend_Service_Amazon_S3_Value_Object
*/
public function get($path, array $parameters = array()) {
assert('is_string($path)');

}


/**
* Retrieve header information on an object
*
* @param string $path The path of a particular object
*
* @return array An associative array of header elements
*/
public function head($path) {
assert('is_string($path)');

}

/**
* Delete an object
*
* @param string $path Path of object to delete
*
* @return bool Returns true regardless of actual success as S3 returns
* the same error code on success or failure
*/
public function delete($path) {
assert('is_string($path)');
}
}

/**
* Provides an interface to S3's service requests
*/
class Zend_Service_Amazon_S3_Service {

/**
* Handle instantiation
*
* @param Zend_Service_Amazon_S3_Connection $connection
*/
public function __construct(Zend_Service_Amazon_S3_Connection $connection) {

}

/**
* Return an XML list of all of the buckets owned by the authenticated user
*
* @return string
*/
public function get() {

}
}

/**
* Provides a basic wrapper for Objects to be stored on S3
*/
class Zend_Service_Amazon_S3_Value_Object {

/**
* Set the file path of this object
*
* @param string $file An existing and readable file
*/
public function setFilePath($file) {
assert('file_exists($file)');
assert('is_readable($file)');

}

/**
* Allow setting of properties
*
* Intercepts all "bucket" properties and insures there is a trailing slash
*
* Intercepts request for "fullName" and throws an exception as a reserved word
*
* @param string $key Key to set
* @param string $value Value to set to
*/
public function __set($key, $value) {

}

/**
* Returns properties
*
* Intercepts request for "fullName" and creates it from combining the "bucket"
* and "name" properties.
*
* @param string $key Key of value to return
*
* @return mixed
*/
public function __get($key) {

}
}

/**
* This object creates and maintains the connection and communication with Amazon's S3
* servers.
*
* @see Zend_Http_Client, Zend_Service_Amazon_S3_Authorization
*/
class Zend_Service_Amazon_S3_Connection {
/**
* Handle instantiation
*
* @param string $accessKeyId Amazon provided access key
* @param string $secret Amazon provide secret key
*/
public function __construct($accessKeyId, $secret) { }

/**
* Send actual request to S3 server
*
* @param string $type The type of request (HEAD, GET, PUT, DELETE)
* @param string $uri The URI of the requested file
* @param string $body Optionally, the body of the request when sending data
*/
public function doRequest($type, $uri, $body = '') {
assert('in_array($type, array("HEAD", "GET", "PUT", "DELETE"))');
}
}

/**
* This object contains the headers associated with a particular request
*
* @see Zend_Service_Amazon_S3_Connection
*
* @todo Should this extend from more generic object (i.e., Zend_Http_HeaderList)?
*/
class Zend_Service_Amazon_S3_Connection_Header {
public function __construct() { }

/**
* Returns an array of all headers, or optionally just the X-Amz headers
*
* @param bool $amzOnly If true, return only X-Amz headers
* @return array
*/
public function toArray($amzOnly = false) {
assert('is_bool($amzOnly)');
}

/**
* Set the the "verb" on the request, GET, POST, PUT, DELETE, etc.
*
* @param string $type
*
* @todo Rename "Type" to "Verb"?
*/
public function setType($type) {
assert('in_array($type, array("HEAD", "GET", "PUT", "DELETE"))');
}

/**
* Return the set type
*
* @return string
*/
public function getType() { }

/**
* Add a particular header
*
* @param string $key
*
* @param string $value
*/
public function add($key, $value) { }

/**
* Retrieve a particular header
*
* @param string $key
*
* @return string
*/
public function get($key) { }

/**
* Set the URL portion of the header request
*
* @param string $url
*/
public function setUrl($url) { }

/**
* Return the currently set URL
*
* @return string
*/
public function getUrl() { }

/**
* AWS specific
*/

/**
* Add an AMZ specific header.
*
* @internal Prefix the $key with 'X-Amz-'
*
* @param string $key
*
* @param string $value
*/
public function addAmz($key, $value) { }

/**
* Retrieve an AMZ specific header.
*
* @internal Prefix $key with 'X-Amz' and pass it to {@link get()}
*
* @return string
*/
public function getAmz($key) { }
}

/**
* This object generates the authorization header for connecting to S3
*
* @see Zend_Service_Amazon_S3_Connection
*/
class Zend_Service_Amazon_S3_Connection_Authorization {
public function __construct(Zend_Service_Amazon_S3_Connection_Header $header, $accessKeyId) { }

/**
* Returns the full value of the Authorization header (i.e., "AWS{$accessKeyId}:{this->hash()}")
*
* @return string
*/
public function generate() { }

/**
* Returns the hash portion of the Authorization header
*
* @return string
*/
public function hash() { }
}
?>
{code}
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>