From d64ec2d3d4c6686eae985fe1cf9832074edc8982 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Tue, 7 Aug 2012 16:00:15 -0400 Subject: [PATCH 1/9] Updated the set calls to return so they can be used in chaining. --- .../Storage/ObjectStorage/Container.php | 6 ++++ src/HPCloud/Storage/ObjectStorage/Object.php | 34 +++++++++++++++++++ .../Storage/ObjectStorage/RemoteObject.php | 12 +++++++ .../Storage/ObjectStorage/StreamWrapper.php | 5 +++ src/HPCloud/Transport/CURLTransport.php | 2 ++ 5 files changed, 59 insertions(+) diff --git a/src/HPCloud/Storage/ObjectStorage/Container.php b/src/HPCloud/Storage/ObjectStorage/Container.php index aabbf5e..5283f0d 100644 --- a/src/HPCloud/Storage/ObjectStorage/Container.php +++ b/src/HPCloud/Storage/ObjectStorage/Container.php @@ -412,9 +412,15 @@ class Container implements \Countable, \IteratorAggregate { * Names can be no longer than 128 characters, and values can be no * more than 256. UTF-8 or ASCII characters are allowed, though ASCII * seems to be preferred. + * + * @retval HPCloud::Storage::ObjectStorage::Container + * @return \HPCloud\Storage\ObjectStorage\Container + * $this so the method can be used in chaining. */ public function setMetadata($metadata) { $this->metadata = $metadata; + + return $this; } /** diff --git a/src/HPCloud/Storage/ObjectStorage/Object.php b/src/HPCloud/Storage/ObjectStorage/Object.php index 90b87a9..253fe42 100644 --- a/src/HPCloud/Storage/ObjectStorage/Object.php +++ b/src/HPCloud/Storage/ObjectStorage/Object.php @@ -147,9 +147,14 @@ class Object { * * @param array $array * An associative array of metadata names to values. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setMetadata(array $array) { $this->metadata = $array; + return $this; } @@ -178,6 +183,10 @@ class Object { * * @param string $name * A file or object name. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setName($name) { $this->name = $name; @@ -223,6 +232,10 @@ class Object { * * @param string $type * A valid content type. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setContentType($type) { $this->contentType = $type; @@ -261,6 +274,10 @@ class Object { * @param string $type * The content type (MIME type). This can be set here for * convenience, or you can call setContentType() directly. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setContent($content, $type = NULL) { $this->content = $content; @@ -348,9 +365,15 @@ class Object { * * @param string $encoding * A valid encoding type. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setEncoding($encoding) { $this->contentEncoding = $encoding; + + return $this; } /** @@ -386,9 +409,15 @@ class Object { * @param string $disposition * A valid disposition declaration. These are defined in various * HTTP specifications. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setDisposition($disposition) { $this->contentDisposition = $disposition; + + return $this; } /** @@ -436,9 +465,14 @@ class Object { * An associative array where each name is an HTTP header name, and * each value is the HTTP header value. No encoding or escaping is * done. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this so the method can be used in chaining. */ public function setAdditionalHeaders($headers) { $this->additionalHeaders = $headers; + return $this; } /** diff --git a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php index b4494e5..7c7d241 100644 --- a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php +++ b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php @@ -268,6 +268,8 @@ class RemoteObject extends Object { $this->allHeaders[$name] = $value; } } + + return $this; } /** @@ -478,9 +480,14 @@ class RemoteObject extends Object { * @param boolean $enabled * If this is TRUE, caching will be enabled. If this is FALSE, * caching will be disabled. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this so the method can be used in chaining. */ public function setCaching($enabled) { $this->caching = $enabled; + return $this; } /** @@ -518,9 +525,14 @@ class RemoteObject extends Object { * If this is TRUE, content verification is performed. The content * is hashed and checked against a server-supplied MD5 hashcode. If * this is FALSE, no checking is done. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this so the method can be used in chaining. */ public function setContentVerification($enabled) { $this->contentVerification = $enabled; + return $this; } /** diff --git a/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php b/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php index cd22218..fd00e6a 100644 --- a/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php +++ b/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php @@ -1320,6 +1320,10 @@ class StreamWrapper { * * @param string $mode * The mode string, e.g. `r+` or `wb`. + * + * @retval HPCloud::Storage::ObjectStorage::StreamWrapper + * @return \HPCloud\Storage\ObjectStorage\StreamWrapper + * $this so the method can be used in chaining. */ protected function setMode($mode) { $mode = strtolower($mode); @@ -1391,6 +1395,7 @@ class StreamWrapper { } + return $this; } /** diff --git a/src/HPCloud/Transport/CURLTransport.php b/src/HPCloud/Transport/CURLTransport.php index 0e4947f..7f217fa 100644 --- a/src/HPCloud/Transport/CURLTransport.php +++ b/src/HPCloud/Transport/CURLTransport.php @@ -389,5 +389,7 @@ class CURLTransport implements Transporter { } curl_setopt($curl, CURLOPT_HTTPHEADER, $buffer); + + return $this; } } From b0117898cc74676badc6a7456ddc9e699d5b80af Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Wed, 8 Aug 2012 16:20:28 -0400 Subject: [PATCH 2/9] Removed pear and phing files as we are not using them. --- README.pear | 3 - RELEASE | 17 - build.xml | 626 ------------------------------------ compatible_build.xml | 751 ------------------------------------------- project.properties | 37 --- 5 files changed, 1434 deletions(-) delete mode 100644 README.pear delete mode 100644 RELEASE delete mode 100644 build.xml delete mode 100644 compatible_build.xml delete mode 100644 project.properties diff --git a/README.pear b/README.pear deleted file mode 100644 index 4f5ab72..0000000 --- a/README.pear +++ /dev/null @@ -1,3 +0,0 @@ -%SUMMARY% - -%DESCRIPTION% \ No newline at end of file diff --git a/RELEASE b/RELEASE deleted file mode 100644 index c792226..0000000 --- a/RELEASE +++ /dev/null @@ -1,17 +0,0 @@ -Release notes for HPCloud-PHP - -1.0.0 - -1.0.0-alpha1 - -* Added ACL support -* Added ability to update obj metadata without re-submitting the entire - object. -* Added container metadata. -* Added support for setting the following header types: - - Content Disposition - - Content Encoding - - CORS headers -* Added support for server-side copying of objects. -* Added the ability to upload a file straight from a stream, instead of - having to buffer the entire stream into memory. diff --git a/build.xml b/build.xml deleted file mode 100644 index e000554..0000000 --- a/build.xml +++ /dev/null @@ -1,626 +0,0 @@ - - - - - - - ############# -# Basic Usage # - ############# - -Use Phing to manage this project. - -To list all of the available commands, do: - - phing -l - -To build a release, type: - - phing build -Dversion=1.0.0 - -Leaving -Dversion off will result in a "snapshot" release. - -To learn about more options, type - - phing longhelp - - - - - ############ -# THE BASICS # - ############ - -To build HPCloud-PHP, run: - - phing build - -This will create a complete distribution of the project in /dist, with the build files in /bin/build. Documentation will be generated if the appropriate target is configured. - -A versioned release can be built with: - - phing build -Dversion=2.1.1alpha1 - -To see all available build targets, run this command: - - phing -l - -Check Configuration -=================== - -To check how your project is configured, use the 'info' target: - - phing info - -This will print details about the project. - -Syntax Check -============ - -To check the syntax of all of your PHP source code, run this: - - phing lint - -It will generate a report on any files that fail to parse correctly. - -Generating Documentation -======================== - -To generate docs, do: - - phing doc - -Documentation will be stored in doc/. You can start with doc/index.html. - -Running Unit Tests -================== - -To run any configured tests, do: - - phing test - -The above will generate HTML test results which will be placed in test/reports/. If you wish to run the test and print the results directly the the command line (fast tests), you should run 'phing ftest' instead. - - phing ftest - -Code Coverage Reports -===================== - -To run coverage analysis, do: - - phing coverage - -This will create HTML pages describing code coverage. The coverage analysis will be available in test/coverage - - ################### -# OPTIONAL FEATURES # - ################### - -Phar Packages -============= - -This script can produce Phar packages on systems with PHP 5.3: - - phing pharBuild - -TextMate Integration -==================== - -If you are a TextMate user, you can install the Phing TextMate bundle -(http://github.com/technosophos/phing-tmbundle) to get some special TextMate features. - -Special TextMate keybindings: - - CMD-U: Run any target in the build file - CMD-SHIFT-I: Run the tmtest unit test target - CMD-SHIFT-U: Run the tmtarget target, which you can configure to do whatever you want - -Pear Channel Support -==================== - -This script will generate PEAR-compatible packages, provided you configure your settings correctly. -If you use Pirum (http://pirum-project.org) to manage your PEAR channel, you can use the -Phing-Pirum package (http://github.com/technosophos/Phing-Pirum) to build or manage the channel from -these scripts. You need to edit the Pirum configuration in build.xml, though. - -Pyrus Support -============= - -We are experimenting with supporting Pyrus, the next generation PEAR client. Pyrus can build -packages much more effectively, and supports a wide range of useful commands. Currently, we are -working on two targets: - - phing pyrusMake - phing pyrusPackage - -======== -To print this message, do: - - phing longhelp - - - - - - - - - - - - PHP language bindings for the HP Cloud. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Project name: ${project.name} - By ${project.lead} (${project.lead.email}) - Summary: ${project.summary} - Description: ${project.description} - - Source code: ${srcdir} - Complete packages: ${packagedir} - Version string pattern: ${project.name}-dev${DSTAMP} - -Edit project.properties (or build.xml) to set the above. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Executed tmtarget in build.xml. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ${releasedir} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/compatible_build.xml b/compatible_build.xml deleted file mode 100644 index 3283d06..0000000 --- a/compatible_build.xml +++ /dev/null @@ -1,751 +0,0 @@ - - - - - - - ############# -# Basic Usage # - ############# - -Use Phing to manage this project. - -To list all of the available commands, do: - - phing -l - -To build a release, type: - - phing build -Dversion=1.0.0 - -Leaving -Dversion off will result in a "snapshot" release. - -To learn about more options, type - - phing longhelp - - - - - ############ -# THE BASICS # - ############ - -To build HPCloud-PHP, run: - - phing build - -This will create a complete distribution of the project in /dist, with the build files in /bin/build. Documentation will be generated if the appropriate target is configured. - -A versioned release can be built with: - - phing build -Dversion=2.1.1alpha1 - -To see all available build targets, run this command: - - phing -l - -Check Configuration -=================== - -To check how your project is configured, use the 'info' target: - - phing info - -This will print details about the project. - -Syntax Check -============ - -To check the syntax of all of your PHP source code, run this: - - phing lint - -It will generate a report on any files that fail to parse correctly. - -Generating Documentation -======================== - -To generate docs, do: - - phing doc - -Documentation will be stored in doc/. You can start with doc/index.html. - -Running Unit Tests -================== - -To run any configured tests, do: - - phing test - -The above will generate HTML test results which will be placed in test/reports/. If you wish to run the test and print the results directly the the command line (fast tests), you should run 'phing ftest' instead. - - phing ftest - -Code Coverage Reports -===================== - -To run coverage analysis, do: - - phing coverage - -This will create HTML pages describing code coverage. The coverage analysis will be available in test/coverage - - ################### -# OPTIONAL FEATURES # - ################### - -Phar Packages -============= - -This script can produce Phar packages on systems with PHP 5.3: - - phing pharBuild - -TextMate Integration -==================== - -If you are a TextMate user, you can install the Phing TextMate bundle -(http://github.com/technosophos/phing-tmbundle) to get some special TextMate features. - -Special TextMate keybindings: - - CMD-U: Run any target in the build file - CMD-SHIFT-I: Run the tmtest unit test target - CMD-SHIFT-U: Run the tmtarget target, which you can configure to do whatever you want - -Pear Channel Support -==================== - -This script will generate PEAR-compatible packages, provided you configure your settings correctly. -If you use Pirum (http://pirum-project.org) to manage your PEAR channel, you can use the -Phing-Pirum package (http://github.com/technosophos/Phing-Pirum) to build or manage the channel from -these scripts. You need to edit the Pirum configuration in build.xml, though. - -Pyrus Support -============= - -We are experimenting with supporting Pyrus, the next generation PEAR client. Pyrus can build -packages much more effectively, and supports a wide range of useful commands. Currently, we are -working on two targets: - - phing pyrusMake - phing pyrusPackage - -======== -To print this message, do: - - phing longhelp - - - - - - - - - - - - This is a useful PHP project. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Project name: ${projectname} - By ${project.lead} (${project.lead.email}) - Summary: ${project.summary} - Description: ${project.description} - - Source code: ${srcdir} - Complete packages: ${packagedir} - Version string pattern: ${projectname}-dev${DSTAMP} - -Edit project.properties (or build.xml) to set the above. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Executed tmtarget in build.xml. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ${releasedir} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - stable - - - - snapshot - - - - - alpha - - - - - - beta - - - - ${stability} - - \ No newline at end of file diff --git a/project.properties b/project.properties deleted file mode 100644 index 3083657..0000000 --- a/project.properties +++ /dev/null @@ -1,37 +0,0 @@ -# Project build properties for HPCloud-PHP -# -# You can set your project-wide settings here. -# -# This file has some of the common properties -- the ones we think you probably -# want to change -- declared here. There are other available properties at the -# top of the build.xml file. - -# The name of the project. Alpha-Num and underscores allowed. NO SPACES. -#project.name=HPCloud-PHP - -# Where people can go to learn more about this project. -project.homepage=http://github.com/hpcloud - -# A short phrase describing this project. -project.summary=PHP API for HP Cloud - -# Technical description of this project. -project.description=Provides an API for working with the HP Cloud - -# The name of the license under which this is released. -project.license=MIT License - -# The minimal PHP version required to run this project. -project.php.version=5.3.1 - -# Name and email of the "lead developer" of this project. -project.lead=technosophos -project.lead.email=matthew.butcher@hp.com - -# If you are building PEAR packages, set this. -# (By default, our tgz files are PEAR packages) -pear.channel=pear.hpcloud.com - -# If you are using PhpDocumentor for documentation, set the output format -# using this. -phpdoc.style=HTML:frames:earthli From ee2f5019caa6a62f62a4d44c1153e5cb41205263 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Wed, 8 Aug 2012 16:34:41 -0400 Subject: [PATCH 3/9] Added a changelog. --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8c8cfaf --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Release Notes + +This changelog contains the relevant feature additions and bug fixes. To obtain a complete diff between versions you can got to https://github.com/hpcloud/HPCloud-PHP/compare/XXX...XXX where the XXX values are two different tagged versions of the library. For example, https://github.com/hpcloud/HPCloud-PHP/compare/1.0.0-beta6...1.0.0 + +* 1.0.0 (2012-08-09) + + * This is the initial stable release for object storage, CDN, and identity services. DBaaS is currently in private beta as such the bindings for this component are still in beta. \ No newline at end of file From 75730378e34d476d8fdf63c858ecc3de70280089 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Thu, 9 Aug 2012 14:36:19 -0400 Subject: [PATCH 4/9] Added support for @return in addition to @retval. @retval is a doxygen convention we use when generating our api docs. But, phpdoc uses @return which is what IDEs typically support on introspection. To better support introspection we now have both. --- src/HPCloud/Bootstrap.php | 3 +++ src/HPCloud/Services/DBaaS.php | 2 ++ src/HPCloud/Services/DBaaS/Instance.php | 4 +++- .../Services/DBaaS/InstanceDetails.php | 10 ++++++++ src/HPCloud/Services/DBaaS/Snapshot.php | 8 +++++-- .../Services/DBaaS/SnapshotDetails.php | 4 ++++ src/HPCloud/Services/IdentityServices.php | 13 +++++++++++ src/HPCloud/Storage/CDN.php | 14 +++++++++-- src/HPCloud/Storage/ObjectStorage.php | 16 +++++++++++-- src/HPCloud/Storage/ObjectStorage/ACL.php | 9 +++++++- .../Storage/ObjectStorage/Container.php | 23 ++++++++++++++++--- src/HPCloud/Storage/ObjectStorage/Object.php | 11 ++++++++- .../Storage/ObjectStorage/RemoteObject.php | 9 +++++++- .../Storage/ObjectStorage/StreamWrapper.php | 12 ++++++++++ .../Storage/ObjectStorage/StreamWrapperFS.php | 3 ++- src/HPCloud/Storage/ObjectStorage/Subdir.php | 2 ++ src/HPCloud/Transport.php | 1 + src/HPCloud/Transport/CURLTransport.php | 2 ++ src/HPCloud/Transport/PHPStreamTransport.php | 1 + src/HPCloud/Transport/Response.php | 13 +++++++++-- 20 files changed, 144 insertions(+), 16 deletions(-) diff --git a/src/HPCloud/Bootstrap.php b/src/HPCloud/Bootstrap.php index a47d771..722a251 100644 --- a/src/HPCloud/Bootstrap.php +++ b/src/HPCloud/Bootstrap.php @@ -285,6 +285,7 @@ class Bootstrap { * @param mixed $default * The default value to return if the name is not found. * @retval mixed + * @return mixed * The value, if found; or the default, if set; or NULL. */ public static function config($name = NULL, $default = NULL) { @@ -315,6 +316,7 @@ class Bootstrap { * @param string $name * The name of the item to check for. * @retval boolean + * @return boolean * TRUE if the named option is set, FALSE otherwise. Note that the value may * be falsey (FALSE, 0, etc.), but if the value is NULL, this will return * false. @@ -333,6 +335,7 @@ class Bootstrap { * Whether to force the generation of a new object even if one is already * cached. * @retval HPCloud::Services::IdentityService + * @return \HPCloud\Services\:IdentityService * An authenticated ready to use HPCloud::Services::IdentityService object. * @throws HPCloud::Exception * When the needed configuration to authenticate is not available. diff --git a/src/HPCloud/Services/DBaaS.php b/src/HPCloud/Services/DBaaS.php index 418efda..a943f46 100644 --- a/src/HPCloud/Services/DBaaS.php +++ b/src/HPCloud/Services/DBaaS.php @@ -137,6 +137,7 @@ class DBaaS { * Get the project ID for this session. * * @retval string + * @return string * The project ID. */ public function projectId() { @@ -147,6 +148,7 @@ class DBaaS { * Get the endpoint URL to the DBaaS session. * * @retval string + * @return string * The URL. */ public function url() { diff --git a/src/HPCloud/Services/DBaaS/Instance.php b/src/HPCloud/Services/DBaaS/Instance.php index be809a8..72e957b 100644 --- a/src/HPCloud/Services/DBaaS/Instance.php +++ b/src/HPCloud/Services/DBaaS/Instance.php @@ -79,7 +79,8 @@ class Instance extends Operations { *- medium * @param array $typeSpec * A typespec array. Currently, only 'mysql', '5.5' is supported. - * @retval object HPCloud::Services::DBaaS::InstanceDetails + * @retval HPCloud::Services::DBaaS::InstanceDetails + * @return \HPCloud\Services\DBaaS\InstanceDetails * The details of creation, including login and password info. * @see http://api-docs.hpcloud.com/hpcloud-dbaas/1.0/content/instance-create.html */ @@ -132,6 +133,7 @@ class Instance extends Operations { * Reset the primary password on this instance. * * @retval string + * @return string * The new (autogenerated) password. */ public function resetPassword($instanceId) { diff --git a/src/HPCloud/Services/DBaaS/InstanceDetails.php b/src/HPCloud/Services/DBaaS/InstanceDetails.php index 3bbe20d..295320b 100644 --- a/src/HPCloud/Services/DBaaS/InstanceDetails.php +++ b/src/HPCloud/Services/DBaaS/InstanceDetails.php @@ -74,6 +74,7 @@ class InstanceDetails { * Get the name of this instance. * * @retval string + * @return string * The name of the instance. */ public function name() { @@ -84,6 +85,7 @@ class InstanceDetails { * Get the ID of the instance. * * @retval string + * @return string * The ID. */ public function id() { @@ -96,6 +98,7 @@ class InstanceDetails { * This may only be set during CREATE or DESCRIBE results. * * @retval string + * @return string * A string indicating the creation time. * Format is in ISO date format. */ @@ -115,6 +118,7 @@ class InstanceDetails { *- restarting: Instance has been restarted, and is still coming online. * * @retval string + * @return string * A short status message. */ public function status() { @@ -129,6 +133,7 @@ class InstanceDetails { * checking that status() returns 'running'. * * @retval boolean + * @return boolean * TRUE if this is running, FALSE otherwise. */ public function isRunning() { @@ -148,6 +153,7 @@ class InstanceDetails { * This returns the DNS name of the host (or possibly an IP address). * * @retval string + * @return string * The FQDN or IP address of the MySQL server. */ public function hostname() { @@ -177,6 +183,7 @@ class InstanceDetails { * Typically this is only available at creation time! * * @retval string + * @return string * The username for the MySQL instance. */ public function username() { @@ -208,6 +215,7 @@ class InstanceDetails { * This is only returned when a database is first created. * * @retval string + * @return string * A password string. */ public function password() { @@ -250,6 +258,7 @@ class InstanceDetails { * definition. * * @retval array + * @return array * An array of related links to DBaaS URLs. */ public function links() { @@ -271,6 +280,7 @@ class InstanceDetails { * of PHP use this. * * @retval string + * @return string * The DSN, including driver, host, port, and database name. * @todo * At this time, 'mysql' is hard-coded as the driver name. Does this diff --git a/src/HPCloud/Services/DBaaS/Snapshot.php b/src/HPCloud/Services/DBaaS/Snapshot.php index f80cae8..9d6ca2a 100644 --- a/src/HPCloud/Services/DBaaS/Snapshot.php +++ b/src/HPCloud/Services/DBaaS/Snapshot.php @@ -66,6 +66,7 @@ class Snapshot extends Operations { * An optional database instance ID. If set, only snapshots for * the given instance will be returned. * @retval array + * @return array * An array of HPCloud::Services::DBaaS::SnapshotDetails * instances. */ @@ -102,7 +103,8 @@ class Snapshot extends Operations { * A human-readable name for the snapshot. Internally, * a snapshot ID will be used to reference this * snapshot. - * @retval object HPCloud::Services::DBaaS::SnapshotDetails + * @retval HPCloud::Services::DBaaS::SnapshotDetails + * @return \HPCloud\Services\DBaaS\SnapshotDetails * A snapshot details object containing information about * the snapshot. */ @@ -130,6 +132,7 @@ class Snapshot extends Operations { * The snapshot ID for the snapshot that should * be deleted. * @retval boolean + * @return boolean * Returns boolean TRUE on success. Throws one of the * HPCloud::Exception instances on failure. * @throws HPCloud::Exception @@ -148,7 +151,8 @@ class Snapshot extends Operations { * @param string $snapshotId * The snapshot ID. * - * @retval object HPCloud::Services::DBaaS::SnapshotDetails + * @retval HPCloud::Services::DBaaS::SnapshotDetails + * @return \HPCloud\Services\DBaaS\SnapshotDetails * The details object. */ public function describe($snapshotId) { diff --git a/src/HPCloud/Services/DBaaS/SnapshotDetails.php b/src/HPCloud/Services/DBaaS/SnapshotDetails.php index e1df550..f91b999 100644 --- a/src/HPCloud/Services/DBaaS/SnapshotDetails.php +++ b/src/HPCloud/Services/DBaaS/SnapshotDetails.php @@ -54,6 +54,7 @@ class SnapshotDetails { * The ID of the snapshot. * * @retval string + * @return string * The ID. */ public function id() { @@ -66,6 +67,7 @@ class SnapshotDetails { * is a snapshot. * * @retval string + * @return string * The database instance ID. */ public function instanceId() { @@ -75,6 +77,7 @@ class SnapshotDetails { * The data upon which this snapshot was created. * * @retval string + * @return string * An ISO data string representing the date and time * that this snapshot was created. */ @@ -90,6 +93,7 @@ class SnapshotDetails { * The data returned from this may be in flux during the beta release * of this product. * @retval array + * @return array * An array of links. Typically, at least an URL to the snapshot should * be provided. */ diff --git a/src/HPCloud/Services/IdentityServices.php b/src/HPCloud/Services/IdentityServices.php index b14b4fe..8e2aed4 100644 --- a/src/HPCloud/Services/IdentityServices.php +++ b/src/HPCloud/Services/IdentityServices.php @@ -223,6 +223,7 @@ class IdentityServices /*implements Serializable*/ { * URL to the one passed into the constructor. * * @retval string + * @return string * The complete URL to the identity services endpoint. */ public function url() { @@ -258,6 +259,7 @@ class IdentityServices /*implements Serializable*/ { * An associative array of authentication operations and their respective * parameters. * @retval string + * @return string * The token. This is returned for simplicity. The full response is used * to populate this object's service catalog, etc. The token is also * retrievable with token(). @@ -383,6 +385,7 @@ class IdentityServices /*implements Serializable*/ { * The tenant Name for this account. This can be obtained through the * HPCloud console. * @retval string + * @return string * The auth token. * @throws HPCloud::Transport::AuthorizationException * If authentication failed. @@ -416,6 +419,7 @@ class IdentityServices /*implements Serializable*/ { * methods has been run. * * @retval string + * @return string * The token ID to be used in subsequent calls. */ public function token() { @@ -432,6 +436,7 @@ class IdentityServices /*implements Serializable*/ { * run. * * @retval string + * @return string * The tenant ID if available, or NULL. */ public function tenantId() { @@ -450,6 +455,7 @@ class IdentityServices /*implements Serializable*/ { * run. * * @retval string + * @return string * The tenant name if available, or NULL. */ public function tenantName() { @@ -484,6 +490,7 @@ class IdentityServices /*implements Serializable*/ { * This will not be populated until after authentication has been done. * * @retval array + * @return array * An associative array of details. */ public function tokenDetails() { @@ -498,6 +505,7 @@ class IdentityServices /*implements Serializable*/ { * mis-configured machine timestamp could give spurious results. * * @retval boolean + * @return boolean * This will return FALSE if there is a current token and it has * not yet expired (according to the date info). In all other cases * it returns TRUE. @@ -581,6 +589,7 @@ class IdentityServices /*implements Serializable*/ { * @todo Paging on the service catalog is not yet implemented. * * @retval array + * @return array * An associative array representing * the service catalog. */ @@ -628,6 +637,7 @@ class IdentityServices /*implements Serializable*/ { * This will not have data until after authentication has been done. * * @retval array + * @return array * An associative array, as described above. */ public function user() { @@ -661,6 +671,7 @@ class IdentityServices /*implements Serializable*/ { * Note that this method invokes a new request against the remote server. * * @retval array + * @return array * An indexed array of tenant info. Each entry will be an associative * array containing tenant details. * @throws HPCloud::Transport::AuthorizationException @@ -723,6 +734,7 @@ class IdentityServices /*implements Serializable*/ { * ID will be removed. * * @retval string + * @return string * The authentication token. * @throws HPCloud::Transport::AuthorizationException * If authentication failed. @@ -780,6 +792,7 @@ class IdentityServices /*implements Serializable*/ { * name will be removed. * * @retval string + * @return string * The authentication token. * @throws HPCloud::Transport::AuthorizationException * If authentication failed. diff --git a/src/HPCloud/Storage/CDN.php b/src/HPCloud/Storage/CDN.php index ad2bfa0..42220e9 100644 --- a/src/HPCloud/Storage/CDN.php +++ b/src/HPCloud/Storage/CDN.php @@ -149,7 +149,9 @@ class CDN { * * @param HPCloud::Services::IdentityServices $identity * The identity to use. - * @retval object + * @retval boolean + * @retval HPCloud::Storage::CDN + * @return \HPCloud\Storage\CDN|boolean * A CDN object or FALSE if no CDN services could be found * in the catalog. */ @@ -195,7 +197,9 @@ class CDN { * A service catalog; see HPCloud::Services::IdentityServices::serviceCatalog(). * @param string $token * The token. - * @retval object + * @retval boolean + * @retval HPCloud::Storage::CDN + * @return boolean|\HPCloud\Storage\CDN * A CDN object or FALSE if no CDN services could be found * in the catalog. */ @@ -305,6 +309,7 @@ class CDN { * If this is set to TRUE, then only containers that are * CDN-enabled will be returned. * @retval array + * @return array * An indexed array of associative arrays. The format of each * associative array is explained on container(). * @throws HPCloud::Exception @@ -357,6 +362,7 @@ class CDN { * @param string $name * The name of the container to fetch. * @retval array + * @return array * An associative array in the exact format as in containers. */ public function container($name) { @@ -412,6 +418,7 @@ class CDN { * If this is passed, then its value will be set to TRUE if the * container was created in the CDN, or FALSE if the container * already existed in CDN. + * @retval string * @return string * TRUE if the container was created, FALSE if the container was already * added to the CDN (and thus nothing happened). @@ -450,6 +457,7 @@ class CDN { * @param array $attrs * An associative array of attributes. * @retval boolean + * @return boolean * TRUE if the update was successful. * @throws HPCloud::Exception * Possibly throws one of the HTTP exceptions. @@ -509,6 +517,7 @@ class CDN { * @param string $name * The name of the container whose cache should be suspended. * @retval boolean + * @return boolean * TRUE if the container is disabled. * @throws HPCloud::Exception * HTTP exceptions may be thrown if an error occurs. @@ -535,6 +544,7 @@ class CDN { * @param string $name * The Container name. * @retval boolean + * @return boolean * TRUE if the container was successfully deleted, * FALSE if the container was not removed, but no * error occurred. diff --git a/src/HPCloud/Storage/ObjectStorage.php b/src/HPCloud/Storage/ObjectStorage.php index 238982a..57b22fb 100644 --- a/src/HPCloud/Storage/ObjectStorage.php +++ b/src/HPCloud/Storage/ObjectStorage.php @@ -172,7 +172,8 @@ class ObjectStorage { * @param HPCloud::Services::IdentityServices $identity * An identity services object that already has a valid token and a * service catalog. - * @retval object ObjectStorage + * @retval HPCloud::Storage::ObjectStorage + * @return \HPCloud\Storage\ObjectStorage * A new ObjectStorage instance. */ public static function newFromIdentity($identity) { @@ -196,7 +197,8 @@ class ObjectStorage { * just ObjectStorage::SERVICE_TYPE. * @param string $authToken * The auth token returned by IdentityServices. - * @retval object ObjectStorage + * @retval HPCloud::Storage::ObjectStorage + * @return \HPCloud\Storage\ObjectStorage * A new ObjectStorage instance. */ public static function newFromServiceCatalog($catalog, $authToken) { @@ -286,6 +288,7 @@ class ObjectStorage { * If this is TRUE (default), get the URL to the SSL CDN; * otherwise get the URL to the plain HTTP CDN. * @retval string + * @return string * The URL to the CDN container, or NULL if no such * URL is found. */ @@ -300,6 +303,7 @@ class ObjectStorage { * Get the authentication token. * * @retval string + * @return string * The authentication token. */ public function token() { @@ -310,6 +314,7 @@ class ObjectStorage { * Get the URL endpoint. * * @retval string + * @return string * The URL that is the endpoint for this service. */ public function url() { @@ -346,6 +351,7 @@ class ObjectStorage { * The name of the last object seen. Used when paging. * * @retval array + * @return array * An associative array of containers, where the key is the * container's name and the value is an * HPCloud::Storage::ObjectStorage::Container object. Results are @@ -387,6 +393,7 @@ class ObjectStorage { * @param string $name * The name of the container to load. * @retval HPCloud::Storage::ObjectStorage::Container + * @return \HPCloud\Storage\ObjectStorage\Container * A container. * @throws HPCloud::Transport::FileNotFoundException * if the named container is not found on the remote server. @@ -422,6 +429,7 @@ class ObjectStorage { * @param string $name * The name of the container to test. * @retval boolean + * @return boolean * TRUE if the container exists, FALSE if it does not. * @throws HPCloud::Exception * If an unexpected network error occurs. @@ -495,6 +503,7 @@ class ObjectStorage { * @param array $metadata * An associative array of metadata to attach to the container. * @retval boolean + * @return boolean * TRUE if the container was created, FALSE if the container was not * created because it already exists. */ @@ -558,6 +567,7 @@ class ObjectStorage { * An ACL. To make the container publically readable, use * ACL::makePublic(). * @retval boolean + * @return boolean * TRUE if the cointainer was created, FALSE otherwise. */ public function changeContainerACL($name, ACL $acl) { @@ -579,6 +589,7 @@ class ObjectStorage { * @param string $name * The name of the container. * @retval boolean + * @return boolean * TRUE if the container was deleted, FALSE if the container was not * found (and hence, was not deleted). * @throws HPCloud::Storage::ObjectStorage::ContainerNotEmptyException @@ -625,6 +636,7 @@ class ObjectStorage { * - The number of containers (`count`). * * @retval array + * @return array * An associative array of account info. Typical keys are: * - bytes: Bytes consumed by existing content. * - containers: Number of containers. diff --git a/src/HPCloud/Storage/ObjectStorage/ACL.php b/src/HPCloud/Storage/ObjectStorage/ACL.php index 18d6533..8137ff5 100644 --- a/src/HPCloud/Storage/ObjectStorage/ACL.php +++ b/src/HPCloud/Storage/ObjectStorage/ACL.php @@ -152,6 +152,7 @@ class ACL { * - READ to any host, with container listings. * * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL * an ACL object with the appopriate permissions set. */ public static function makePublic() { @@ -172,6 +173,7 @@ class ACL { * with no permissions as a private object. * * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL * an ACL object with the appopriate permissions set. */ public static function makeNonPublic() { @@ -194,7 +196,8 @@ class ACL { * * @param array $headers * An associative array of headers. - * @retval ACL + * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL * A new ACL. */ public static function newFromHeaders($headers) { @@ -242,6 +245,7 @@ class ACL { * @param string $rule * The string rule to parse. * @retval array + * @return array * The rule as an array. */ public static function parseRule($perm, $rule) { @@ -392,6 +396,7 @@ class ACL { * Get the rules array for this ACL. * * @retval array + * @return array * An array of associative arrays of rules. */ public function rules() { @@ -496,6 +501,7 @@ class ACL { * at all. * * @retval boolean + * @return boolean * TRUE if this is private (non-public), FALSE if * any permissions are granted via this ACL. */ @@ -544,6 +550,7 @@ class ACL { * a pretty string. * * @retval string + * @return string * The ACL represented as a string. */ public function __toString() { diff --git a/src/HPCloud/Storage/ObjectStorage/Container.php b/src/HPCloud/Storage/ObjectStorage/Container.php index 5283f0d..83a4455 100644 --- a/src/HPCloud/Storage/ObjectStorage/Container.php +++ b/src/HPCloud/Storage/ObjectStorage/Container.php @@ -110,6 +110,7 @@ class Container implements \Countable, \IteratorAggregate { * @param string $prefix * A prefix for the metadata headers. * @retval array + * @return array * An array of headers. * @see http://docs.openstack.org/bexar/openstack-object-storage/developer/content/ch03s03.html#d5e635 * @see http://docs.openstack.org/bexar/openstack-object-storage/developer/content/ch03s03.html#d5e700 @@ -143,6 +144,7 @@ class Container implements \Countable, \IteratorAggregate { * @param string $oname * The name of the object. * @retval string + * @return string * The URL to the object. Characters that need escaping will be escaped, * while slash characters are not. Thus, the URL will look pathy. */ @@ -179,6 +181,7 @@ class Container implements \Countable, \IteratorAggregate { * @param string $prefix * The prefix on metadata headers. * @retval array + * @return array * An associative array of name/value attribute pairs. */ public static function extractHeaderAttributes($headers, $prefix = NULL) { @@ -252,7 +255,8 @@ class Container implements \Countable, \IteratorAggregate { * @param string $url * The base URL. The container name is automatically appended to * this at construction time. - * @retval Container + * @retval HPCloud::Storage::ObjectStorage::Container + * @return \HPCloud\Storage\ObjectStorage\Container * The Container object, initialized and ready for use. */ public static function newFromResponse($name, $response, $token, $url) { @@ -348,6 +352,7 @@ class Container implements \Countable, \IteratorAggregate { * Get the name of this container. * * @retval string + * @return string * The name of the container. */ public function name() { @@ -358,6 +363,7 @@ class Container implements \Countable, \IteratorAggregate { * Get the number of bytes in this container. * * @retval int + * @return int * The number of bytes in this container. */ public function bytes() { @@ -383,6 +389,7 @@ class Container implements \Countable, \IteratorAggregate { * directly does. * * @retval array + * @return array * An array of metadata name/value pairs. */ public function metadata() { @@ -436,6 +443,7 @@ class Container implements \Countable, \IteratorAggregate { * @endcode * * @retval int + * @return int * The number of items in this container. */ public function count() { @@ -458,6 +466,7 @@ class Container implements \Countable, \IteratorAggregate { * An optional file argument that, if set, will be treated as the * contents of the object. * @retval boolean + * @return boolean * TRUE if the object was saved. * @throws HPCloud::Transport::LengthRequiredException * if the Content-Length could not be determined and chunked @@ -577,6 +586,7 @@ class Container implements \Countable, \IteratorAggregate { * The object to update. * * @retval boolean + * @return boolean * TRUE if the metadata was updated. * * @throws HPCloud::Transport::FileNotFoundException @@ -695,7 +705,8 @@ class Container implements \Countable, \IteratorAggregate { * If this is TRUE (the default), then SSL will always be * used. If this is FALSE, then CDN-based fetching will * use non-SSL, which is faster. - * @retval \HPCloud\Storage\ObjectStorage\RemoteObject + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject * A remote object with the content already stored locally. */ public function object($name, $requireSSL = TRUE) { @@ -759,7 +770,8 @@ class Container implements \Countable, \IteratorAggregate { * * @param string $name * The name of the object to fetch. - * @retval \HPCloud\Storage\ObjectStorage\RemoteObject + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject * A remote object ready for use. */ public function proxyObject($name) { @@ -830,6 +842,7 @@ class Container implements \Countable, \IteratorAggregate { * The name of the object to start with. The query will begin with * the next object AFTER this one. * @retval array + * @return array * List of RemoteObject or Subdir instances. */ public function objects($limit = NULL, $marker = NULL) { @@ -891,6 +904,7 @@ class Container implements \Countable, \IteratorAggregate { * The name of the object to start with. The query will begin with * the next object AFTER this one. * @retval array + * @return array * List of RemoteObject or Subdir instances. */ public function objectsWithPrefix($prefix, $delimiter = '/', $limit = NULL, $marker = NULL) { @@ -956,6 +970,7 @@ class Container implements \Countable, \IteratorAggregate { * ObjectStorage::createContainer()) will be accessible by this URL. * * @retval string + * @return string * The URL. */ public function url() { @@ -981,6 +996,7 @@ class Container implements \Countable, \IteratorAggregate { * * @todo Determine how to get the ACL from JSON data. * @retval \HPCloud\Storage\ObjectStorage\ACL + * @return HPCloud::Storage::ObjectStorage::ACL * An ACL, or NULL if the ACL could not be retrieved. */ public function acl() { @@ -1117,6 +1133,7 @@ class Container implements \Countable, \IteratorAggregate { * @param string $name * The name of the object to remove. * @retval boolean + * @return boolean * TRUE if the file was deleted, FALSE if no such file is found. */ public function delete($name) { diff --git a/src/HPCloud/Storage/ObjectStorage/Object.php b/src/HPCloud/Storage/ObjectStorage/Object.php index 253fe42..7c09320 100644 --- a/src/HPCloud/Storage/ObjectStorage/Object.php +++ b/src/HPCloud/Storage/ObjectStorage/Object.php @@ -164,6 +164,7 @@ class Object { * This returns an associative array of all metadata for this object. * * @retval array + * @return array * An associative array of metadata. This may be empty. */ public function metadata() { @@ -200,6 +201,7 @@ class Object { * using setName(), this will return the latest (overwritten) name. * * @retval string + * @return string * The name of the object. */ public function name() { @@ -248,6 +250,7 @@ class Object { * This returns the currently set content type. * * @retval string + * @return string * The content type, including any additional options. */ public function contentType() { @@ -306,6 +309,7 @@ class Object { * returns the entire contents of an object. * * @retval string + * @return string * The content of the file. */ public function content() { @@ -323,7 +327,8 @@ class Object { * When extending this class, you should make sure to calculate the * content length appropriately. * - * return int + * @retval int + * @return int * The length of the content, in bytes. */ public function contentLength() { @@ -341,6 +346,7 @@ class Object { * 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). */ public function eTag() { @@ -383,6 +389,7 @@ class Object { * See setEncoding() for more information. * * @retval string + * @return string * The encoding type. */ public function encoding() { @@ -426,6 +433,7 @@ class Object { * See setDisposition() for discussion. * * @retval string + * @return string * The disposition string, or NULL if none is set. */ public function disposition() { @@ -524,6 +532,7 @@ class Object { * if this returns TRUE, contentLength() is ignored. * * @retval boolean + * @return boolean * TRUE to recommend chunked transfer, FALSE otherwise. */ public function isChunked() { diff --git a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php index 7c7d241..34140bf 100644 --- a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php +++ b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php @@ -210,6 +210,7 @@ class RemoteObject extends Object { * (b) it mirrors non-CDN behavior. This can be turned off by setting * $useSSL to FALSE. * @retval string + * @return string * A URL to the object. The following considerations apply: * - If the container is public, this URL can be loaded without * authentication. You can, for example, pass the URL to a browser @@ -281,6 +282,7 @@ class RemoteObject extends Object { * were sent from the server. * * @retval array + * @return array * An associative array of header names and values. */ public function headers() { @@ -363,6 +365,7 @@ class RemoteObject extends Object { * Be wary of using this method with large files. * * @retval string + * @return string * The contents of the file as a string. * @throws \HPCloud\Transport\FileNotFoundException * when the requested content cannot be located on the remote @@ -429,6 +432,7 @@ class RemoteObject extends Object { * and the content will be refreshed from the server. Any * local changes to the object will be discarded. * @retval resource + * @return resource * A handle to the stream, which is already opened and positioned at * the beginning of the stream. */ @@ -497,6 +501,7 @@ class RemoteObject extends Object { * its contents, not whether anything is actually cached. * * @retval boolean + * @return boolean * TRUE if caching is enabled, FALSE otherwise. */ public function isCaching() { @@ -544,6 +549,7 @@ class RemoteObject extends Object { * supplied ETag hash. * * @retval boolean + * @return boolean * TRUE if this is verifying, FALSE otherwise. */ public function isVerifyingContent() { @@ -622,7 +628,8 @@ class RemoteObject extends Object { * cause the remote host to return the object in the response body. * The response body is not handled, though. If this is set to * FALSE, a HEAD request is sent, and no body is returned. - * @retval \HPCloud\Transport\Response + * @retval HPCloud::Transport::Response + * @return \HPCloud\Transport\Response * containing the object metadata and (depending on the * $fetchContent flag) optionally the data. */ diff --git a/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php b/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php index fd00e6a..f451477 100644 --- a/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php +++ b/src/HPCloud/Storage/ObjectStorage/StreamWrapper.php @@ -407,6 +407,7 @@ class StreamWrapper { * @param int $options * Unused. * @retval boolean + * @return boolean * TRUE if the directory is opened, FALSE otherwise. */ public function dir_opendir($path, $options) { @@ -462,6 +463,7 @@ class StreamWrapper { * @endcode * * @retval string + * @return string * The name of the resource or FALSE when the directory has no more * entries. */ @@ -562,6 +564,7 @@ class StreamWrapper { * @param string $path_to * A swift URL to another path. * @retval boolean + * @return boolean * TRUE on success, FALSE otherwise. */ public function rename($path_from, $path_to) { @@ -609,6 +612,7 @@ class StreamWrapper { * side effects. * * @retval resource + * @return resource * this returns the underlying stream. */ public function stream_cast($cast_as) { @@ -662,6 +666,7 @@ class StreamWrapper { * See stream_seek(). * * @retval boolean + * @return boolean * TRUE if it has reached the end, FALSE otherwise. */ public function stream_eof() { @@ -969,6 +974,7 @@ class StreamWrapper { * @param int $count * The number of bytes to read (usually 8192). * @retval string + * @return string * The data read. */ public function stream_read($count) { @@ -1034,6 +1040,7 @@ class StreamWrapper { * etc.) through HPCloud::Bootstrap::setConfiguration(). * * @retval array + * @return array * The stats array. */ public function stream_stat() { @@ -1052,6 +1059,7 @@ class StreamWrapper { * See ftell() and fseek(). * * @retval int + * @return int * The current position in the stream. */ public function stream_tell() { @@ -1068,6 +1076,7 @@ class StreamWrapper { * @param string $data * Data to write to the stream. * @retval int + * @return int * The number of bytes written. 0 indicates and error. */ public function stream_write($data) { @@ -1094,6 +1103,7 @@ class StreamWrapper { * @param string $path * The URL. * @retval boolean + * @return boolean * TRUE if the file was deleted, FALSE otherwise. */ public function unlink($path) { @@ -1409,6 +1419,7 @@ class StreamWrapper { * @param mixed $default * The default value to return if no config param was found. * @retval mixed + * @return mixed * The discovered result, or $default if specified, or NULL if * no $default is specified. */ @@ -1455,6 +1466,7 @@ class StreamWrapper { * @param string $url * A Swift URL. * @retval array + * @return array * An array as documented in parse_url(). */ protected function parseUrl($url) { diff --git a/src/HPCloud/Storage/ObjectStorage/StreamWrapperFS.php b/src/HPCloud/Storage/ObjectStorage/StreamWrapperFS.php index a9ec5f7..f694b9b 100644 --- a/src/HPCloud/Storage/ObjectStorage/StreamWrapperFS.php +++ b/src/HPCloud/Storage/ObjectStorage/StreamWrapperFS.php @@ -148,7 +148,8 @@ class StreamWrapperFS extends StreamWrapper { * * @param string $path * The directory path to test. - * @retval bool + * @retval boolean + * @return boolean * TRUE if the directory prefix exists and FALSE otherwise. */ protected function testDirectoryExists($path) { diff --git a/src/HPCloud/Storage/ObjectStorage/Subdir.php b/src/HPCloud/Storage/ObjectStorage/Subdir.php index 17152ea..155b5e4 100644 --- a/src/HPCloud/Storage/ObjectStorage/Subdir.php +++ b/src/HPCloud/Storage/ObjectStorage/Subdir.php @@ -61,6 +61,7 @@ class Subdir { * The path is delimited using the string returned by delimiter(). * * @retval string + * @return string * The path. */ public function path() { @@ -70,6 +71,7 @@ class Subdir { * Get the delimiter used by the server. * * @retval string + * @return string * The value used as a delimiter. */ public function delimiter() { diff --git a/src/HPCloud/Transport.php b/src/HPCloud/Transport.php index 2bfe37f..8936e75 100644 --- a/src/HPCloud/Transport.php +++ b/src/HPCloud/Transport.php @@ -72,6 +72,7 @@ class Transport { * @endcode * * @retval HPCloud::Transport::Transporter + * @return \HPCloud\Transport\Transporter * An initialized transporter. */ public static function instance() { diff --git a/src/HPCloud/Transport/CURLTransport.php b/src/HPCloud/Transport/CURLTransport.php index 7f217fa..1f0dd5e 100644 --- a/src/HPCloud/Transport/CURLTransport.php +++ b/src/HPCloud/Transport/CURLTransport.php @@ -278,6 +278,7 @@ class CURLTransport implements Transporter { * @param resource $handle * A CURL handle from curl_init(). * @retval boolean + * @return boolean * Returns a boolean value indicating whether or not CURL could process the * request. */ @@ -322,6 +323,7 @@ class CURLTransport implements Transporter { * @param resource $file * A file pointer to the file that has the headers. * @retval array + * @return array * An array of headers, one header per line. */ protected function fetchHeaders($file) { diff --git a/src/HPCloud/Transport/PHPStreamTransport.php b/src/HPCloud/Transport/PHPStreamTransport.php index 6bde3de..a940c6f 100644 --- a/src/HPCloud/Transport/PHPStreamTransport.php +++ b/src/HPCloud/Transport/PHPStreamTransport.php @@ -207,6 +207,7 @@ class PHPStreamTransport implements Transporter { * @param array $headers * An associative array of header names to header values. * @retval string + * @return string * A string containing formatted headers. */ protected function smashHeaders($headers) { diff --git a/src/HPCloud/Transport/Response.php b/src/HPCloud/Transport/Response.php index 026c0fe..0050684 100644 --- a/src/HPCloud/Transport/Response.php +++ b/src/HPCloud/Transport/Response.php @@ -143,6 +143,7 @@ class Response { * (they are one and the same). * * @retval resource + * @return resource * A file handle. */ public function file() { @@ -162,6 +163,7 @@ class Response { * entire content in a string. * * @retval string + * @return string * The contents of the response body. */ public function content() { @@ -203,6 +205,7 @@ class Response { * data. * * @retval array + * @return array * An associative array of metadata about the * transaction resulting in this response. */ @@ -219,6 +222,7 @@ class Response { * An optional default value. * * @retval mixed + * @return mixed * The value, if found, or the default, is specified, or NULL. */ public function header($name, $default = NULL) { @@ -237,8 +241,9 @@ class Response { * * These are available even if the stream has been closed. * - * @retval - * array The array of headers. + * @retval array + * @return array + * The array of headers. */ public function headers() { return $this->headers; @@ -266,6 +271,7 @@ class Response { * appear in a Response object. * * @retval int + * @return int * The HTTP code, e.g. 200 or 202. */ public function status() { @@ -279,6 +285,7 @@ class Response { * recommendations. e.g. 200 returns 'OK'. * * @retval string + * @return string * A server-generated status message. */ public function statusMessage() { @@ -291,6 +298,7 @@ class Response { * Example: HTTP/1.1 * * @retval string + * @return string * The protocol name and version. */ public function protocol() { @@ -308,6 +316,7 @@ class Response { * An indexed array of headers, as returned by the PHP stream * library. * @retval array + * @return array * An associative array of header name/value pairs. */ protected function parseHeaders($headerArray) { From 029b1065cd8923d90ee4416b5f4307eed17b4cd9 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Thu, 9 Aug 2012 18:42:26 -0400 Subject: [PATCH 5/9] For methods that had no return value return so they can be used in object chaining. --- src/HPCloud/Services/IdentityServices.php | 6 +++ src/HPCloud/Storage/ObjectStorage.php | 6 +++ src/HPCloud/Storage/ObjectStorage/ACL.php | 24 ++++++++++ .../Storage/ObjectStorage/Container.php | 8 ++++ src/HPCloud/Storage/ObjectStorage/Object.php | 6 +++ .../Storage/ObjectStorage/RemoteObject.php | 45 +++++++++++++++++++ 6 files changed, 95 insertions(+) diff --git a/src/HPCloud/Services/IdentityServices.php b/src/HPCloud/Services/IdentityServices.php index 8e2aed4..3e9006e 100644 --- a/src/HPCloud/Services/IdentityServices.php +++ b/src/HPCloud/Services/IdentityServices.php @@ -835,6 +835,10 @@ class IdentityServices /*implements Serializable*/ { * * @param object $response HPCloud::Transport::Response * A response object. + * + * @retval HPCloud::Services::IdentityServices + * @return \HPCloud\Services\IdentityServices + * $this for the current object so it can be used in chaining. */ protected function handleResponse($response) { $json = json_decode($response->content(), TRUE); @@ -843,6 +847,8 @@ class IdentityServices /*implements Serializable*/ { $this->tokenDetails = $json['access']['token']; $this->userDetails = $json['access']['user']; $this->serviceCatalog = $json['access']['serviceCatalog']; + + return $this; } /* Not necessary. diff --git a/src/HPCloud/Storage/ObjectStorage.php b/src/HPCloud/Storage/ObjectStorage.php index 57b22fb..f0c0c61 100644 --- a/src/HPCloud/Storage/ObjectStorage.php +++ b/src/HPCloud/Storage/ObjectStorage.php @@ -247,6 +247,10 @@ class ObjectStorage { * objects in CDN can be older than objects in Swift itself. For that * reason, CDN should not be used when a combination of read and write * operations occur. + * + * @retval HPCloud::Storage::ObjectStorage + * @return \HPCloud\Storage\ObjectStorage + * $this for current object so the method can be used in chaining. */ public function useCDN($cdn) { @@ -270,6 +274,8 @@ class ObjectStorage { } } $this->cdnContainers = $buffer; + + return $this; } public function hasCDN() { diff --git a/src/HPCloud/Storage/ObjectStorage/ACL.php b/src/HPCloud/Storage/ObjectStorage/ACL.php index 8137ff5..e3b068b 100644 --- a/src/HPCloud/Storage/ObjectStorage/ACL.php +++ b/src/HPCloud/Storage/ObjectStorage/ACL.php @@ -323,6 +323,10 @@ class ACL { * @param mixed $user * The name of the user, or optionally an indexed array of user * names. + * + * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL + * $this for current object so the method can be used in chaining. */ public function addAccount($perm, $account, $user = NULL) { $rule = array('account' => $account); @@ -332,6 +336,8 @@ class ACL { } $this->addRule($perm, $rule); + + return $this; } /** @@ -354,9 +360,15 @@ class ACL { * The permission being granted. One of ACL:READ, ACL::WRITE, or ACL::READ_WRITE. * @param string $host * A host specification string as described above. + * + * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL + * $this for current object so the method can be used in chaining. */ public function addReferrer($perm, $host = '*') { $this->addRule($perm, array('host' => $host)); + + return $this; } /** @@ -366,11 +378,17 @@ class ACL { * One of the predefined permission constants. * @param array $rule * A rule array. + * + * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL + * $this for current object so the method can be used in chaining. */ protected function addRule($perm, $rule) { $rule['mask'] = $perm; $this->rules[] = $rule; + + return $this; } /** @@ -383,6 +401,10 @@ class ACL { * * In the current Swift implementation, there is no mechanism for * allowing some hosts to get listings, while denying others. + * + * @retval HPCloud::Storage::ObjectStorage::ACL + * @return \HPCloud\Storage\ObjectStorage\ACL + * $this for current object so the method can be used in chaining. */ public function allowListings() { @@ -390,6 +412,8 @@ class ACL { 'mask' => self::READ, 'rlistings' => TRUE, ); + + return $this; } /** diff --git a/src/HPCloud/Storage/ObjectStorage/Container.php b/src/HPCloud/Storage/ObjectStorage/Container.php index 83a4455..4905c9b 100644 --- a/src/HPCloud/Storage/ObjectStorage/Container.php +++ b/src/HPCloud/Storage/ObjectStorage/Container.php @@ -214,6 +214,10 @@ class Container implements \Countable, \IteratorAggregate { * @param string $url * The base URL. The container name is automatically appended to * this at construction time. + * + * @retval HPCloud::Storage::ObjectStorage::Comtainer + * @return \HPCloud\Storage\ObjectStorage\Container + * A new container object. */ public static function newFromJSON($jsonArray, $token, $url) { $container = new Container($jsonArray['name']); @@ -1011,6 +1015,9 @@ class Container implements \Countable, \IteratorAggregate { * * Not all containers come fully instantiated. This method is sometimes * called to "fill in" missing fields. + * + * @retval HPCloud::Storage::ObjectStorage::Comtainer + * @return \HPCloud\Storage\ObjectStorage\Container */ protected function loadExtraData() { @@ -1039,6 +1046,7 @@ class Container implements \Countable, \IteratorAggregate { $prefix = Container::CONTAINER_METADATA_HEADER_PREFIX; $this->setMetadata(Container::extractHeaderAttributes($response->headers(), $prefix)); + return $this; } /** diff --git a/src/HPCloud/Storage/ObjectStorage/Object.php b/src/HPCloud/Storage/ObjectStorage/Object.php index 7c09320..b9644ae 100644 --- a/src/HPCloud/Storage/ObjectStorage/Object.php +++ b/src/HPCloud/Storage/ObjectStorage/Object.php @@ -508,11 +508,17 @@ class Object { * * @param array $keys * The header names to be removed. + * + * @retval HPCloud::Storage::ObjectStorage::Object + * @return \HPCloud\Storage\ObjectStorage\Object + * $this for the current object so it can be used in chaining methods. */ public function removeHeaders($keys) { foreach ($keys as $k) { unset($this->additionalHeaders[$k]); } + + return $this; } /** diff --git a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php index 34140bf..5a78867 100644 --- a/src/HPCloud/Storage/ObjectStorage/RemoteObject.php +++ b/src/HPCloud/Storage/ObjectStorage/RemoteObject.php @@ -121,6 +121,10 @@ class RemoteObject extends Object { * CDN URL when requested. * @param string $cdnSslUrl * The URL to the SSL-protected CDN version of the object. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * A new RemoteObject. */ public static function newFromHeaders($name, $headers, $token, $url, $cdnUrl = NULL, $cdnSslUrl = NULL) { $object = new RemoteObject($name); @@ -183,10 +187,16 @@ class RemoteObject extends Object { * The URL to this object in CDN. * @param string $sslUrl * The SSL URL to this object in CDN. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this for the current object so it can be used in chaining methods. */ public function useCDN($url, $sslUrl) { $this->cdnUrl = $url; $this->cdnSslUrl = $sslUrl; + + return $this; } /** @@ -261,6 +271,13 @@ class RemoteObject extends Object { return $this->metadata; } + /** + * Set the headers + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this for the current object so it can be used in chaining methods. + */ public function setHeaders($headers) { $this->allHeaders = array(); @@ -311,6 +328,14 @@ class RemoteObject extends Object { 'transfer-encoding' => TRUE, 'x-trans-id' => TRUE, ); + + /** + * Filter the headers. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this for the current object so it can be used in chaining methods. + */ public function filterHeaders(&$headers) { $unset = array(); foreach ($headers as $name => $value) { @@ -322,6 +347,8 @@ class RemoteObject extends Object { foreach ($unset as $u) { unset($headers[$u]); } + + return $this; } /** @@ -341,12 +368,18 @@ class RemoteObject extends Object { * * @param array $keys * The header names to be removed. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this for the current object so it can be used in chaining methods. */ public function removeHeaders($keys) { foreach ($keys as $key) { unset($this->allHeaders[$key]); unset($this->additionalHeaders[$key]); } + + return $this; } /** @@ -606,6 +639,10 @@ class RemoteObject extends Object { * * @param boolean $fetchContent * If this is TRUE, the content will be downloaded as well. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this for the current object so it can be used in chaining methods. */ public function refresh($fetchContent = FALSE) { @@ -618,6 +655,8 @@ class RemoteObject extends Object { if ($fetchContent) { $this->setContent($response->content()); } + + return $this; } /** @@ -661,6 +700,10 @@ class RemoteObject extends Object { * Extract information from HTTP headers. * * This is used internally to set object properties from headers. + * + * @retval HPCloud::Storage::ObjectStorage::RemoteObject + * @return \HPCloud\Storage\ObjectStorage\RemoteObject + * $this for the current object so it can be used in chaining methods. */ protected function extractFromHeaders($response) { $this->setContentType($response->header('Content-Type', $this->contentType())); @@ -674,5 +717,7 @@ class RemoteObject extends Object { // Reset the metadata, too: $this->setMetadata(Container::extractHeaderAttributes($response->headers())); + return $this; + } } From 8a4333e0cb22fd41e545df09521b56fcb22ff9ee Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Thu, 9 Aug 2012 19:49:14 -0400 Subject: [PATCH 6/9] Added dbaas test config. --- test/example.settings.ini | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/test/example.settings.ini b/test/example.settings.ini index 4e03212..cb7311d 100644 --- a/test/example.settings.ini +++ b/test/example.settings.ini @@ -33,6 +33,12 @@ hpcloud.identity.password = hpcloud.identity.account = hpcloud.identity.secret = +;;;;;;;;;;;;;;;;;;;;;;;;; +; Database as a Service ; +;;;;;;;;;;;;;;;;;;;;;;;;; + +hpcloud.dbaas.database = "ponycorns" + ;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; Configuration Parameters ; ;;;;;;;;;;;;;;;;;;;;;;;;;;;; From 561ac0cbdfe9c67607e5966f89b056d5468416d0 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Thu, 9 Aug 2012 20:13:43 -0400 Subject: [PATCH 7/9] Disabled an instance test. --- test/Tests/DBaaSInstanceTest.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/test/Tests/DBaaSInstanceTest.php b/test/Tests/DBaaSInstanceTest.php index 486eefa..6771367 100644 --- a/test/Tests/DBaaSInstanceTest.php +++ b/test/Tests/DBaaSInstanceTest.php @@ -41,11 +41,11 @@ class DBaaSInstanceTest extends DBaaSTestCase { $ident = $this->identity(); $dbaas = DBaaS::newFromIdentity($ident); - $endpoint = self::conf('hpcloud.dbaas.endpoint') . '/' . $ident->tenantId(); + // $endpoint = self::conf('hpcloud.dbaas.endpoint') . '/' . $ident->tenantId(); - // Test #1: Build from scratch. - $inst = new Instance($ident->token(), $ident->tenantName(), $endpoint); - $this->assertInstanceOf('\HPCloud\Services\DBaaS\Instance', $inst); + // // Test #1: Build from scratch. + // $inst = new Instance($ident->token(), $ident->tenantName(), $endpoint); + // $this->assertInstanceOf('\HPCloud\Services\DBaaS\Instance', $inst); // Test #2: Build from DBaaS. $inst = $dbaas->instance(); From 41e0c1e7e915f9647fcdeb781fcebf6cc6b13bfc Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Thu, 9 Aug 2012 20:28:50 -0400 Subject: [PATCH 8/9] Added myself to the composer.json file. --- composer.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/composer.json b/composer.json index 8a3fe97..1b6a189 100644 --- a/composer.json +++ b/composer.json @@ -9,6 +9,10 @@ { "name": "M Butcher", "email": "matthew.butcher@hp.com" + }, + { + "name": "Matt Farina", + "email": "matthew.farina@hp.com" } ], "require": { From 2b1614e22385280ad3f39116739b94d438e23766 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Thu, 9 Aug 2012 21:06:39 -0400 Subject: [PATCH 9/9] Added a note about versions. Released products from HP Cloud will follow semantic versioning. Beta products from HP Cloud are beta in the bindings. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 090ced6..568039d 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,9 @@ Coming soon: We also have support for using PHP's native HTTP stream wrapper, but it is not as reliable. We recommend cURL. -## Warnings +## Versioning -The API for services in beta (e.g., DBaaS) should be considered beta as well. +We have a goal to be as consistent as possible with [Semantic Versioning](http://semver.org/). For released HP Cloud services this is what you can expect. For products in beta expect the included components to be in beta. For example, [HP Cloud Relational Database for MySQL](https://www.hpcloud.com/products/RDB) (our DBaaS offering) is private beta. ## Installation