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.