stackforge/openstack-sdk-php
Code Issues Proposed changes

Object Storage directory has been converted from doxygen to PHPDoc.

Browse Source 
Partially implements blueprint phpdoc.

Change-Id: I46e1f0bb2a585bb17260f3841007a8d82c6cad95
This commit is contained in:
Sam Choi
2014-04-04 01:02:32 -07:00
parent 670d1e9e6e
commit bf922f3abd
11 changed files with 668 additions and 958 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -15,12 +15,11 @@
limitations under the License. limitations under the License.
============================================================================ */ ============================================================================ */
/** /**
* @file
* Contains the stream wrapper for `swiftfs://` URLs. * Contains the stream wrapper for `swiftfs://` URLs.
* *
* <b>Note, this stream wrapper is in early testing.</b> * Note, this stream wrapper is in early testing.
* *
* The stream wrapper implemented in OpenStack\Storage\ObjectStorage\StreamWrapper * The stream wrapper implemented in \OpenStack\Storage\ObjectStorage\StreamWrapper
* only supports the elements of a stream that are implemented by object * 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 * 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 * created. Because some features do not exist, attempting to treat a stream
@@ -33,9 +32,9 @@
* Hence the protocol is swiftfs standing for swift file system. * Hence the protocol is swiftfs standing for swift file system.
* *
* To understand how this stream wrapper works start by first reading the * To understand how this stream wrapper works start by first reading the
* documentation on the OpenStack::Storage::ObjectStorage::StreamWrapper. * documentation on the \OpenStack\Storage\ObjectStorage\StreamWrapper.
* *
* <b>DIRECTORIES</b> * DIRECTORIES
* *
* Because OpenStack Swift does not support directories the swift:// stream * Because OpenStack Swift does not support directories the swift:// stream
* wrapper does not support them. This stream wrapper attempts to fake them by * wrapper does not support them. This stream wrapper attempts to fake them by
@@ -46,7 +45,7 @@
* *
* In addition to the parameters supported by StreamWrapper, the following * In addition to the parameters supported by StreamWrapper, the following
* parameters may be set either in the stream context or through * parameters may be set either in the stream context or through
* OpenStack::Bootstrap::setConfiguration(): * OpenStack\Bootstrap::setConfiguration():
* - swiftfs_fake_stat_mode: Directories don't exist in swift. When stat() is * - 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 called on a directory we mock the stat information so functions like
* is_dir will work. The default file permissions is 0777. Though this * 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 * This provides a full stream wrapper to expose `swiftfs://` URLs to the
* PHP stream system. * PHP stream system.
* *
*
* @see http://us3.php.net/manual/en/class.streamwrapper.php * @see http://us3.php.net/manual/en/class.streamwrapper.php
*/ */
class StreamWrapperFS extends StreamWrapper { class StreamWrapperFS extends StreamWrapper {
@@ -141,11 +139,9 @@ class StreamWrapperFS extends StreamWrapper {
* we have an object at foo/bar/baz.txt and test the existance of the * we have an object at foo/bar/baz.txt and test the existance of the
* directory foo/bar/ we sould see it. * directory foo/bar/ we sould see it.
* *
* @param string $path * @param string $path The directory path to test.
* The directory path to test. *
* @retval boolean * @return boolean TRUE if the directory prefix exists and FALSE otherwise.
* @return boolean
* TRUE if the directory prefix exists and FALSE otherwise.
*/ */
protected function testDirectoryExists($path) { protected function testDirectoryExists($path) {
$url = $this->parseUrl($path); $url = $this->parseUrl($path);

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

@@ -15,7 +15,6 @@
limitations under the License. limitations under the License.
============================================================================ */ ============================================================================ */
/** /**
* @file
* Contains the Subdir class. * Contains the Subdir class.
*/ */
@@ -31,7 +30,14 @@ namespace OpenStack\Storage\ObjectStorage;
*/ */
class Subdir { class Subdir {
/**
* @var string The path string that this subdir describes
*/
protected $path; protected $path;
/**
* @var string The delimiter used in this path
*/
protected $delimiter; protected $delimiter;
@@ -40,10 +46,8 @@ class Subdir {
* *
* This represents a remote response's tag for a subdirectory. * This represents a remote response's tag for a subdirectory.
* *
* @param string $path * @param string $path The path string that this subdir describes.
* The path string that this subdir describes. * @param string $delimiter The delimiter used in this path.
* @param string $delimiter
* The delimiter used in this path.
*/ */
public function __construct($path, $delimiter = '/') { public function __construct($path, $delimiter = '/') {
$this->path = $path; $this->path = $path;
@@ -55,9 +59,7 @@ class Subdir {
* *
* The path is delimited using the string returned by delimiter(). * The path is delimited using the string returned by delimiter().
* *
* @retval string * @return string The path
* @return string
* The path.
*/ */
public function path() { public function path() {
return $this->path; return $this->path;
@@ -65,9 +67,7 @@ class Subdir {
/** /**
* Get the delimiter used by the server. * 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() { public function delimiter() {
return $this->delimiter; return $this->delimiter;