stackforge
/
openstack-sdk-php
Code Issues Proposed changes

Merge "Object Storage directory has been converted from doxygen to PHPDoc. Partially implements blueprint phpdoc."

This commit is contained in:
Jenkins 2014-04-07 18:46:24 +00:00 committed by Gerrit Code Review
parent e74180781b bf922f3abd
commit 38ae1ae3e8
11 changed files with 668 additions and 958 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
src/OpenStack/Storage/ObjectStorage.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* This file provides the ObjectStorage class, which is the primary
* representation of the ObjectStorage system.
*
@ -39,7 +37,7 @@ use OpenStack\Storage\ObjectStorage\ACL;
*
* There is also a stream wrapper interface that exposes ObjectStorage
* to PHP's streams system. For common use of an object store, you may
* prefer to use that system. (See OpenStack::Bootstrap).
* prefer to use that system. (@see \OpenStack\Bootstrap).
*
* When constructing a new ObjectStorage object, you will need to know
* what kind of authentication you are going to perform. Older
@ -47,8 +45,8 @@ use OpenStack\Storage\ObjectStorage\ACL;
* mechanism for Swift. You can use ObjectStorage::newFromSwiftAuth() to
* perform this type of authentication.
*
* Newer versions use the IdentityServices authentication mechanism (see
* OpenStack::Services::IdentityServices). That method is the preferred
* Newer versions use the IdentityServices authentication mechanism (@see
* \OpenStack\Services\IdentityServices). That method is the preferred
* method.
*
* Common Tasks
@ -87,7 +85,7 @@ class ObjectStorage {
* Create a new instance after getting an authenitcation token.
*
* THIS METHOD IS DEPRECATED. OpenStack now uses Keyston to authenticate.
* You should use OpenStack::Services::IdentityServices to authenticate.
* You should use \OpenStack\Services\IdentityServices to authenticate.
* Then use this class's constructor to create an object.
*
* This uses the legacy Swift authentication facility to authenticate
@ -102,18 +100,15 @@ class ObjectStorage {
* - Key: Typically this will be your password.
* - Endpoint URL: The URL given to you by your service provider.
*
* @param string $account
* Your account name.
* @param string $key
* Your secret key.
* @param string $url
* The URL to the object storage endpoint.
* @param string $account Your account name.
* @param string $key Your secret key.
* @param string $url The URL to the object storage endpoint.
*
* @throws OpenStack::Transport::AuthorizationException if the
* @throws \OpenStack\Transport\AuthorizationException if the
* authentication failed.
* @throws OpenStack::Transport::FileNotFoundException if the URL is
* @throws \OpenStack\Transport\FileNotFoundException if the URL is
* wrong.
* @throws OpenStack::Exception if some other exception occurs.
* @throws \OpenStack\Exception if some other exception occurs.
*
* @deprecated Newer versions of OpenStack use Keystone auth instead
* of Swift auth.
@ -151,14 +146,12 @@ class ObjectStorage {
* Given an IdentityServices instance, create an ObjectStorage instance.
*
* This constructs a new ObjectStorage from an authenticated instance
* of an OpenStack::Services::IdentityServices object.
* of an \OpenStack\Services\IdentityServices object.
*
* @param OpenStack::Services::IdentityServices $identity
* An identity services object that already has a valid token and a
* service catalog.
* @retval OpenStack::Storage::ObjectStorage
* @return \OpenStack\Storage\ObjectStorage
* A new ObjectStorage instance.
* @param \OpenStack\Services\IdentityServices $identity An identity services
* object that already has a valid token and a service catalog.
*
* @return \OpenStack\Storage\ObjectStorage A new ObjectStorage instance.
*/
public static function newFromIdentity($identity, $region = ObjectStorage::DEFAULT_REGION) {
$cat = $identity->serviceCatalog();
@ -175,15 +168,12 @@ class ObjectStorage {
* This builder can scan the catalog and generate a new ObjectStorage
* instance pointed to the first object storage endpoint in the catalog.
*
* @param array $catalog
* The serice catalog from IdentityServices::serviceCatalog(). This
* can be either the entire catalog or a catalog filtered to
* just ObjectStorage::SERVICE_TYPE.
* @param string $authToken
* The auth token returned by IdentityServices.
* @retval OpenStack::Storage::ObjectStorage
* @return \OpenStack\Storage\ObjectStorage
* A new ObjectStorage instance.
* @param array $catalog The serice catalog from IdentityServices::serviceCatalog().
* This can be either the entire catalog or a catalog filtered to just
* ObjectStorage::SERVICE_TYPE.
* @param string $authToken The auth token returned by IdentityServices.
*
* @return \OpenStack\Storage\ObjectStorage A new ObjectStorage instance.
*/
public static function newFromServiceCatalog($catalog, $authToken, $region = ObjectStorage::DEFAULT_REGION) {
$c = count($catalog);
@ -207,12 +197,10 @@ class ObjectStorage {
*
* Use this if newFromServiceCatalog() does not meet your needs.
*
* @param string $authToken
* A token that will be included in subsequent requests to validate
* that this client has authenticated correctly.
* @param string $url
* The URL to the endpoint. This typically is returned after
* authentication.
* @param string $authToken A token that will be included in subsequent
* requests to validate that this client has authenticated correctly.
* @param string $url The URL to the endpoint. This typically is returned
* after authentication.
*/
public function __construct($authToken, $url) {
$this->token = $authToken;
@ -222,9 +210,7 @@ class ObjectStorage {
/**
* Get the authentication token.
*
* @retval string
* @return string
* The authentication token.
* @return string The authentication token.
*/
public function token() {
return $this->token;
@ -233,9 +219,7 @@ class ObjectStorage {
/**
* Get the URL endpoint.
*
* @retval string
* @return string
* The URL that is the endpoint for this service.
* @return string The URL that is the endpoint for this service.
*/
public function url() {
return $this->url;
@ -263,20 +247,15 @@ class ObjectStorage {
* requested, it makes an additional round-trip to the server to
* fetch that data.
*
* @param int $limit
* The maximum number to return at a time. The default is -- brace
* yourself -- 10,000 (as determined by OpenStack. Implementations
* @param int $limit The maximum number to return at a time. The default is
* -- brace yourself -- 10,000 (as determined by OpenStack. Implementations
* may vary).
* @param string $marker
* The name of the last object seen. Used when paging.
* @param string $marker The name of the last object seen. Used when paging.
*
* @retval array
* @return array
* An associative array of containers, where the key is the
* container's name and the value is an
* OpenStack::Storage::ObjectStorage::Container object. Results are
* ordered in server order (the order that the remote host puts them
* in).
* @return array An associative array of containers, where the key is the
* container's name and the value is an \OpenStack\Storage\ObjectStorage\Container
* object. Results are ordered in server order (the order that the remote
* host puts them in).
*/
public function containers($limit = 0, $marker = NULL) {
@ -305,13 +284,11 @@ class ObjectStorage {
*
* This loads only the named container from the remote server.
*
* @param string $name
* The name of the container to load.
* @retval OpenStack::Storage::ObjectStorage::Container
* @return \OpenStack\Storage\ObjectStorage\Container
* A container.
* @throws OpenStack::Transport::FileNotFoundException
* if the named container is not found on the remote server.
* @param string $name The name of the container to load.
*
* @return \OpenStack\Storage\ObjectStorage\Container A container.
* @throws \OpenStack\Transport\FileNotFoundException if the named container
* is not found on the remote server.
*/
public function container($name) {
@ -332,17 +309,14 @@ class ObjectStorage {
/**
* Check to see if this container name exists.
*
* This method directly checks the remote server. Calling container()
* or containers() might be more efficient if you plan to work with
* This method directly checks the remote server. Calling container()
* or containers() might be more efficient if you plan to work with
* the resulting container.
*
* @param string $name
* The name of the container to test.
* @retval boolean
* @return boolean
* TRUE if the container exists, FALSE if it does not.
* @throws OpenStack::Exception
* If an unexpected network error occurs.
* @param string $name The name of the container to test.
*
* @return boolean TRUE if the container exists, FALSE if it does not.
* @throws \OpenStack\Exception If an unexpected network error occurs.
*/
public function hasContainer($name) {
try {
@ -373,8 +347,8 @@ class ObjectStorage {
* ACLs
*
* Swift supports an ACL stream that allows for specifying (with
* certain caveats) various levels of read and write access. However,
* there are two standard settings that cover the vast majority of
* certain caveats) various levels of read and write access. However,
* there are two standard settings that cover the vast majority of
* cases.
*
* - Make the resource private: This grants read and write access to
@ -388,34 +362,29 @@ class ObjectStorage {
* container public will allow access to ALL objects inside of the
* container.
*
* To find out whether an existing container is public, you can
* To find out whether an existing container is public, you can
* write something like this:
*
* @code
* <?php
* // Get the container.
* $container = $objectStorage->container('my_container');
* <?php
* // Get the container.
* $container = $objectStorage->container('my_container');
*
* //Check the permission on the ACL:
* $boolean = $container->acl()->isPublic();
* ?>
* @endcode
* //Check the permission on the ACL:
* $boolean = $container->acl()->isPublic();
* ?>
*
* For details on ACLs, see OpenStack::Storage::ObjectStorage::ACL.
* For details on ACLs, see \OpenStack\Storage\ObjectStorage\ACL.
*
* @param string $name
* The name of the container.
* @param object $acl OpenStack::Storage::ObjectStorage::ACL
* An access control list object. By default, a container is
* non-public (private). To change this behavior, you can add a
* custom ACL. To make the container publically readable, you can
* use this: OpenStack::Storage::ObjectStorage::ACL::makePublic().
* @param array $metadata
* An associative array of metadata to attach to the container.
* @retval boolean
* @return boolean
* TRUE if the container was created, FALSE if the container was not
* created because it already exists.
* @param string $name The name of the container.
* @param object $acl \OpenStack\Storage\ObjectStorage\ACL An access control
* list object. By default, a container is non-public (private). To change
* this behavior, you can add a custom ACL. To make the container publically
* readable, you can use this: \OpenStack\Storage\ObjectStorage\ACL::makePublic().
* @param array $metadata An associative array of metadata to attach to the
* container.
*
* @return boolean TRUE if the container was created, FALSE if the container
* was not created because it already exists.
*/
public function createContainer($name, ACL $acl = NULL, $metadata = array()) {
$url = $this->url() . '/' . rawurlencode($name);
@ -471,14 +440,11 @@ class ObjectStorage {
* implementation, which uses the same HTTP verb to create a container
* and to set the ACL.)
*
* @param string $name
* The name of the container.
* @param object $acl OpenStack::Storage::ObjectStorage::ACL
* An ACL. To make the container publically readable, use
* ACL::makePublic().
* @retval boolean
* @return boolean
* TRUE if the cointainer was created, FALSE otherwise.
* @param string $name The name of the container.
* @param object $acl \OpenStack\Storage\ObjectStorage\ACL An ACL. To make the
* container publically readable, use ACL::makePublic().
*
* @return boolean TRUE if the cointainer was created, FALSE otherwise.
*/
public function changeContainerACL($name, ACL $acl) {
// Oddly, the way to change an ACL is to issue the
@ -493,18 +459,16 @@ class ObjectStorage {
* the object storage.
*
* The container MUST be empty before it can be deleted. If it is not,
* an OpenStack::Storage::ObjectStorage::ContainerNotEmptyException will
* an \OpenStack\Storage\ObjectStorage\ContainerNotEmptyException will
* be thrown.
*
* @param string $name
* The name of the container.
* @retval boolean
* @return boolean
* TRUE if the container was deleted, FALSE if the container was not
* found (and hence, was not deleted).
* @throws OpenStack::Storage::ObjectStorage::ContainerNotEmptyException
* @param string $name The name of the container.
*
* @return boolean TRUE if the container was deleted, FALSE if the container
* was not found (and hence, was not deleted).
* @throws \OpenStack\Storage\ObjectStorage\ContainerNotEmptyException
* if the container is not empty.
* @throws OpenStack::Exception if an unexpected response code is returned.
* @throws \OpenStack\Exception if an unexpected response code is returned.
* While this should never happen on OpenStack servers, forks of
* OpenStack may choose to extend object storage in a way that
* results in a non-standard code.
@ -545,14 +509,12 @@ class ObjectStorage {
* - The total bytes used by this Object Storage instance (`bytes`).
* - The number of containers (`count`).
*
* @retval array
* @return array
* An associative array of account info. Typical keys are:
* @return array An associative array of account info. Typical keys are:
* - bytes: Bytes consumed by existing content.
* - containers: Number of containers.
* - objects: Number of objects.
* @throws OpenStack::Transport::AuthorizationException
* if the user credentials are invalid or have expired.
* @throws \OpenStack\Transport\AuthorizationException if the user credentials
* are invalid or have expired.
*/
public function accountInfo() {
$url = $this->url();

176
src/OpenStack/Storage/ObjectStorage/ACL.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* Contains the class for manipulating ObjectStorage ACL strings.
*/
@ -25,7 +23,7 @@ namespace OpenStack\Storage\ObjectStorage;
/**
* Access control list for object storage.
*
* @b EXPERIMENTAL: This is bassed on a feature of Swift that is likely to
* EXPERIMENTAL: This is bassed on a feature of Swift that is likely to
* change. Most of this is based on undocmented features of the API
* discovered both in the Python docs and in discussions by various
* members of the OpenStack community.
@ -38,63 +36,56 @@ namespace OpenStack\Storage\ObjectStorage;
* In the current implementation of Swift, access can be assigned based
* on two different factors:
*
* - @b Accounts: Access can be granted to specific accounts, and within
* - Accounts: Access can be granted to specific accounts, and within
* those accounts, can be further specified to specific users. See the
* addAccount() method for details on this.
* - @b Referrers: Access can be granted based on host names or host name
* patterns. For example, only subdomains of <tt>*.example.com</tt> may be
* - Referrers: Access can be granted based on host names or host name
* patterns. For example, only subdomains of *.example.com may be
* granted READ access to a particular object.
*
* ACLs are transmitted within the HTTP headers for an object or
* container. Two headers are used: @c X-Container-Read for READ rules, and
* @c X-Container-Write for WRITE rules. Each header may have a chain of
* container. Two headers are used: `X-Container-Read` for READ rules, and
* `X-Container-Write` for WRITE rules. Each header may have a chain of
* rules.
*
* @b Examples
* Examples
*
* For most casual cases, only the static constructor functions are
* used. For example, an ACL that does not grant any public access can
* be created with a single call:
*
* @code
* <?php
* $acl = ACL::makeNonPublic();
* ?>
* @endcode
* <?php
* $acl = ACL::makeNonPublic();
* ?>
*
* Public read access is granted like this:
*
* @code
* <?php
* $acl = ACL::makePublic();
* ?>
* @endcode
* <?php
* $acl = ACL::makePublic();
* ?>
*
* (Note that in both cases, what is returned is an instance of an ACL with
* all of the necessary configuration done.)
*
* Sometimes you will need more sophisticated access control rules. The
* following grants READ access to anyone coming from an @c example.com
* domain, but grants WRITE access only to the account @c admins:
* following grants READ access to anyone coming from an `example.com`
* domain, but grants WRITE access only to the account `admins:`
*
* @code
* <?php
* $acl = new ACL();
* <?php
* $acl = new ACL();
*
* // Grant READ to example.com users.
* $acl->addReferrer(ACL::READ, '*.example.com');
* // Grant READ to example.com users.
* $acl->addReferrer(ACL::READ, '*.example.com');
*
* // Allow only people in the account 'admins' access to
* // write.
* $acl->addAccount(ACL::WRITE, 'admins');
* // Allow only people in the account 'admins' access to
* // write.
* $acl->addAccount(ACL::WRITE, 'admins');
*
* // Allow example.com users to view the container
* // listings:
* $acl->allowListings();
*
* ?>
* @endcode
* // Allow example.com users to view the container
* // listings:
* $acl->allowListings();
*
* ?>
*
* Notes
*
@ -105,7 +96,7 @@ namespace OpenStack\Storage\ObjectStorage;
* replaced by a new mechanism.
*
* For a detailed description of the rules for ACL creation,
* see http://swift.openstack.org/misc.html#acls
* @see http://swift.openstack.org/misc.html#acls
*/
class ACL {
@ -124,7 +115,7 @@ class ACL {
/**
* Flag for READ and WRITE.
*
* This is equivalent to <tt>ACL::READ | ACL::WRITE</tt>
* This is equivalent to `ACL::READ | ACL::WRITE`
*/
const READ_WRITE = 3; // self::READ | self::WRITE;
@ -146,9 +137,8 @@ class ACL {
*
* - READ to any host, with container listings.
*
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* an ACL object with the appopriate permissions set.
* @return \OpenStack\Storage\ObjectStorage\ACL an ACL object with the
* appopriate permissions set.
*/
public static function makePublic() {
$acl = new ACL();
@ -167,9 +157,8 @@ class ACL {
* This does not grant any permissions. OpenStack interprets an object
* with no permissions as a private object.
*
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* an ACL object with the appopriate permissions set.
* @return \OpenStack\Storage\ObjectStorage\ACL an ACL object with the
* appopriate permissions set.
*/
public static function makeNonPublic() {
// Default ACL is private.
@ -189,11 +178,9 @@ class ACL {
* This is a utility for processing headers and discovering any ACLs embedded
* inside the headers.
*
* @param array $headers
* An associative array of headers.
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* A new ACL.
* @param array $headers An associative array of headers.
*
* @return \OpenStack\Storage\ObjectStorage\ACL A new ACL.
*/
public static function newFromHeaders($headers) {
$acl = new ACL();
@ -235,13 +222,10 @@ class ACL {
* This attempts to parse an ACL rule. It is not particularly
* fault-tolerant.
*
* @param int $perm
* The permission (ACL::READ, ACL::WRITE).
* @param string $rule
* The string rule to parse.
* @retval array
* @return array
* The rule as an array.
* @param int $perm The permission (ACL::READ, ACL::WRITE).
* @param string $rule The string rule to parse.
*
* @return array The rule as an array.
*/
public static function parseRule($perm, $rule) {
// This regular expression generates the following:
@ -304,24 +288,20 @@ class ACL {
*
* If $user is an array, every user in the array will be granted
* access under the provided account. That is, for each user in the
* array, an entry of the form \c account:user will be generated in the
* array, an entry of the form `account:user` will be generated in the
* final ACL.
*
* At this time there does not seem to be a way to grant global write
* access to an object.
*
* @param int $perm
* ACL::READ, ACL::WRITE or ACL::READ_WRITE (which is the same as
* ACL::READ|ACL::WRITE).
* @param string $account
* The name of the account.
* @param mixed $user
* The name of the user, or optionally an indexed array of user
* names.
* @param int $perm ACL::READ, ACL::WRITE or ACL::READ_WRITE (which is the
* same as ACL::READ|ACL::WRITE).
* @param string $account The name of the account.
* @param mixed $user The name of the user, or optionally an indexed array of
* user names.
*
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* $this for current object so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\ACL $this for current object so
* the method can be used in chaining.
*/
public function addAccount($perm, $account, $user = NULL) {
$rule = array('account' => $account);
@ -351,14 +331,12 @@ class ACL {
* Note that a simple minus sign ('-') is illegal, though it seems it
* should be "disallow all hosts."
*
* @param string $perm
* The permission being granted. One of ACL:READ, ACL::WRITE, or ACL::READ_WRITE.
* @param string $host
* A host specification string as described above.
* @param string $perm The permission being granted. One of ACL:READ,
* ACL::WRITE, or ACL::READ_WRITE.
* @param string $host A host specification string as described above.
*
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* $this for current object so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\ACL $this for current object so
* the method can be used in chaining.
*/
public function addReferrer($perm, $host = '*') {
$this->addRule($perm, array('host' => $host));
@ -369,14 +347,11 @@ class ACL {
/**
* Add a rule to the appropriate stack of rules.
*
* @param int $perm
* One of the predefined permission constants.
* @param array $rule
* A rule array.
*
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* $this for current object so the method can be used in chaining.
* @param int $perm One of the predefined permission constants.
* @param array $rule A rule array.
*
* @return \OpenStack\Storage\ObjectStorage\ACL $this for current object so
* the method can be used in chaining.
*/
protected function addRule($perm, $rule) {
$rule['mask'] = $perm;
@ -397,9 +372,8 @@ class ACL {
* In the current Swift implementation, there is no mechanism for
* allowing some hosts to get listings, while denying others.
*
* @retval OpenStack::Storage::ObjectStorage::ACL
* @return \OpenStack\Storage\ObjectStorage\ACL
* $this for current object so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\ACL $this for current object so
* the method can be used in chaining.
*/
public function allowListings() {
@ -414,9 +388,7 @@ class ACL {
/**
* Get the rules array for this ACL.
*
* @retval array
* @return array
* An array of associative arrays of rules.
* @return array An array of associative arrays of rules.
*/
public function rules() {
return $this->rules;
@ -427,6 +399,8 @@ class ACL {
*
* If this is called on an empty object, an empty set of headers is
* returned.
*
* @return array Array of headers
*/
public function headers() {
$headers = array();
@ -467,10 +441,8 @@ class ACL {
/**
* Convert a rule to a string.
*
* @param int $perm
* The permission for which to generate the rule.
* @param array $rule
* A rule array.
* @param int $perm The permission for which to generate the rule.
* @param array $rule A rule array.
*/
protected function ruleToString($perm, $rule) {
@ -519,10 +491,8 @@ class ACL {
* This returns TRUE only if this ACL does not grant any permissions
* at all.
*
* @retval boolean
* @return boolean
* TRUE if this is private (non-public), FALSE if
* any permissions are granted via this ACL.
* @return boolean TRUE if this is private (non-public), FALSE if any
* permissions are granted via this ACL.
*/
public function isNonPublic() {
return empty($this->rules);
@ -544,7 +514,9 @@ class ACL {
* This checks whether the object allows public reading,
* not whether it is ONLY allowing public reads.
*
* See ACL::makePublic().
* @see ACL::makePublic().
*
* @return boolean Whether or not the object allows public reading.
*/
public function isPublic() {
$allowsAllHosts = FALSE;
@ -563,14 +535,12 @@ class ACL {
}
/**
* Implements the magic __toString() PHP function.
* Implements the magic `__toString()` PHP function.
*
* This allows you to <tt>print $acl</tt> and get back
* This allows you to `print $acl` and get back
* a pretty string.
*
* @retval string
* @return string
* The ACL represented as a string.
* @return string The ACL represented as a string.
*/
public function __toString() {
$headers = $this->headers();
@ -583,4 +553,4 @@ class ACL {
return implode("\t", $buffer);
}
}
}

376
src/OpenStack/Storage/ObjectStorage/Container.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* Contains the class for ObjectStorage Container objects.
*/
@ -37,28 +35,26 @@ namespace OpenStack\Storage\ObjectStorage;
* They are retrieved using ObjectStorage::container() or
* ObjectStorage::containers().
*
* @code
* <?php
* use \OpenStack\Storage\ObjectStorage;
* use \OpenStack\Storage\ObjectStorage\Container;
* use \OpenStack\Storage\ObjectStorage\Object;
* <?php
* use \OpenStack\Storage\ObjectStorage;
* use \OpenStack\Storage\ObjectStorage\Container;
* use \OpenStack\Storage\ObjectStorage\Object;
*
* // Create a new ObjectStorage instance, logging in with older Swift
* // credentials.
* $store = ObjectStorage::newFromSwiftAuth('user', 'key', 'http://example.com');
* // Create a new ObjectStorage instance, logging in with older Swift
* // credentials.
* $store = ObjectStorage::newFromSwiftAuth('user', 'key', 'http://example.com');
*
* // Get the container called 'foo'.
* $container = $store->container('foo');
* // Get the container called 'foo'.
* $container = $store->container('foo');
*
* // Create an object.
* $obj = new Object('bar.txt');
* $obj->setContent('Example content.', 'text/plain');
* // Create an object.
* $obj = new Object('bar.txt');
* $obj->setContent('Example content.', 'text/plain');
*
* // Save the new object in the container.
* $container->save($obj);
* // Save the new object in the container.
* $container->save($obj);
*
* ?>
* @endcode
* ?>
*
* Once you have a Container, you manipulate objects inside of the
* container.
@ -92,16 +88,13 @@ class Container implements \Countable, \IteratorAggregate {
*
* This is used when storing an object in a container.
*
* @param array $metadata
* An associative array of metadata. Metadata is not escaped in any
* way (there is no codified spec by which to escape), so make sure
* that keys are alphanumeric (dashes allowed) and values are
* @param array $metadata An associative array of metadata. Metadata is not
* escaped in any way (there is no codified spec by which to escape), so
* make sure that keys are alphanumeric (dashes allowed) and values are
* ASCII-armored with no newlines.
* @param string $prefix
* A prefix for the metadata headers.
* @retval array
* @return array
* An array of headers.
* @param string $prefix A prefix for the metadata headers.
*
* @return array An array of headers.
* @see http://docs.openstack.org/bexar/openstack-object-storage/developer/content/ch03s03.html#d5e635
* @see http://docs.openstack.org/bexar/openstack-object-storage/developer/content/ch03s03.html#d5e700
*/
@ -124,19 +117,15 @@ class Container implements \Countable, \IteratorAggregate {
* (namely slashes (`/`)) that are normally URLencoded when they appear
* inside of path sequences.
*
* @note
* Swift does not distinguish between @c %2F and a slash character, so
* Swift does not distinguish between `%2F` and a slash character, so
* this is not strictly necessary.
*
* @param string $base
* The base URL. This is not altered; it is just prepended to
* the returned string.
* @param string $oname
* The name of the object.
* @retval string
* @return string
* The URL to the object. Characters that need escaping will be escaped,
* while slash characters are not. Thus, the URL will look pathy.
* @param string $base The base URL. This is not altered; it is just prepended
* to the returned string.
* @param string $oname The name of the object.
*
* @return string The URL to the object. Characters that need escaping will be
* escaped, while slash characters are not. Thus, the URL will look pathy.
*/
public static function objectUrl($base, $oname) {
if (strpos($oname, '/') === FALSE) {
@ -152,7 +141,6 @@ class Container implements \Countable, \IteratorAggregate {
return $base . '/' . $newname;
}
/**
* Extract object attributes from HTTP headers.
*
@ -166,13 +154,10 @@ class Container implements \Countable, \IteratorAggregate {
* value data, so it is left up to implementors to choose their own
* strategy.
*
* @param array $headers
* An associative array of HTTP headers.
* @param string $prefix
* The prefix on metadata headers.
* @retval array
* @return array
* An associative array of name/value attribute pairs.
* @param array $headers An associative array of HTTP headers.
* @param string $prefix The prefix on metadata headers.
*
* @return array An associative array of name/value attribute pairs.
*/
public static function extractHeaderAttributes($headers, $prefix = NULL) {
if (empty($prefix)) {
@ -197,17 +182,13 @@ class Container implements \Countable, \IteratorAggregate {
* This is used in lieue of a standard constructor when
* fetching containers from ObjectStorage.
*
* @param array $jsonArray
* An associative array as returned by json_decode($foo, TRUE);
* @param string $token
* The auth token.
* @param string $url
* The base URL. The container name is automatically appended to
* this at construction time.
* @param array $jsonArray An associative array as returned by
* json_decode($foo, TRUE);
* @param string $token The auth token.
* @param string $url The base URL. The container name is automatically
* appended to this at construction time.
*
* @retval OpenStack::Storage::ObjectStorage::Comtainer
* @return \OpenStack\Storage\ObjectStorage\Container
* A new container object.
* @return \OpenStack\Storage\ObjectStorage\Container A new container object.
*/
public static function newFromJSON($jsonArray, $token, $url) {
$container = new Container($jsonArray['name']);
@ -240,18 +221,14 @@ class Container implements \Countable, \IteratorAggregate {
* cases, the standard constructor is preferred for client-size
* Container initialization.
*
* @param string $name
* The name of the container.
* @param object $response OpenStack::Transport::Response
* The HTTP response object from the Transporter layer
* @param string $token
* The auth token.
* @param string $url
* The base URL. The container name is automatically appended to
* this at construction time.
* @retval OpenStack::Storage::ObjectStorage::Container
* @return \OpenStack\Storage\ObjectStorage\Container
* The Container object, initialized and ready for use.
* @param string $name The name of the container.
* @param object $response \OpenStack\Transport\Response The HTTP response object from the Transporter layer
* @param string $token The auth token.
* @param string $url The base URL. The container name is automatically
* appended to this at construction time.
*
* @return \OpenStack\Storage\ObjectStorage\Container The Container object,
* initialized and ready for use.
*/
public static function newFromResponse($name, $response, $token, $url) {
$container = new Container($name);
@ -273,7 +250,6 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Construct a new Container.
*
* @attention
* Typically a container should be created by ObjectStorage::createContainer().
* Get existing containers with ObjectStorage::container() or
* ObjectStorage::containers(). Using the constructor directly has some
@ -307,13 +283,9 @@ class Container implements \Countable, \IteratorAggregate {
* - When in doubt, use the ObjectStorage methods. That is always the safer
* option.
*
* @param string $name
* The name.
* @param string $url
* The full URL to the container.
* @param string $token
* The auth token.
*
* @param string $name The name.
* @param string $url The full URL to the container.
* @param string $token The auth token.
*/
public function __construct($name , $url = NULL, $token = NULL) {
$this->name = $name;
@ -324,9 +296,7 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Get the name of this container.
*
* @retval string
* @return string
* The name of the container.
* @return string The name of the container.
*/
public function name() {
return $this->name;
@ -335,9 +305,7 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Get the number of bytes in this container.
*
* @retval int
* @return int
* The number of bytes in this container.
* @return int The number of bytes in this container.
*/
public function bytes() {
if (is_null($this->bytes)) {
@ -361,9 +329,7 @@ class Container implements \Countable, \IteratorAggregate {
* listings do not supply the metadata, while loading a container
* directly does.
*
* @retval array
* @return array
* An array of metadata name/value pairs.
* @return array An array of metadata name/value pairs.
*/
public function metadata() {
@ -374,7 +340,6 @@ class Container implements \Countable, \IteratorAggregate {
return $this->metadata;
}
/**
* Set the tags on the container.
*
@ -393,9 +358,8 @@ class Container implements \Countable, \IteratorAggregate {
* more than 256. UTF-8 or ASCII characters are allowed, though ASCII
* seems to be preferred.
*
* @retval OpenStack::Storage::ObjectStorage::Container
* @return \OpenStack\Storage\ObjectStorage\Container
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Container $this so the method can
* be used in chaining.
*/
public function setMetadata($metadata) {
$this->metadata = $metadata;
@ -406,18 +370,14 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Get the number of items in this container.
*
* Since Container implements Countable, the PHP builtin
* count() can be used on a Container instance:
* Since Container implements Countable, the PHP builtin count() can be used
* on a Container instance:
*
* @code
* <?php
* count($container) === $container->count();
* ?>
* @endcode
* <?php
* count($container) === $container->count();
* ?>
*
* @retval int
* @return int
* The number of items in this container.
* @return int The number of items in this container.
*/
public function count() {
if (is_null($this->count)) {
@ -429,28 +389,24 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Save an Object into Object Storage.
*
* This takes an OpenStack::Storage::ObjectStorage::Object
* This takes an \OpenStack\Storage\ObjectStorage\Object
* and stores it in the given container in the present
* container on the remote object store.
*
* @param object $obj OpenStack::Storage::ObjectStorage::Object
* The object to store.
* @param resource $file
* An optional file argument that, if set, will be treated as the
* contents of the object.
* @retval boolean
* @return boolean
* TRUE if the object was saved.
* @throws OpenStack::Transport::LengthRequiredException
* if the Content-Length could not be determined and chunked
* encoding was not enabled. This should not occur for this class,
* which always automatically generates Content-Length headers.
* However, subclasses could generate this error.
* @throws OpenStack::Transport::UnprocessableEntityException
* if the checksome passed here does not match the checksum
* calculated remotely.
* @throws OpenStack::Exception when an unexpected (usually
* network-related) error condition arises.
* @param object $obj \OpenStack\Storage\ObjectStorage\Object The object to
* store.
* @param resource $file An optional file argument that, if set, will be
* treated as the contents of the object.
*
* @return boolean TRUE if the object was saved.
* @throws \OpenStack\Transport\LengthRequiredException if the Content-Length
* could not be determined and chunked encoding was not enabled. This should
* not occur for this class, which always automatically generates
* Content-Length headers. However, subclasses could generate this error.
* @throws \OpenStack\Transport\UnprocessableEntityException if the checksum
* passed here does not match the checksum calculated remotely.
* @throws \OpenStack\Exception when an unexpected (usually network-related)
* error condition arises.
*/
public function save(Object $obj, $file = NULL) {
@ -555,15 +511,12 @@ class Container implements \Countable, \IteratorAggregate {
* particularly in cases where custom headers have been set.
* Use with caution.
*
* @param object $obj OpenStack::Storage::ObjectStorage::Object
* The object to update.
* @param object $obj \OpenStack\Storage\ObjectStorage\Object The object to
* update.
*
* @retval boolean
* @return boolean
* TRUE if the metadata was updated.
*
* @throws OpenStack::Transport::FileNotFoundException
* if the object does not already exist on the object storage.
* @return boolean TRUE if the metadata was updated.
* @throws \OpenStack\Transport\FileNotFoundException if the object does not
* already exist on the object storage.
*/
public function updateMetadata(Object $obj) {
//$url = $this->url . '/' . rawurlencode($obj->name());
@ -605,20 +558,16 @@ class Container implements \Countable, \IteratorAggregate {
* Note that there is no MOVE operation. You must copy and then DELETE
* in order to achieve that.
*
* @param object $obj OpenStack::Storage::ObjectStorage::Object
* The object to copy. This object MUST already be saved on the
* remote server. The body of the object is not sent. Instead, the
* copy operation is performed on the remote server. You can, and
* probably should, use a RemoteObject here.
* @param string $newName
* The new name of this object. If you are copying across
* containers, the name can be the same. If you are copying within
* @param object $obj \OpenStack\Storage\ObjectStorage::Object The object to
* copy. This object MUST already be saved on the remote server. The body of
* the object is not sent. Instead, the copy operation is performed on the
* remote server. You can, and probably should, use a RemoteObject here.
* @param string $newName The new name of this object. If you are copying a
* cross containers, the name can be the same. If you are copying within
* the same container, though, you will need to supply a new name.
* @param string $container
* The name of the alternate container. If this is set, the object
* will be saved into this container. If this is not sent, the copy
* will be performed inside of the original container.
*
* @param string $container The name of the alternate container. If this is
* set, the object will be saved into this container. If this is not sent,
* the copy will be performed inside of the original container.
*/
public function copy(Object $obj, $newName, $container = NULL) {
//$sourceUrl = $obj->url(); // This doesn't work with Object; only with RemoteObject.
@ -655,11 +604,11 @@ class Container implements \Countable, \IteratorAggregate {
* This fetches a single object with the given name. It downloads the
* entire object at once. This is useful if the object is small (under
* a few megabytes) and the content of the object will be used. For
* example, this is the right operation for accessing a text file
* example, this is the right operation for accessing a text file
* whose contents will be processed.
*
* For larger files or files whose content may never be accessed, use
* remoteObject(), which delays loading the content until one of its
* For larger files or files whose content may never be accessed, use
* remoteObject(), which delays loading the content until one of its
* content methods (e.g. RemoteObject::content()) is called.
*
* This does not yet support the following features of Swift:
@ -668,11 +617,10 @@ class Container implements \Countable, \IteratorAggregate {
* - If-Modified-Since/If-Unmodified-Since
* - If-Match/If-None-Match
*
* @param string $name
* The name of the object to load.
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* A remote object with the content already stored locally.
* @param string $name The name of the object to load.
*
* @return \OpenStack\Storage\ObjectStorage\RemoteObject A remote object with
* the content already stored locally.
*/
public function object($name) {
@ -720,11 +668,10 @@ class Container implements \Countable, \IteratorAggregate {
* though, that calling RemoteObject::content() will initiate another
* network operation.
*
* @param string $name
* The name of the object to fetch.
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* A remote object ready for use.
* @param string $name The name of the object to fetch.
*
* @return \OpenStack\Storage\ObjectStorage\RemoteObject A remote object ready
* for use.
*/
public function proxyObject($name) {
$url = self::objectUrl($this->url, $name);
@ -749,6 +696,7 @@ class Container implements \Countable, \IteratorAggregate {
}
/**
* This has been replaced with proxyObject().
*
* @deprecated
*/
public function remoteObject($name) {
@ -758,10 +706,9 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Get a list of objects in this container.
*
* This will return a list of objects in the container. With no
* parameters, it will attempt to return a listing of <i>all</i>
* objects in the container. However, by setting contraints, you can
* retrieve only a specific subset of objects.
* This will return a list of objects in the container. With no parameters, it
* will attempt to return a listing of all objects in the container. However,
* by setting contraints, you can retrieve only a specific subset of objects.
*
* Note that OpenStacks Swift will return no more than 10,000 objects
* per request. When dealing with large datasets, you are encouraged
@ -776,15 +723,12 @@ class Container implements \Countable, \IteratorAggregate {
* will begin with the next item after the marker (assuming the marker
* is found.)
*
* @param int $limit
* An integer indicating the maximum number of items to return. This
* cannot be greater than the Swift maximum (10k).
* @param string $marker
* The name of the object to start with. The query will begin with
* the next object AFTER this one.
* @retval array
* @return array
* List of RemoteObject or Subdir instances.
* @param int $limit An integer indicating the maximum number of items to
* return. This cannot be greater than the Swift maximum (10k).
* @param string $marker The name of the object to start with. The query will
* begin with the next object AFTER this one.
*
* @return array List of RemoteObject or Subdir instances.
*/
public function objects($limit = NULL, $marker = NULL) {
$params = array();
@ -834,19 +778,15 @@ class Container implements \Countable, \IteratorAggregate {
* delimiters other than '/', you need to be very consistent with your
* usage or else you may get surprising results.
*
* @param string $prefix
* The leading prefix.
* @param string $delimiter
* The character used to delimit names. By default, this is '/'.
* @param int $limit
* An integer indicating the maximum number of items to return. This
* cannot be greater than the Swift maximum (10k).
* @param string $marker
* The name of the object to start with. The query will begin with
* the next object AFTER this one.
* @retval array
* @return array
* List of RemoteObject or Subdir instances.
* @param string $prefix The leading prefix.
* @param string $delimiter The character used to delimit names. By default,
* this is '/'.
* @param int $limit An integer indicating the maximum number of items to
* return. This cannot be greater than the Swift maximum (10k).
* @param string $marker The name of the object to start with. The query will
* begin with the next object AFTER this one.
*
* @return array List of RemoteObject or Subdir instances.
*/
public function objectsWithPrefix($prefix, $delimiter = '/', $limit = NULL, $marker = NULL) {
$params = array(
@ -867,12 +807,10 @@ class Container implements \Countable, \IteratorAggregate {
* directory-like. You create it exactly as you create any other file.
* Typically, it is 0 bytes long.
*
* @code
* <?php
* $dir = new Object('a/b/c', '');
* $container->save($dir);
* ?>
* @endcode
* <?php
* $dir = new Object('a/b/c', '');
* $container->save($dir);
* ?>
*
* Using objectsByPath() with directory markers will return a list of
* Object instances, some of which are regular files, and some of
@ -884,16 +822,13 @@ class Container implements \Countable, \IteratorAggregate {
* method was legacy. More recent versions of the documentation no
* longer indicate this.
*
* @param string $path
* The path prefix.
* @param string $delimiter
* The character used to delimit names. By default, this is '/'.
* @param int $limit
* An integer indicating the maximum number of items to return. This
* cannot be greater than the Swift maximum (10k).
* @param string $marker
* The name of the object to start with. The query will begin with
* the next object AFTER this one.
* @param string $path The path prefix.
* @param string $delimiter The character used to delimit names. By default,
* this is '/'.
* @param int $limit An integer indicating the maximum number of items to
* return. This cannot be greater than the Swift maximum (10k).
* @param string $marker The name of the object to start with. The query will
* begin with the next object AFTER this one.
*/
public function objectsByPath($path, $delimiter = '/', $limit = NULL, $marker = NULL) {
$params = array(
@ -907,12 +842,10 @@ class Container implements \Countable, \IteratorAggregate {
* Get the URL to this container.
*
* Any container that has been created will have a valid URL. If the
* Container was set to be public (See
* Container was set to be public (See
* ObjectStorage::createContainer()) will be accessible by this URL.
*
* @retval string
* @return string
* The URL.
* @return string The URL.
*/
public function url() {
return $this->url;
@ -932,9 +865,9 @@ class Container implements \Countable, \IteratorAggregate {
* ObjectStorage methods.
*
* @todo Determine how to get the ACL from JSON data.
* @retval \OpenStack\Storage\ObjectStorage\ACL
* @return OpenStack::Storage::ObjectStorage::ACL
* An ACL, or NULL if the ACL could not be retrieved.
*
* @return \OpenStack\Storage\ObjectStorage\ACL An ACL, or NULL if the ACL
* could not be retrieved.
*/
public function acl() {
if (!isset($this->acl)) {
@ -949,7 +882,6 @@ class Container implements \Countable, \IteratorAggregate {
* Not all containers come fully instantiated. This method is sometimes
* called to "fill in" missing fields.
*
* @retval OpenStack::Storage::ObjectStorage::Comtainer
* @return \OpenStack\Storage\ObjectStorage\Container
*/
protected function loadExtraData() {
@ -1039,26 +971,23 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Return the iterator of contents.
*
* A Container is Iterable. This means that you can use a container in
* A Container is Iterable. This means that you can use a container in
* a `foreach` loop directly:
*
* @code
* <?php
* foreach ($container as $object) {
* print $object->name();
* }
* ?>
* @endcode
* <?php
* foreach ($container as $object) {
* print $object->name();
* }
* ?>
*
* The above is equivalent to doing the following:
* @code
* <?php
* $objects = $container->objects();
* foreach ($objects as $object) {
* print $object->name();
* }
* ?>
* @endcode
*
* <?php
* $objects = $container->objects();
* foreach ($objects as $object) {
* print $object->name();
* }
* ?>
*
* Note that there is no way to pass any constraints into an iterator.
* You cannot limit the number of items, set an marker, or add a
@ -1071,11 +1000,10 @@ class Container implements \Countable, \IteratorAggregate {
/**
* Remove the named object from storage.
*
* @param string $name
* The name of the object to remove.
* @retval boolean
* @return boolean
* TRUE if the file was deleted, FALSE if no such file is found.
* @param string $name The name of the object to remove.
*
* @return boolean TRUE if the file was deleted, FALSE if no such file is
* found.
*/
public function delete($name) {
$url = self::objectUrl($this->url, $name);

2
src/OpenStack/Storage/ObjectStorage/ContainerNotEmptyException.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* Contains exception class for ContainerNotEmptyException.
*/

3
src/OpenStack/Storage/ObjectStorage/ContentVerificationException.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* Contains the ContentVerificationException object.
*/
namespace OpenStack\Storage\ObjectStorage;
@ -27,6 +25,5 @@ namespace OpenStack\Storage\ObjectStorage;
* This occurs when the server sends content whose value does
* not match the supplied checksum. See
* RemoteObject::setContentVerification().
*
*/
class ContentVerificationException extends \OpenStack\Exception {}

174
src/OpenStack/Storage/ObjectStorage/Object.php
View File

@ -15,7 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
* Contains the class Object for ObjectStorage.
*/
@ -40,7 +39,7 @@ namespace OpenStack\Storage\ObjectStorage;
* - Metadata: File attributes that are stored along with the file on
* object store.
*
* Objects are stored and retrieved <i>by name</i>. So it is assumed
* Objects are stored and retrieved by name. So it is assumed
* that, per container, no more than one file with a given name exists.
*
* You may create Object instance and then store them in Containers.
@ -66,6 +65,7 @@ class Object {
* as they may prefer filesystem backing.
*/
protected $content;
/**
* The content type.
*
@ -73,6 +73,7 @@ class Object {
* a generic byte stream.
*/
protected $contentType = self::DEFAULT_CONTENT_TYPE;
/**
* Associative array of stored metadata.
*/
@ -86,18 +87,14 @@ class Object {
*/
protected $additionalHeaders = array();
/**
* Construct a new object for storage.
*
* @param string $name
* A name (may be pathlike) for the object.
* @param string $content
* Optional content to store in this object. This is the same
* as calling setContent().
* @param string $type
* Optional content type for this content. This is the same as
* calling setContentType().
* @param string $name A name (may be pathlike) for the object.
* @param string $content Optional content to store in this object. This is
* the same as calling setContent().
* @param string $type Optional content type for this content. This is the
* same as calling setContentType().
*/
public function __construct($name, $content = NULL, $type = NULL) {
$this->name = $name;
@ -140,16 +137,14 @@ class Object {
* names so that the name is always given an initial capital leter.
* That is, `foo` becomes `Foo`.
*
* @param array $array
* An associative array of metadata names to values.
* @param array $array An associative array of metadata names to values.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setMetadata(array $array) {
$this->metadata = $array;
return $this;
}
@ -158,9 +153,7 @@ class Object {
*
* This returns an associative array of all metadata for this object.
*
* @retval array
* @return array
* An associative array of metadata. This may be empty.
* @return array An associative array of metadata. This may be empty.
*/
public function metadata() {
return $this->metadata;
@ -169,20 +162,18 @@ class Object {
/**
* Override (change) the name of an object.
*
* Note that this changes only the <i>local copy</i> of an object. It
* Note that this changes only the local copy of an object. It
* does not rename the remote copy. In fact, changing the local name
* and then saving it will result in a new object being created in the
* object store.
*
* To copy an object, see
* OpenStack::Storage::ObjectStorage::Container::copyObject().
* To copy an object:
* @see \OpenStack\Storage\ObjectStorage\Container::copyObject().
*
* @param string $name
* A file or object name.
* @param string $name A file or object name.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setName($name) {
$this->name = $name;
@ -195,9 +186,7 @@ class Object {
* Returns the name of an object. If the name has been overwritten
* using setName(), this will return the latest (overwritten) name.
*
* @retval string
* @return string
* The name of the object.
* @return string The name of the object.
*/
public function name() {
return $this->name;
@ -216,23 +205,19 @@ class Object {
* All HTTP type options are allowed. So, for example, you can add a
* charset to a text type:
*
* @code
* <?php
* $o = new Object('my.html');
* $o->setContentType('text/html; charset=iso-8859-13');
* ?>
* @endcode
* <?php
* $o = new Object('my.html');
* $o->setContentType('text/html; charset=iso-8859-13');
* ?>
*
* Content type is not parsed or verified locally (though it is
* remotely). It can be dangerous, too, to allow users to specify a
* content type.
*
* @param string $type
* A valid content type.
* @param string $type A valid content type.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setContentType($type) {
$this->contentType = $type;
@ -244,9 +229,7 @@ class Object {
*
* This returns the currently set content type.
*
* @retval string
* @return string
* The content type, including any additional options.
* @return string The content type, including any additional options.
*/
public function contentType() {
return $this->contentType;
@ -255,10 +238,10 @@ class Object {
/**
* Set the content for this object.
*
* Place the content into the object. Typically, this is string
* Place the content into the object. Typically, this is string
* content that will be stored remotely.
*
* PHP's string is backed by a robust system that can accomodate
* PHP's string is backed by a robust system that can accomodate
* moderately sized files. However, it is best to keep strings short
* (<2MB, for example -- test for your own system's sweet spot).
* Larger data may be better handled with file system entries or
@ -267,15 +250,12 @@ class Object {
* Note that the OpenStack will not allow files larger than 5G, and
* PHP will likely croak well before that marker. So use discretion.
*
* @param string $content
* The content of the object.
* @param string $type
* The content type (MIME type). This can be set here for
* @param string $content The content of the object.
* @param string $type The content type (MIME type). This can be set here for
* convenience, or you can call setContentType() directly.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setContent($content, $type = NULL) {
$this->content = $content;
@ -303,9 +283,7 @@ class Object {
* When extending this class, you should make sure that this function
* returns the entire contents of an object.
*
* @retval string
* @return string
* The content of the file.
* @return string The content of the file.
*/
public function content() {
return $this->content;
@ -314,7 +292,7 @@ class Object {
/**
* Calculate the content length.
*
* This returns the number of <i>bytes</i> in a piece of content (not
* This returns the number of bytes in a piece of content (not
* the number of characters). Among other things, it is used to let
* the remote object store know how big of an object to expect when
* transmitting data.
@ -322,9 +300,7 @@ class Object {
* When extending this class, you should make sure to calculate the
* content length appropriately.
*
* @retval int
* @return int
* The length of the content, in bytes.
* @return int The length of the content, in bytes.
*/
public function contentLength() {
// strlen() is binary safe (or at least it seems to be).
@ -340,9 +316,7 @@ class Object {
* When extending this class, generate an ETag by creating an MD5 of
* the entire object's content (but not the metadata or name).
*
* @retval string
* @return string
* An MD5 value as a string of 32 hex digits (0-9a-f).
* @return string An MD5 value as a string of 32 hex digits (0-9a-f).
*/
public function eTag() {
return md5($this->content);
@ -364,12 +338,10 @@ class Object {
* to "gzip". This allows many user agents to receive the compressed
* data and automatically decompress them and display them correctly.
*
* @param string $encoding
* A valid encoding type.
* @param string $encoding A valid encoding type.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setEncoding($encoding) {
$this->contentEncoding = $encoding;
@ -383,9 +355,7 @@ class Object {
* Encoding is used to indicate how a file was encoded or compressed.
* See setEncoding() for more information.
*
* @retval string
* @return string
* The encoding type.
* @return string The encoding type.
*/
public function encoding() {
return $this->contentEncoding;
@ -399,22 +369,19 @@ class Object {
* a display.
*
* The typical value for this is:
* @code
* <?php
* $object->setDisposition('attachment; filename=foo.png');
* ?>
* @endcode
*
* <?php
* $object->setDisposition('attachment; filename=foo.png');
* ?>
*
* A disposition string should not include any newline characters or
* binary data.
*
* @param string $disposition
* A valid disposition declaration. These are defined in various
* HTTP specifications.
* @param string $disposition A valid disposition declaration. These are
* defined in various HTTP specifications.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setDisposition($disposition) {
$this->contentDisposition = $disposition;
@ -427,9 +394,7 @@ class Object {
*
* See setDisposition() for discussion.
*
* @retval string
* @return string
* The disposition string, or NULL if none is set.
* @return string The disposition string, or NULL if none is set.
*/
public function disposition() {
return $this->contentDisposition;
@ -438,8 +403,8 @@ class Object {
/**
* Set additional headers for storage.
*
* @attention EXPERT: You will need to understand OpenStack
* internals to use this effectively.
* EXPERT: You will need to understand OpenStack internals to use this
* effectively.
*
* Headers set here will be added to the HTTP request during save
* operations. They are not merged into existing headers until
@ -464,14 +429,12 @@ class Object {
* checking. You must ensure that the headers are in the proper
* format.
*
* @param array $headers
* An associative array where each name is an HTTP header name, and
* each value is the HTTP header value. No encoding or escaping is
* done.
* @param array $headers An associative array where each name is an HTTP
* header name, and each value is the HTTP header value. No encoding or
* escaping is done.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\Object $this so the method can be
* used in chaining.
*/
public function setAdditionalHeaders($headers) {
$this->additionalHeaders = $headers;
@ -496,17 +459,14 @@ class Object {
* by setAdditionalHeaders() are removed from an Object.
* (RemoteObject works differently).
*
* @attention
* Many headers are generated automatically, such as
* Content-Type and Content-Length. Removing these
* will simply result in their being regenerated.
* Many headers are generated automatically, such as
* Content-Type and Content-Length. Removing these
* will simply result in their being regenerated.
*
* @param array $keys
* The header names to be removed.
* @param array $keys The header names to be removed.
*
* @retval OpenStack::Storage::ObjectStorage::Object
* @return \OpenStack\Storage\ObjectStorage\Object
* $this for the current object so it can be used in chaining methods.
* @return \OpenStack\Storage\ObjectStorage\Object $this for the current
* object so it can be used in chaining methods.
*/
public function removeHeaders($keys) {
foreach ($keys as $k) {
@ -525,16 +485,14 @@ class Object {
* This should be used when (a) the file size is large, or (b) the
* exact size of the file is unknown.
*
* If this returns TRUE, it does not <i>guarantee</i> that the data
* If this returns TRUE, it does not guarantee that the data
* will be transmitted in chunks. But it recommends that the
* underlying transport layer use chunked encoding.
*
* The contentLength() method is not called for chunked transfers. So
* if this returns TRUE, contentLength() is ignored.
*
* @retval boolean
* @return boolean
* TRUE to recommend chunked transfer, FALSE otherwise.
* @return boolean TRUE to recommend chunked transfer, FALSE otherwise.
*/
public function isChunked() {
// Currently, this value is hard-coded. The default Object

4
src/OpenStack/Storage/ObjectStorage/ReadOnlyObjectException.php
View File

@ -14,9 +14,7 @@
See the License for the specific language governing permissions and
limitations under the License.
============================================================================ */
/**
* @file
*/
namespace OpenStack\Storage\ObjectStorage;
/**
* Thrown if an object that is read only is modified.

165
src/OpenStack/Storage/ObjectStorage/RemoteObject.php
View File

@ -15,8 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
*
* Contains the RemoteObject class.
*/
@ -27,7 +25,7 @@ namespace OpenStack\Storage\ObjectStorage;
*
* A remote object is one whose canonical copy is stored in a remote
* object storage. It represents a local (and possibly partial) copy of
* an object. (Contrast this with OpenStack::Storage::ObjectStorage::Object)
* an object. (Contrast this with \OpenStack\Storage\ObjectStorage\Object)
*
* Depending on how the object was constructed, it may or may not have a
* local copy of the entire contents of the file. It may only have the
@ -37,8 +35,8 @@ namespace OpenStack\Storage\ObjectStorage;
*
* Remote objects can be modified locally. Simply modifying an object
* will not result in those modifications being stored on the remote
* server. The object must be saved (see
* OpenStack::Storage::ObjectStorage::Container::save()). When an
* server. The object must be saved (see
* \OpenStack\Storage\ObjectStorage\Container::save()). When an
* object is modified so that its local contents differ from the remote
* stored copy, it is marked dirty (see isDirty()).
*/
@ -65,12 +63,9 @@ class RemoteObject extends Object {
/**
* Create a new RemoteObject from JSON data.
*
* @param array $data
* The JSON data as an array.
* @param string $token
* The authentication token.
* @param $url
* The URL to the object on the remote server
* @param array $data The JSON data as an array.
* @param string $token The authentication token.
* @param $url The URL to the object on the remote server
*/
public static function newFromJSON($data, $token, $url) {
@ -96,20 +91,15 @@ class RemoteObject extends Object {
* This is used to create objects from GET and HEAD requests, which
* return all of the metadata inside of the headers.
*
* @param string $name
* The name of the object.
* @param array $headers
* An associative array of HTTP headers in the exact format
* documented by OpenStack's API docs.
* @param string $token
* The current auth token (used for issuing subsequent requests).
* @param string $url
* The URL to the object in the object storage. Used for issuing
* subsequent requests.
* @param string $name The name of the object.
* @param array $headers An associative array of HTTP headers in the exact
* format documented by OpenStack's API docs.
* @param string $token The current auth token (used for issuing subsequent
* requests).
* @param string $url The URL to the object in the object storage. Used for
* issuing subsequent requests.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* A new RemoteObject.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject A new RemoteObject.
*/
public static function newFromHeaders($name, $headers, $token, $url) {
$object = new RemoteObject($name);
@ -155,7 +145,6 @@ class RemoteObject extends Object {
* If this object has been stored remotely, it will have
* a valid URL.
*
* @retval string
* @return string
* A URL to the object. The following considerations apply:
* - If the container is public, this URL can be loaded without
@ -203,9 +192,8 @@ class RemoteObject extends Object {
/**
* Set the headers
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this for the current object so it can be used in chaining methods.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this for the current
* object so it can be used in chaining methods.
*/
public function setHeaders($headers) {
$this->allHeaders = array();
@ -222,14 +210,12 @@ class RemoteObject extends Object {
/**
* Get the HTTP headers sent by the server.
*
* @attention EXPERT.
* EXPERT.
*
* This returns the array of minimally processed HTTP headers that
* were sent from the server.
*
* @retval array
* @return array
* An associative array of header names and values.
* @return array An associative array of header names and values.
*/
public function headers() {
return $this->allHeaders;
@ -252,7 +238,7 @@ class RemoteObject extends Object {
}
protected $reservedHeaders = array(
'etag' => TRUE, 'content-length' => TRUE,
'etag' => TRUE, 'content-length' => TRUE,
'x-auth-token' => TRUE,
'transfer-encoding' => TRUE,
'x-trans-id' => TRUE,
@ -261,9 +247,8 @@ class RemoteObject extends Object {
/**
* Filter the headers.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this for the current object so it can be used in chaining methods.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this for the current
* object so it can be used in chaining methods.
*/
public function filterHeaders(&$headers) {
$unset = array();
@ -290,17 +275,14 @@ class RemoteObject extends Object {
* Note that you cannot remove metadata through this mechanism,
* as it is managed using the metadata() methods.
*
* @attention
* Many headers are generated automatically, such as
* Content-Type and Content-Length. Removing these
* will simply result in their being regenerated.
* Many headers are generated automatically, such as
* Content-Type and Content-Length. Removing these
* will simply result in their being regenerated.
*
* @param array $keys
* The header names to be removed.
* @param array $keys The header names to be removed.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this for the current object so it can be used in chaining methods.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this for the current
* object so it can be used in chaining methods.
*/
public function removeHeaders($keys) {
foreach ($keys as $key) {
@ -326,15 +308,11 @@ class RemoteObject extends Object {
*
* Be wary of using this method with large files.
*
* @retval string
* @return string
* The contents of the file as a string.
* @throws \OpenStack\Transport\FileNotFoundException
* when the requested content cannot be located on the remote
* server.
* @throws \OpenStack\Exception
* when an unknown exception (usually an abnormal network condition)
* occurs.
* @return string The contents of the file as a string.
* @throws \OpenStack\Transport\FileNotFoundException when the requested
* content cannot be located on the remote server.
* @throws \OpenStack\Exception when an unknown exception (usually an abnormal
* network condition) occurs.
*/
public function content() {
@ -389,14 +367,12 @@ class RemoteObject extends Object {
*
* The stream is read-only.
*
* @param boolean $refresh
* If this is set to TRUE, any existing local modifications will be ignored
* and the content will be refreshed from the server. Any
* local changes to the object will be discarded.
* @retval resource
* @return resource
* A handle to the stream, which is already opened and positioned at
* the beginning of the stream.
* @param boolean $refresh If this is set to TRUE, any existing local
* modifications will be ignored and the content will be refreshed from the
* server. Any local changes to the object will be discarded.
*
* @return resource A handle to the stream, which is already opened and
* positioned at the beginning of the stream.
*/
public function stream($refresh = FALSE) {
@ -443,13 +419,11 @@ class RemoteObject extends Object {
* existing cached content will not be removed if caching is turned
* off.
*
* @param boolean $enabled
* If this is TRUE, caching will be enabled. If this is FALSE,
* caching will be disabled.
* @param boolean $enabled If this is TRUE, caching will be enabled. If this
* is FALSE, caching will be disabled.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this so the method
* can be used in chaining.
*/
public function setCaching($enabled) {
$this->caching = $enabled;
@ -459,12 +433,10 @@ class RemoteObject extends Object {
/**
* Indicates whether this object caches content.
*
* Importantly, this indicates whether the object <i>will</i> cache
* Importantly, this indicates whether the object will cache
* its contents, not whether anything is actually cached.
*
* @retval boolean
* @return boolean
* TRUE if caching is enabled, FALSE otherwise.
* @return boolean TRUE if caching is enabled, FALSE otherwise.
*/
public function isCaching() {
return $this->caching;
@ -488,14 +460,12 @@ class RemoteObject extends Object {
* also provide a small performance improvement on large files, but at
* the expense of security.
*
* @param boolean $enabled
* If this is TRUE, content verification is performed. The content
* is hashed and checked against a server-supplied MD5 hashcode. If
* this is FALSE, no checking is done.
* @param boolean $enabled If this is TRUE, content verification is performed.
* The content is hashed and checked against a server-supplied MD5 hashcode.
* If this is FALSE, no checking is done.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this so the method
* can be used in chaining.
*/
public function setContentVerification($enabled) {
$this->contentVerification = $enabled;
@ -510,9 +480,7 @@ class RemoteObject extends Object {
* returned by the remote server, and comparing that to the server's
* supplied ETag hash.
*
* @retval boolean
* @return boolean
* TRUE if this is verifying, FALSE otherwise.
* @return boolean TRUE if this is verifying, FALSE otherwise.
*/
public function isVerifyingContent() {
return $this->contentVerification;
@ -539,6 +507,8 @@ class RemoteObject extends Object {
* written to the remote server when desired.
*
* To replace dirty content with a clean copy, see refresh().
*
* @return boolean Whether or not there are unsaved changes.
*/
public function isDirty() {
@ -566,12 +536,11 @@ class RemoteObject extends Object {
* WARNING: This will destroy any unsaved local changes. You can use
* isDirty() to determine whether or not a local change has been made.
*
* @param boolean $fetchContent
* If this is TRUE, the content will be downloaded as well.
* @param boolean $fetchContent If this is TRUE, the content will be
* downloaded as well.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this for the current object so it can be used in chaining methods.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this for the current
* object so it can be used in chaining methods.
*/
public function refresh($fetchContent = FALSE) {
@ -591,15 +560,13 @@ class RemoteObject extends Object {
/**
* Helper function for fetching an object.
*
* @param boolean $fetchContent
* If this is set to TRUE, a GET request will be issued, which will
* cause the remote host to return the object in the response body.
* The response body is not handled, though. If this is set to
* FALSE, a HEAD request is sent, and no body is returned.
* @retval OpenStack::Transport::Response
* @return \OpenStack\Transport\Response
* containing the object metadata and (depending on the
* $fetchContent flag) optionally the data.
* @param boolean $fetchContent If this is set to TRUE, a GET request will be
* issued, which will cause the remote host to return the object in the
* response body. The response body is not handled, though. If this is set
* to FALSE, a HEAD request is sent, and no body is returned.
*
* @return \OpenStack\Transport\Response containing the object metadata and
* (depending on the $fetchContent flag) optionally the data.
*/
protected function fetchObject($fetchContent = FALSE) {
$method = $fetchContent ? 'GET' : 'HEAD';
@ -625,9 +592,8 @@ class RemoteObject extends Object {
*
* This is used internally to set object properties from headers.
*
* @retval OpenStack::Storage::ObjectStorage::RemoteObject
* @return \OpenStack\Storage\ObjectStorage\RemoteObject
* $this for the current object so it can be used in chaining methods.
* @return \OpenStack\Storage\ObjectStorage\RemoteObject $this for the current
* object so it can be used in chaining methods.
*/
protected function extractFromHeaders($response) {
$this->setContentType($response->header('Content-Type', $this->contentType()));
@ -642,6 +608,5 @@ class RemoteObject extends Object {
$this->setMetadata(Container::extractHeaderAttributes($response->headers()));
return $this;
}
}

460
src/OpenStack/Storage/ObjectStorage/StreamWrapper.php
View File

@ -15,7 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
* Contains the stream wrapper for `swift://` URLs.
*/
@ -35,15 +34,15 @@ use \OpenStack\Storage\ObjectStorage;
* unauthenticated access to files (which can be done using the HTTP
* stream wrapper -- no need for swift-specific logic).
*
* <b>URL Structure</b>
* URL Structure
*
* This takes URLs of the following form:
*
* <tt>swift://CONTAINER/FILE</tt>
* `swift://CONTAINER/FILE`
*
* Example:
*
* <tt>swift://public/example.txt</tt>
* `swift://public/example.txt`
*
* The example above would access the `public` container and attempt to
* retrieve the file named `example.txt`.
@ -51,7 +50,7 @@ use \OpenStack\Storage\ObjectStorage;
* Slashes are legal in Swift filenames, so a pathlike URL can be constructed
* like this:
*
* <tt>swift://public/path/like/file/name.txt</tt>
* `swift://public/path/like/file/name.txt`
*
* The above would attempt to find a file in object storage named
* `path/like/file/name.txt`.
@ -61,7 +60,7 @@ use \OpenStack\Storage\ObjectStorage;
* and object name (path) if there is any possibility that it will contain
* UTF-8 characters.
*
* <b>Locking</b>
* Locking
*
* This library does not support locking (e.g. flock()). This is because the
* OpenStack Object Storage implementation does not support locking. But there
@ -73,7 +72,7 @@ use \OpenStack\Storage\ObjectStorage;
* TWO COPIES of the object. This can, of course, lead to nasty race
* conditions if each copy is modified.
*
* <b>Usage</b>
* Usage
*
* The principle purpose of this wrapper is to make it easy to access and
* manipulate objects on a remote object storage instance. Managing
@ -81,46 +80,43 @@ use \OpenStack\Storage\ObjectStorage;
* the OpenStack API). Consequently, almost all actions done through the
* stream wrapper are focused on objects, not containers, servers, etc.
*
* <b>Retrieving an Existing Object</b>
* Retrieving an Existing Object
*
* Retrieving an object is done by opening a file handle to that object.
*
* <b>Writing an Object</b>
* Writing an Object
*
* Nothing is written to the remote storage until the file is closed. This
* keeps network traffic at a minimum, and respects the more-or-less stateless
* nature of ObjectStorage.
*
* <b>USING FILE/STREAM RESOURCES</b>
* USING FILE/STREAM RESOURCES
*
* In general, you should access files like this:
*
* @code
* <?php
* \OpenStack\Bootstrap::useStreamWrappers();
* // Set up the context.
* $context = stream_context_create(
* array('swift' => array(
* 'account' => ACCOUNT_NUMBER,
* 'secret' => SECRET_KEY,
* 'tenantid' => TENANT_ID,
* 'tenantname' => TENANT_NAME, // Optional instead of tenantid.
* 'endpoint' => AUTH_ENDPOINT_URL,
* )
* )
* );
* // Open the file.
* $handle = fopen('swift://mycontainer/myobject.txt', 'r+', FALSE, $context);
* <?php
* \OpenStack\Bootstrap::useStreamWrappers();
* // Set up the context.
* $context = stream_context_create(
* array('swift' => array(
* 'account' => ACCOUNT_NUMBER,
* 'secret' => SECRET_KEY,
* 'tenantid' => TENANT_ID,
* 'tenantname' => TENANT_NAME, // Optional instead of tenantid.
* 'endpoint' => AUTH_ENDPOINT_URL,
* )
* )
* );
* // Open the file.
* $handle = fopen('swift://mycontainer/myobject.txt', 'r+', FALSE, $context);
*
* // You can get the entire file, or use fread() to loop through the file.
* $contents = stream_get_contents($handle);
* // You can get the entire file, or use fread() to loop through the file.
* $contents = stream_get_contents($handle);
*
* fclose($handle);
* ?>
* @endcode
*
* @remarks
* fclose($handle);
* ?>
*
* Remarks
* - file_get_contents() works fine.
* - You can write to a stream, too. Nothing is pushed to the server until
* fflush() or fclose() is called.
@ -128,7 +124,7 @@ use \OpenStack\Storage\ObjectStorage;
* constraints are slightly relaxed to accomodate efficient local buffering.
* - Files are buffered locally.
*
* <b>USING FILE-LEVEL FUNCTIONS</b>
* USING FILE-LEVEL FUNCTIONS
*
* PHP provides a number of file-level functions that stream wrappers can
* optionally support. Here are a few such functions:
@ -147,7 +143,7 @@ use \OpenStack\Storage\ObjectStorage;
* * An auth request
* * A request for the container (to get container permissions)
* * A request for the object
* - <em>IMPORTANT:</em> Unlike the fopen()/fclose()... functions NONE of these functions
* - IMPORTANT: Unlike the fopen()/fclose()... functions NONE of these functions
* retrieves the body of the file. If you are working with large files, using
* these functions may be orders of magnitude faster than using fopen(), etc.
* (The crucial detail: These kick off a HEAD request, will fopen() does a
@ -172,13 +168,13 @@ use \OpenStack\Storage\ObjectStorage;
* - stat/fstat provide only one timestamp. Swift only tracks mtime, so mtime, atime,
* and ctime are all set to the last modified time.
*
* <b>DIRECTORIES</b>
* DIRECTORIES
*
* OpenStack Swift does not really have directories. Rather, it allows
* characters such as '/' to be used to designate namespaces on object
* names. (For simplicity, this library uses only '/' as a separator).
*
* This allows for simulated directory listings. Requesting
* This allows for simulated directory listings. Requesting
* `scandir('swift://foo/bar/')` is really a request to "find all of the items
* in the 'foo' container whose names start with 'bar/'".
*
@ -194,35 +190,33 @@ use \OpenStack\Storage\ObjectStorage;
* said markers ought to be created, they are not supported by the stream
* wrapper.
*
* As usual, the underlying OpenStack::Storage::ObjectStorage::Container class
* As usual, the underlying \OpenStack\Storage\ObjectStorage\Container class
* supports the full range of Swift features.
*
* <b>SUPPORTED CONTEXT PARAMETERS</b>
* SUPPORTED CONTEXT PARAMETERS
*
* This section details paramters that can be passed <i>either</i>
* through a stream context <i>or</i> through
* OpenStack::Bootstrap::setConfiguration().
* This section details paramters that can be passed either
* through a stream context or through
* \OpenStack\Bootstrap\setConfiguration().
*
* @attention
* PHP functions that do not allow you to pass a context may still be supported
* here <em>IF</em> you have set options using Bootstrap::setConfiguration().
* here IF you have set options using Bootstrap::setConfiguration().
*
* You are <i>required</i> to pass in authentication information. This
* You are required to pass in authentication information. This
* comes in one of three forms:
*
* -# API keys: acccount, secret, tenantid, endpoint
* -# User login: username, password, tenantid, endpoint
* -# Existing (valid) token: token, swift_endpoint
*
* @attention
* As of 1.0.0-beta6, you may use `tenantname` instead of `tenantid`.
* As of 1.0.0-beta6, you may use `tenantname` instead of `tenantid`.
*
* The third method (token) can be used when the application has already
* authenticated. In this case, a token has been generated and assigned
* to an account and tenant.
*
* The following parameters may be set either in the stream context
* or through OpenStack::Bootstrap::setConfiguration():
* or through OpenStack\Bootstrap::setConfiguration():
*
* - token: An auth token. If this is supplied, authentication is skipped and
* this token is used. NOTE: You MUST set swift_endpoint if using this
@ -297,7 +291,7 @@ class StreamWrapper {
/**
* Indicate whether the local differs from remote.
*
* When the file is modified in such a way that
* When the file is modified in such a way that
* it needs to be written remotely, the isDirty flag
* is set to TRUE.
*/
@ -337,19 +331,17 @@ class StreamWrapper {
*
* This closes a directory handle, freeing up the resources.
*
* @code
* <?php
* <?php
*
* // Assuming a valid context in $cxt...
* // Assuming a valid context in $cxt...
*
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
*
* // Do something with $dir
* // Do something with $dir
*
* closedir($dir);
* ?>
* @endcode
* closedir($dir);
* ?>
*
* NB: Some versions of PHP 5.3 don't clear all buffers when
* closing, and the handle can occasionally remain accessible for
@ -367,29 +359,24 @@ class StreamWrapper {
/**
* Open a directory for reading.
*
* @code
* <?php
* <?php
*
* // Assuming a valid context in $cxt...
* // Assuming a valid context in $cxt...
*
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
*
* // Do something with $dir
* // Do something with $dir
*
* closedir($dir);
* ?>
* @endcode
* closedir($dir);
* ?>
*
* See opendir() and scandir().
*
* @param string $path
* The URL to open.
* @param int $options
* Unused.
* @retval boolean
* @return boolean
* TRUE if the directory is opened, FALSE otherwise.
* @param string $path The URL to open.
* @param int $options Unused.
*
* @return boolean TRUE if the directory is opened, FALSE otherwise.
*/
public function dir_opendir($path, $options) {
$url = $this->parseUrl($path);
@ -427,26 +414,23 @@ class StreamWrapper {
* Read an entry from the directory.
*
* This gets a single line from the directory.
* @code
* <?php
*
* // Assuming a valid context in $cxt...
* <?php
*
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
* // Assuming a valid context in $cxt...
*
* while (($entry = readdir($dir)) !== FALSE) {
* print $entry . PHP_EOL;
* }
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
*
* closedir($dir);
* ?>
* @endcode
* while (($entry = readdir($dir)) !== FALSE) {
* print $entry . PHP_EOL;
* }
*
* @retval string
* @return string
* The name of the resource or FALSE when the directory has no more
* entries.
* closedir($dir);
* ?>
*
* @return string The name of the resource or FALSE when the directory has no
* more entries.
*/
public function dir_readdir() {
// If we are at the end of the listing, return FALSE.
@ -469,33 +453,30 @@ class StreamWrapper {
$fullpath = substr($fullpath, $len);
}
return $fullpath;
}
/**
* Rewind to the beginning of the listing.
*
* This repositions the read pointer at the first entry in the directory.
* @code
* <?php
*
* // Assuming a valid context in $cxt...
* <?php
*
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
* // Assuming a valid context in $cxt...
*
* while (($entry = readdir($dir)) !== FALSE) {
* print $entry . PHP_EOL;
* }
* // Get the container as if it were a directory.
* $dir = opendir('swift://mycontainer', $cxt);
*
* rewinddir($dir);
* while (($entry = readdir($dir)) !== FALSE) {
* print $entry . PHP_EOL;
* }
*
* $first = readdir($dir);
* rewinddir($dir);
*
* closedir($dir);
* ?>
* @endcode
* $first = readdir($dir);
*
* closedir($dir);
* ?>
*/
public function dir_rewinddir() {
$this->dirIndex = 0;
@ -519,34 +500,29 @@ class StreamWrapper {
*
* This DOES support cross-container renaming.
*
* See Container::copy().
* @see Container::copy().
*
* @code
* <?php
* Bootstrap::setConfiguration(array(
* 'tenantname' => 'foo@example.com',
* // 'tenantid' => '1234', // You can use this instead of tenantname
* 'account' => '1234',
* 'secret' => '4321',
* 'endpoint' => 'https://auth.example.com',
* ));
* <?php
* Bootstrap::setConfiguration(array(
* 'tenantname' => 'foo@example.com',
* // 'tenantid' => '1234', // You can use this instead of tenantname
* 'account' => '1234',
* 'secret' => '4321',
* 'endpoint' => 'https://auth.example.com',
* ));
*
* $from = 'swift://containerOne/file.txt';
* $to = 'swift://containerTwo/file.txt';
* $from = 'swift://containerOne/file.txt';
* $to = 'swift://containerTwo/file.txt';
*
* // Rename can also take a context as a third param.
* rename($from, $to);
* // Rename can also take a context as a third param.
* rename($from, $to);
*
* ?>
* @endcode
* ?>
*
* @param string $path_from
* A swift URL that exists on the remote.
* @param string $path_to
* A swift URL to another path.
* @retval boolean
* @return boolean
* TRUE on success, FALSE otherwise.
* @param string $path_from A swift URL that exists on the remote.
* @param string $path_to A swift URL to another path.
*
* @return boolean TRUE on success, FALSE otherwise.
*/
public function rename($path_from, $path_to) {
$this->initializeObjectStorage();
@ -592,9 +568,7 @@ class StreamWrapper {
* the lower-level buffer objects, this function can have unexpected
* side effects.
*
* @retval resource
* @return resource
* this returns the underlying stream.
* @return resource this returns the underlying stream.
*/
public function stream_cast($cast_as) {
return $this->objStream;
@ -603,23 +577,21 @@ class StreamWrapper {
/**
* Close a stream, writing if necessary.
*
* @code
* <?php
* <?php
*
* // Assuming $cxt has a valid context.
* // Assuming $cxt has a valid context.
*
* $file = fopen('swift://container/file.txt', 'r', FALSE, $cxt);
* $file = fopen('swift://container/file.txt', 'r', FALSE, $cxt);
*
* fclose($file);
* fclose($file);
*
* ?>
* @endcode
*
* This will close the present stream. Importantly,
* this will also write to the remote object storage if
* any changes have been made locally.
*
* See stream_open().
* @see stream_open().
*/
public function stream_close() {
@ -642,13 +614,11 @@ class StreamWrapper {
* This checks whether the stream has reached the
* end of the object's contents.
*
* Called when \c feof() is called on a stream.
* Called when `feof()` is called on a stream.
*
* See stream_seek().
* @see stream_seek().
*
* @retval boolean
* @return boolean
* TRUE if it has reached the end, FALSE otherwise.
* @return boolean TRUE if it has reached the end, FALSE otherwise.
*/
public function stream_eof() {
return feof($this->objStream);
@ -660,7 +630,7 @@ class StreamWrapper {
* If the local copy of this object has been modified,
* it is written remotely.
*
* Called when \c fflush() is called on a stream.
* Called when `fflush()` is called on a stream.
*/
public function stream_flush() {
try {
@ -706,7 +676,7 @@ class StreamWrapper {
/*
* Locking is currently unsupported.
*
* There is no remote support for locking a
* There is no remote support for locking a
* file.
public function stream_lock($operation) {
@ -718,23 +688,21 @@ class StreamWrapper {
*
* This opens a given stream resource and prepares it for reading or writing.
*
* @code
* <?php
* $cxt = stream_context_create(array(
* 'account' => '1bc123456',
* 'tenantid' => '987654321',
* 'secret' => 'eieio',
* 'endpoint' => 'https://auth.example.com',
* ));
* ?>
* <?php
* $cxt = stream_context_create(array(
* 'account' => '1bc123456',
* 'tenantid' => '987654321',
* 'secret' => 'eieio',
* 'endpoint' => 'https://auth.example.com',
* ));
* ?>
*
* $file = fopen('swift://myContainer/myObject.csv', 'rb', FALSE, $cxt);
* while ($bytes = fread($file, 8192)) {
* print $bytes;
* }
* fclose($file);
* ?>
* @endcode
* $file = fopen('swift://myContainer/myObject.csv', 'rb', FALSE, $cxt);
* while ($bytes = fread($file, 8192)) {
* print $bytes;
* }
* fclose($file);
* ?>
*
* If a file is opened in write mode, its contents will be retrieved from the
* remote storage and cached locally for manipulation. If the file is opened
@ -744,21 +712,18 @@ class StreamWrapper {
* During this operation, the remote host may need to be contacted for
* authentication as well as for file retrieval.
*
* @param string $path
* The URL to the resource. See the class description for details, but
* typically this expects URLs in the form <tt>swift://CONTAINER/OBJECT</tt>.
* @param string $mode
* Any of the documented mode strings. See fopen(). For any file that is
* in a writing mode, the file will be saved remotely on flush or close.
* Note that there is an extra mode: 'nope'. It acts like 'c+' except
* that it is never written remotely. This is useful for debugging the
* stream locally without sending that data to object storage. (Note that
* data is still fetched -- just never written.)
* @param int $options
* An OR'd list of options. Only STREAM_REPORT_ERRORS has any meaning
* to this wrapper, as it is not working with local files.
* @param string $opened_path
* This is not used, as this wrapper deals only with remote objects.
* @param string $path The URL to the resource. See the class description for
* details, but typically this expects URLs in the form `swift://CONTAINER/OBJECT`.
* @param string $mode Any of the documented mode strings. See fopen(). For
* any file that is in a writing mode, the file will be saved remotely on
* flush or close. Note that there is an extra mode: 'nope'. It acts like
* 'c+' except that it is never written remotely. This is useful for
* debugging the stream locally without sending that data to object storage.
* (Note that data is still fetched -- just never written.)
* @param int $options An OR'd list of options. Only STREAM_REPORT_ERRORS has
* any meaning to this wrapper, as it is not working with local files.
* @param string $opened_path This is not used, as this wrapper deals only
* with remote objects.
*/
public function stream_open($path, $mode, $options, &$opened_path) {
@ -837,7 +802,7 @@ class StreamWrapper {
try{
// Now we fetch the file. Only under certain circumstances do we generate
// an error if the file is not found.
// FIXME: We should probably allow a context param that can be set to
// FIXME: We should probably allow a context param that can be set to
// mark the file as lazily fetched.
$this->obj = $this->container->object($objectName);
$stream = $this->obj->stream();
@ -915,26 +880,22 @@ class StreamWrapper {
* This will read up to the requested number of bytes. Or, upon
* hitting the end of the file, it will return NULL.
*
* See fread(), fgets(), and so on for examples.
* @see fread(), fgets(), and so on for examples.
*
* @code
* <?php
* $cxt = stream_context_create(array(
* 'tenantname' => 'me@example.com',
* 'username' => 'me@example.com',
* 'password' => 'secret',
* 'endpoint' => 'https://auth.example.com',
* ));
* <?php
* $cxt = stream_context_create(array(
* 'tenantname' => 'me@example.com',
* 'username' => 'me@example.com',
* 'password' => 'secret',
* 'endpoint' => 'https://auth.example.com',
* ));
*
* $content = file_get_contents('swift://public/myfile.txt', FALSE, $cxt);
* ?>
* @endcode
* $content = file_get_contents('swift://public/myfile.txt', FALSE, $cxt);
* ?>
*
* @param int $count
* The number of bytes to read (usually 8192).
* @retval string
* @return string
* The data read.
* @param int $count The number of bytes to read (usually 8192).
*
* @return string The data read.
*/
public function stream_read($count) {
return fread($this->objStream, $count);
@ -943,12 +904,11 @@ class StreamWrapper {
/**
* Perform a seek.
*
* This is called whenever \c fseek() or \c rewind() is called on a
* This is called whenever `fseek()` or `rewind()` is called on a
* Swift stream.
*
* @attention
* IMPORTANT: Unlike the PHP core, this library
* allows you to fseek() inside of a file opened
* allows you to `fseek()` inside of a file opened
* in append mode ('a' or 'a+').
*/
public function stream_seek($offset, $whence) {
@ -987,20 +947,16 @@ class StreamWrapper {
/**
* Perform stat()/lstat() operations.
*
* @code
* <?php
* $file = fopen('swift://foo/bar', 'r+', FALSE, $cxt);
* $stats = fstat($file);
* ?>
* @endcode
* <?php
* $file = fopen('swift://foo/bar', 'r+', FALSE, $cxt);
* $stats = fstat($file);
* ?>
*
* To use standard \c stat() on a Swift stream, you will
* To use standard `stat()` on a Swift stream, you will
* need to set account information (tenant ID, account ID, secret,
* etc.) through OpenStack::Bootstrap::setConfiguration().
* etc.) through \OpenStack\Bootstrap::setConfiguration().
*
* @retval array
* @return array
* The stats array.
* @return array The stats array.
*/
public function stream_stat() {
$stat = fstat($this->objStream);
@ -1015,11 +971,9 @@ class StreamWrapper {
/**
* Get the current position in the stream.
*
* See ftell() and fseek().
* @see `ftell()` and `fseek()`.
*
* @retval int
* @return int
* The current position in the stream.
* @return int The current position in the stream.
*/
public function stream_tell() {
return ftell($this->objStream);
@ -1029,14 +983,12 @@ class StreamWrapper {
* Write data to stream.
*
* This writes data to the local stream buffer. Data
* is not pushed remotely until stream_close() or
* is not pushed remotely until stream_close() or
* stream_flush() is called.
*
* @param string $data
* Data to write to the stream.
* @retval int
* @return int
* The number of bytes written. 0 indicates and error.
* @param string $data Data to write to the stream.
*
* @return int The number of bytes written. 0 indicates and error.
*/
public function stream_write($data) {
$this->isDirty = TRUE;
@ -1055,15 +1007,12 @@ class StreamWrapper {
* delete either one. If you are using directory markers, not that deleting
* a marker will NOT delete the contents of the "directory".
*
* @attention
* You will need to use OpenStack::Bootstrap::setConfiguration() to set the
* necessary stream configuration, since \c unlink() does not take a context.
* You will need to use \OpenStack\Bootstrap::setConfiguration() to set the
* necessary stream configuration, since `unlink()` does not take a context.
*
* @param string $path
* The URL.
* @retval boolean
* @return boolean
* TRUE if the file was deleted, FALSE otherwise.
* @param string $path The URL.
*
* @return boolean TRUE if the file was deleted, FALSE otherwise.
*/
public function unlink($path) {
$url = $this->parseUrl($path);
@ -1147,7 +1096,7 @@ class StreamWrapper {
* Get the Object.
*
* This provides low-level access to the
* PHCloud::Storage::ObjectStorage::Object instance in which the content
* \OpenStack\Storage\ObjectStorage::Object instance in which the content
* is stored.
*
* Accessing the object's payload (Object::content()) is strongly
@ -1160,13 +1109,11 @@ class StreamWrapper {
*
* To access this:
*
* @code
* <?php
* $handle = fopen('swift://container/test.txt', 'rb', $cxt);
* $md = stream_get_meta_data($handle);
* $obj = $md['wrapper_data']->object();
* ?>
* @endcode
* <?php
* $handle = fopen('swift://container/test.txt', 'rb', $cxt);
* $md = stream_get_meta_data($handle);
* $obj = $md['wrapper_data']->object();
* ?>
*/
public function object() {
return $this->obj;
@ -1175,8 +1122,7 @@ class StreamWrapper {
/**
* EXPERT: Get the ObjectStorage for this wrapper.
*
* @retval object OpenStack::ObjectStorage
* An ObjectStorage object.
* @return object \OpenStack\ObjectStorage An ObjectStorage object.
* @see object()
*/
public function objectStorage() {
@ -1186,8 +1132,7 @@ class StreamWrapper {
/**
* EXPERT: Get the auth token for this wrapper.
*
* @retval string
* A token.
* @return string A token.
* @see object()
*/
public function token() {
@ -1199,8 +1144,7 @@ class StreamWrapper {
*
* This is only available when a file is opened via fopen().
*
* @retval array
* A service catalog.
* @return array A service catalog.
* @see object()
*/
public function serviceCatalog() {
@ -1228,7 +1172,7 @@ class StreamWrapper {
* the cached stat['size'] for the underlying buffer.
*/
protected function generateStat($object, $container, $size) {
// This is not entirely accurate. Basically, if the
// This is not entirely accurate. Basically, if the
// file is marked public, it gets 100775, and if
// it is private, it gets 100770.
//
@ -1287,12 +1231,10 @@ class StreamWrapper {
/**
* Set the fopen mode.
*
* @param string $mode
* The mode string, e.g. `r+` or `wb`.
* @param string $mode The mode string, e.g. `r+` or `wb`.
*
* @retval OpenStack::Storage::ObjectStorage::StreamWrapper
* @return \OpenStack\Storage\ObjectStorage\StreamWrapper
* $this so the method can be used in chaining.
* @return \OpenStack\Storage\ObjectStorage\StreamWrapper $this so the method
* can be used in chaining.
*/
protected function setMode($mode) {
$mode = strtolower($mode);
@ -1372,14 +1314,12 @@ class StreamWrapper {
*
* @todo Should there be an option to NOT query the Bootstrap::conf()?
*
* @param string $name
* The name to look up. First look it up in the context, then look
* it up in the Bootstrap config.
* @param mixed $default
* The default value to return if no config param was found.
* @retval mixed
* @return mixed
* The discovered result, or $default if specified, or NULL if
* @param string $name The name to look up. First look it up in the context,
* then look it up in the Bootstrap config.
* @param mixed $default The default value to return if no config param was
* found.
*
* @return mixed The discovered result, or $default if specified, or NULL if
* no $default is specified.
*/
protected function cxt($name, $default = NULL) {
@ -1422,11 +1362,9 @@ class StreamWrapper {
* This parses the URL and urldecodes the container name and
* the object name.
*
* @param string $url
* A Swift URL.
* @retval array
* @return array
* An array as documented in parse_url().
* @param string $url A Swift URL.
*
* @return array An array as documented in parse_url().
*/
protected function parseUrl($url) {
$res = parse_url($url);
@ -1453,7 +1391,7 @@ class StreamWrapper {
* Based on the context, initialize the ObjectStorage.
*
* The following parameters may be set either in the stream context
* or through OpenStack::Bootstrap::setConfiguration():
* or through \OpenStack\Bootstrap::setConfiguration():
*
* - token: An auth token. If this is supplied, authentication is skipped and
* this token is used. NOTE: You MUST set swift_endpoint if using this
@ -1470,10 +1408,10 @@ class StreamWrapper {
* the deprecated swiftAuth instead of IdentityService authentication.
* In general, you should avoid using this.
*
* To find these params, the method first checks the supplied context. If the
* To find these params, the method first checks the supplied context. If the
* key is not found there, it checks the Bootstrap::conf().
*
* @fixme This should be rewritten to use ObjectStorage::newFromServiceCatalog().
* @fixme This should be rewritten to use \ObjectStorage::newFromServiceCatalog().
*/
protected function initializeObjectStorage() {

42
src/OpenStack/Storage/ObjectStorage/StreamWrapperFS.php
View File

@ -15,12 +15,11 @@
limitations under the License.
============================================================================ */
/**
* @file
* Contains the stream wrapper for `swiftfs://` URLs.
*
* <b>Note, this stream wrapper is in early testing.</b>
*
* The stream wrapper implemented in OpenStack\Storage\ObjectStorage\StreamWrapper
*
* Note, this stream wrapper is in early testing.
*
* The stream wrapper implemented in \OpenStack\Storage\ObjectStorage\StreamWrapper
* only supports the elements of a stream that are implemented by object
* storage. This is how the PHP documentation states a stream wrapper should be
* created. Because some features do not exist, attempting to treat a stream
@ -28,25 +27,25 @@
* while there are not directories objects have pathy names (with / separators).
* Directory calls to object storage with the default stream wrappers will not
* operate how they would for a file system.
*
*
* StreamWrapperFS is an attempt to make a filesystem like stream wrapper.
* Hence the protocol is swiftfs standing for swift file system.
*
*
* To understand how this stream wrapper works start by first reading the
* documentation on the OpenStack::Storage::ObjectStorage::StreamWrapper.
*
* <b>DIRECTORIES</b>
*
* documentation on the \OpenStack\Storage\ObjectStorage\StreamWrapper.
*
* DIRECTORIES
*
* Because OpenStack Swift does not support directories the swift:// stream
* wrapper does not support them. This stream wrapper attempts to fake them by
* faking directory stats, mkdir, and rmdir. By default (see the options below
* for how to change these) directories have permissions of 777, timestamps
* close to that of the request, and the user and group called by php. We mock
* these on the fly though information is stored in the PHP stat cache.
*
*
* In addition to the parameters supported by StreamWrapper, the following
* parameters may be set either in the stream context or through
* OpenStack::Bootstrap::setConfiguration():
* parameters may be set either in the stream context or through
* OpenStack\Bootstrap::setConfiguration():
* - swiftfs_fake_stat_mode: Directories don't exist in swift. When stat() is
* is called on a directory we mock the stat information so functions like
* is_dir will work. The default file permissions is 0777. Though this
@ -70,7 +69,6 @@ use \OpenStack\Storage\ObjectStorage;
* This provides a full stream wrapper to expose `swiftfs://` URLs to the
* PHP stream system.
*
*
* @see http://us3.php.net/manual/en/class.streamwrapper.php
*/
class StreamWrapperFS extends StreamWrapper {
@ -93,7 +91,7 @@ class StreamWrapperFS extends StreamWrapper {
/**
* Fake Remove a directory.
*
*
* ObjectStorage has pathy objects not directories. If no objects with a path
* prefix exist we can pass removing it. If objects with a path prefix exist
* removing the directory will fail.
@ -135,17 +133,15 @@ class StreamWrapperFS extends StreamWrapper {
/**
* Test if a path prefix (directory like) esits.
*
*
* ObjectStorage has pathy objects not directories. If objects exist with a
* path prefix we can consider that the directory exists. For example, if
* we have an object at foo/bar/baz.txt and test the existance of the
* directory foo/bar/ we sould see it.
*
* @param string $path
* The directory path to test.
* @retval boolean
* @return boolean
* TRUE if the directory prefix exists and FALSE otherwise.
*
* @param string $path The directory path to test.
*
* @return boolean TRUE if the directory prefix exists and FALSE otherwise.
*/
protected function testDirectoryExists($path) {
$url = $this->parseUrl($path);

26
src/OpenStack/Storage/ObjectStorage/Subdir.php
View File

@ -15,7 +15,6 @@
limitations under the License.
============================================================================ */
/**
* @file
* Contains the Subdir class.
*/
@ -24,14 +23,21 @@ namespace OpenStack\Storage\ObjectStorage;
/**
* Represent a subdirectory (subdir) entry.
*
* Depending on the method with which Swift container requests are
* Depending on the method with which Swift container requests are
* executed, Swift may return subdir entries instead of Objects.
*
* Subdirs are used for things that are directory-like.
*/
class Subdir {
/**
* @var string The path string that this subdir describes
*/
protected $path;
/**
* @var string The delimiter used in this path
*/
protected $delimiter;
@ -40,10 +46,8 @@ class Subdir {
*
* This represents a remote response's tag for a subdirectory.
*
* @param string $path
* The path string that this subdir describes.
* @param string $delimiter
* The delimiter used in this path.
* @param string $path The path string that this subdir describes.
* @param string $delimiter The delimiter used in this path.
*/
public function __construct($path, $delimiter = '/') {
$this->path = $path;
@ -55,9 +59,7 @@ class Subdir {
*
* The path is delimited using the string returned by delimiter().
*
* @retval string
* @return string
* The path.
* @return string The path
*/
public function path() {
return $this->path;
@ -65,11 +67,9 @@ class Subdir {
/**
* Get the delimiter used by the server.
*
* @retval string
* @return string
* The value used as a delimiter.
* @return string The value used as a delimiter.
*/
public function delimiter() {
return $this->delimiter;
}
}
}