Merge pull request #583 from rackspace/working

Merging working into master in preparation for minor version bump

Author: ycombinator

.travis.yml

@@ -3,7 +3,6 @@ php:
   - "5.6"
   - "5.5"
   - "5.4"
-  - "5.3"
   - hhvm
 
 sudo: false
@@ -33,4 +32,4 @@ notifications:
     - [email protected]
 
 env:
-  - secure: "bdrUeYb3nSGgBB+QtDZxUHVPw6B/wjb3KXLm8TgonWrQm4GPeWKK29qhmDnFZmQjwQPfuebe7wAk1ZxGoZKbEiELVpJJ+8XYVOt6W/6V53H31JL6FqiIE5+7qBwDe+9ziveM6GcTXHT1GI5mUeACIbeBDPZaNubIJH3U6MPim64="
+  - secure: "bdrUeYb3nSGgBB+QtDZxUHVPw6B/wjb3KXLm8TgonWrQm4GPeWKK29qhmDnFZmQjwQPfuebe7wAk1ZxGoZKbEiELVpJJ+8XYVOt6W/6V53H31JL6FqiIE5+7qBwDe+9ziveM6GcTXHT1GI5mUeACIbeBDPZaNubIJH3U6MPim64="

README.md

@@ -4,7 +4,7 @@ PHP SDK for OpenStack/Rackspace APIs
 
 [![Latest Stable Version](https://poser.pugx.org/rackspace/php-opencloud/v/stable.png)](https://packagist.org/packages/rackspace/php-opencloud) [![Travis CI](https://secure.travis-ci.org/rackspace/php-opencloud.png)](https://travis-ci.org/rackspace/php-opencloud) [![Total Downloads](https://poser.pugx.org/rackspace/php-opencloud/downloads.png)](https://packagist.org/packages/rackspace/php-opencloud)
 
-For SDKs in different languages, see http://developer.rackspace.com.
+Our official documentation is now available on http://docs.php-opencloud.com. For SDKs in different languages, see http://developer.rackspace.com.
 
 The PHP SDK should work with most OpenStack-based cloud deployments,
 though it specifically targets the Rackspace public cloud. In
@@ -16,9 +16,11 @@ so that you can still use the SDK with a pure OpenStack instance
 
 Requirements
 ------------
-* PHP >=5.3.3
+* PHP >=5.4
 * cURL extension for PHP
 
+**Note**: Since PHP 5.3 has reached [end of life](http://php.net/eol.php) and is no longer officially supported, we are moving to 5.4 as a minimum requirement. If upgrading is not an option and you still need a stable version of the SDK for 5.3, please follow [this guide](http://docs.php-opencloud.com/en/latest/using-php-5.3).
+
 Installation
 ------------
 You must install this library through Composer:

composer.json

@@ -26,7 +26,7 @@
         }
     },
     "require": {
-        "php" : ">=5.3.3",
+        "php" : ">=5.4",
         "guzzle/guzzle" : "~3.8",
         "psr/log": "~1.0"
     },
@@ -35,6 +35,6 @@
         "satooshi/php-coveralls": "0.6.*@dev",
         "jakub-onderka/php-parallel-lint": "0.*",
         "fabpot/php-cs-fixer": "1.0.*@dev",
-        "apigen/apigen": "~2.8"
+        "apigen/apigen": "~4.0"
     }
 }

doc/index.rst

@@ -30,6 +30,10 @@ Read the :doc:`getting-started-with-openstack` or
 :doc:`getting-started-with-rackspace` to help you get started with basic
 Compute operations.
 
+.. note::
+
+  If you are running PHP 5.3, please see our :doc:`using-php-5.3` guide.
+
 Services
 --------
 

doc/services/common/service-args.rst

@@ -3,9 +3,9 @@
   default will be provided if you pass in ``null``.
 
 * ``{region}`` is the region the service will operate in. For Rackspace
-  users, you can select one of the following from the `supported regions page
-  </regions>`_.
+  users, you can select one of the following from the :doc:`supported regions page
+  </regions>`.
 
-* ``{urlType}`` is the `type of URL </url-types>`_ to use, depending on which
+* ``{urlType}`` is the :doc:`type of URL </url-types>` to use, depending on which
   endpoints your catalog provides. If omitted, it will default to the public
   network.

doc/services/dns/domains.rst

@@ -268,8 +268,8 @@ Modify domain
 
 Only the TTL, email address and comment attributes of a domain can be modified.
 Records cannot be added, modified, or removed through this API operation - you
-will need to use the `add records <records#add-record>`__, `modify records
-<records#modify-record>`__ or `remove records <records#delete-record>`__
+will need to use the `add records <records.html#add-record>`__, `modify records
+<records.html#modify-record>`__ or `remove records <records.html#delete-record>`__
 operations respectively.
 
 .. code-block:: php

doc/services/object-store/migrating-containers.rst

@@ -68,12 +68,12 @@ You can access all this functionality by executing:
 
 
 It's advisable to do this process in a Cloud Server in one of the two
-regions you're migrating to/from. This allows you to use ``privateURL``
+regions you're migrating to/from. This allows you to use ``internalURL``
 as the third argument in the ``objectStoreService`` methods like this:
 
 .. code-block:: php
 
-  $client->objectStoreService('cloudFiles', 'IAD', 'privateURL');
+  $client->objectStoreService('cloudFiles', 'IAD', 'internalURL');
 
 
 This will ensure that traffic between your server and your new IAD

doc/services/object-store/objects.rst

@@ -177,6 +177,42 @@ docs <http://docs.openstack.org/api/openstack-object-storage/1.0/content/list-ob
 `Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/ObjectStore/list-objects.php>`_
 
 
+List over 10,000 objects
+------------------------
+
+To retrieve more than 10,000 objects (the default limit), you'll need to use
+the built-in paging which uses a 'marker' parameter to fetch the next page of data.
+
+.. code-block:: php
+
+    $containerObjects = array();
+    $marker = '';
+
+    while ($marker !== null) {
+        $params = array(
+            'marker' => $marker,
+        );
+
+        $objects = $container->objectList($params);
+        $total = $objects->count();
+        $count = 0;
+
+        if ($total == 0) {
+            break;
+        }
+
+        foreach ($objects as $object) {
+            /** @var $object OpenCloud\ObjectStore\Resource\DataObject **/
+            $containerObjects[] = $object->getName();
+            $count++;
+
+            $marker = ($count == $total) ? $object->getName() : null;
+        }
+    }
+
+`Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/ObjectStore/list-objects-over-10000.php>`_
+
+
 Get object
 ----------
 
@@ -204,8 +240,8 @@ Get file name
 
 .. code-block:: php
 
-  /** @param $container OpenCloud\ObjectStore\Resource\Container */
-  $container = $object->getContainer();
+  /** @param $name string */
+  $name = $object->getName();
 
 
 Get file size
@@ -326,6 +362,41 @@ the name of the object inside the container that does not exist yet.
 `Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/ObjectStore/copy-object.php>`_
 
 
+Symlinking to this object from another location
+-----------------------------------------------
+
+To create a symlink to this file in another location you need to specify
+a string-based source
+
+.. code-block:: php
+
+  $object->createSymlinkFrom('/container_2/new_object_name');
+
+Where ``container_2`` is the name of the container, and ``new_object_name`` is
+the name of the object inside the container that either does not exist yet or
+is an empty file.
+
+`Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/ObjectStore/symlink-object.php>`_
+
+
+Setting this object to symlink to another location
+--------------------------------------------------
+
+To set this file to symlink to another location you need to specify
+a string-based destination
+
+.. code-block:: php
+
+  $object->createSymlinkTo('/container_2/new_object_name');
+
+Where ``container_2`` is the name of the container, and ``new_object_name`` is
+the name of the object inside the container.
+
+The object must be an empty file.
+
+`Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/ObjectStore/symlink-object.php>`_
+
+
 Get object metadata
 -------------------
 

doc/using-php-5.3.rst

@@ -0,0 +1,20 @@
+Using the SDK with PHP v5.3
+===========================
+
+Since PHP 5.3 has entered EOL and no longer receives security updates, we have bumped the minimum requirement to 5.4. Using 5.3 is still possible, however, but you will need to use an older stable version of the SDK. There are two ways to do this.
+
+The first way is by requiring it through the command line:
+
+.. code-block:: bash
+
+  composer require rackspace/php-opencloud:1.12
+
+The second way is by updating your composer.json file, and specifying the appropriate version of the SDK:
+
+.. code-block:: json
+
+  "require": {
+    "rackspace/php-opencloud": "~1.12"
+  }
+
+Note that **1.12** is the last minor release supporting PHP 5.3. Version 1.13 and above has shifted to PHP 5.4.

docs/README.md

@@ -0,0 +1,3 @@
+# Documentation
+
+Our official docs are hosted on http://docs.php-opencloud.com.

lib/OpenCloud/Common/Constants/Header.php

@@ -70,4 +70,5 @@ class Header
     const USER_AGENT = 'User-Agent';
     const VARY = 'Vary';
     const VIA = 'Via';
+    const X_OBJECT_MANIFEST = 'X-Object-Manifest';
 }

lib/OpenCloud/Common/Exceptions/DomainNotFoundException.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * Copyright 2012-2014 Rackspace US, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace OpenCloud\Common\Exceptions;
+
+class DomainNotFoundException extends \Exception
+{
+}

lib/OpenCloud/Compute/Resource/Server.php

@@ -172,6 +172,12 @@ class Server extends NovaResource implements HasPtrRecordsInterface
      */
     public $powerStatus;
 
+    /**
+     * @link http://developer.openstack.org/api-ref-compute-v2-ext.html#ext-os-ext-az
+     * @var string Availability zone of the VM
+     */
+    public $availabilityZone;
+
     protected static $json_name = 'server';
     protected static $url_resource = 'servers';
 
@@ -206,6 +212,7 @@ class Server extends NovaResource implements HasPtrRecordsInterface
         'OS-EXT-STS:vm_state'    => 'extendedStatus',
         'OS-EXT-STS:task_state'  => 'taskStatus',
         'OS-EXT-STS:power_state' => 'powerStatus',
+        'OS-EXT-AZ:availability_zone' => 'availabilityZone'
     );
 
     /**
@@ -729,6 +736,12 @@ protected function createJson()
             $server->user_data = $this->user_data;
         }
 
+        // Availability zone
+        if (!empty($this->availabilityZone)) {
+            $this->checkExtension('OS-EXT-AZ');
+            $server->availability_zone = $this->availabilityZone;
+        }
+
         return (object) array('server' => $server);
     }
 

lib/OpenCloud/Compute/Service.php

@@ -81,7 +81,7 @@ public function __construct(Client $client, $type = null, $name = null, $region
      *
      * @api
      * @param string $id - if specified, the server with the ID is retrieved
-     * @returns Resource\Server object
+     * @return Resource\Server object
      */
     public function server($id = null)
     {
@@ -102,7 +102,7 @@ public function server($id = null)
      *                         not having all the information you need.
      * @param array   $filter  - a set of key/value pairs that is passed to the
      *                         servers list for filtering
-     * @returns \OpenCloud\Common\Collection
+     * @return \OpenCloud\Common\Collection\PaginatedIterator
      */
     public function serverList($details = true, array $filter = array())
     {
@@ -128,7 +128,7 @@ public function network($id = null)
      *
      * @api
      * @param array $filter array of filter key/value pairs
-     * @return \OpenCloud\Common\Collection
+     * @return \OpenCloud\Common\Collection\PaginatedIterator
      */
     public function networkList($filter = array())
     {

lib/OpenCloud/DNS/Resource/Domain.php

@@ -76,7 +76,7 @@ public function record($info = null)
      * returns a Collection of Record objects
      *
      * @param array $filter query-string parameters
-     * @return \OpenCloud\Collection
+     * @return OpenCloud\DNS\Collection\DnsIterator
      */
     public function recordList($filter = array())
     {
@@ -107,6 +107,7 @@ public function subdomain($info = array())
      *
      * @param array $filter key/value pairs for query string parameters
      *                      return \OpenCloud\Collection
+     * @return OpenCloud\DNS\Collection\DnsIterator
      */
     public function subdomainList($filter = array())
     {

lib/OpenCloud/DNS/Service.php

@@ -19,6 +19,7 @@
 
 use OpenCloud\Common\Http\Message\Formatter;
 use OpenCloud\Common\Service\CatalogService;
+use OpenCloud\Common\Exceptions\DomainNotFoundException;
 use OpenCloud\DNS\Collection\DnsIterator;
 use OpenCloud\DNS\Resource\AsyncResponse;
 use OpenCloud\DNS\Resource\Domain;
@@ -55,11 +56,29 @@ public function domain($info = null)
         return $this->resource('Domain', $info);
     }
 
+    /**
+     * Returns a domain, given a domain name
+     *
+     * @param string $domainName Domain name
+     * @return Domain the domain object
+     */
+    public function domainByName($domainName)
+    {
+        $domainList = $this->domainList(array("name" => $domainName));
+
+        if (count($domainList) != 1) {
+            throw new DomainNotFoundException();
+        }
+
+        return $this->resource('Domain', $domainList[0]);
+    }
+
+
     /**
      * Returns a collection of domains
      *
      * @param array $filter key/value pairs to use as query strings
-     * @return \OpenCloud\Common\Collection
+     * @return OpenCloud\DNS\Collection\DnsIterator
      */
     public function domainList($filter = array())
     {
@@ -85,7 +104,7 @@ public function ptrRecord($info = null)
      *
      * @param \OpenCloud\Compute\Resource\Server $server the server for which to
      *                                                   retrieve the PTR records
-     * @return \OpenCloud\Common\Collection
+     * @return OpenCloud\DNS\Collection\DnsIterator
      */
     public function ptrRecordList(HasPtrRecordsInterface $parent)
     {
@@ -181,6 +200,13 @@ public function limitTypes()
         return $body->limitTypes;
     }
 
+    /**
+     * List asynchronous responses' statuses.
+     * @see http://docs.rackspace.com/cdns/api/v1.0/cdns-devguide/content/viewing_status_all_asynch_jobs.html
+     *
+     * @param array $query Any query parameters. Optional.
+     * @return OpenCloud\DNS\Collection\DnsIterator
+     */
     public function listAsyncJobs(array $query = array())
     {
         $url = clone $this->getUrl();