Merge pull request #546 from ycombinator/gh-545

Return array of DataObjects if such is requested.

Author: ycombinator

docs/userguide/ObjectStore/USERGUIDE.md

@@ -198,7 +198,8 @@ $localFileName  = '/path/to/local/php-elephant.jpg';
 $remoteFileName = 'php-elephant.jpg';
 
 $fileData = fopen($localFileName, 'r');
-$container->uploadObject($remoteFileName, $fileData);
+$object = $container->uploadObject($remoteFileName, $fileData);
+/** @var $object OpenCloud\ObjectStore\Resource\DataObject **/
 ```
 [ [Get the executable PHP script for this example](/samples/ObjectStore/upload-object.php) ]
 
@@ -258,15 +259,18 @@ $objects = array(
     a
 );
 
-$container->uploadObjects($objects);
+$responses = $container->uploadObjects($objects);
+foreach ($responses as $response) {
+    /** @var $response \Guzzle\Http\Message\Response **/
+}
 ```
 [ [Get the executable PHP script for this example](/samples/ObjectStore/upload-multiple-objects.php) ]
 
 In the above example, the contents of two files present on the local filesystem are uploaded as objects to the container referenced by `$container`.
 
 Instead of specifying the `path` key in an element of the `$objects` array, you can specify a `body` key whose value is a string or a stream representation.
 
-Finally, you can pass headers as the second parameter to the `uploadObjects` method. These headers will be applied to every object that is uploaded.
+You can pass headers as the second parameter to the `uploadObjects` method. These headers will be applied to every object that is uploaded.
 
 ```
 $metadata = array('author' => 'Jane Doe');
@@ -281,6 +285,17 @@ $container->uploadObjects($objects, $allHeaders);
 
 In the example above, every object referenced within the `$objects` array will be uploaded with the same metadata.
 
+Finally, if you want the `uploadObjects` method to return an array of `OpenCloud\ObjectStore\Resource\DataObject` objects instead of an array of `Guzzle\Http\Message\Response` objects, you can specify a third parameter to the `uploadObjects` method:
+
+```
+use OpenCloud\ObjectStore\Enum\ReturnType;
+
+$dataObjects = $container->uploadObjects($objects, $allHeaders, ReturnType::DATA_OBJECT_ARRAY);
+foreach ($dataObjects as $dataObject) {
+    /** @var $dataObject OpenCloud\ObjectStore\Resource\DataObject **/
+}
+```
+
 ### Large Objects
 
 If you want to upload objects larger than 5GB in size, you must use a different upload process.

lib/OpenCloud/ObjectStore/Enum/ReturnType.php

@@ -0,0 +1,29 @@
+<?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\ObjectStore\Enum;
+
+/**
+ * Enumerated types for return types
+ *
+ * @package OpenCloud\ObjectStore\Enum
+ */
+class ReturnType
+{
+    const RESPONSE_ARRAY = 'RESPONSE_ARRAY';
+    const DATA_OBJECT_ARRAY = 'DATA_OBJECT_ARRAY';
+}

lib/OpenCloud/ObjectStore/Resource/Container.php

@@ -30,6 +30,7 @@
 use OpenCloud\ObjectStore\Exception\ObjectNotFoundException;
 use OpenCloud\ObjectStore\Upload\DirectorySync;
 use OpenCloud\ObjectStore\Upload\TransferBuilder;
+use OpenCloud\ObjectStore\Enum\ReturnType;
 
 /**
  * A container is a storage compartment for your data and provides a way for you
@@ -471,11 +472,14 @@ public function uploadObject($name, $data, array $headers = array())
      *                       `path' Path to an existing file, OR
      *                       `body' Either a string or stream representation of the file contents to be uploaded.
      * @param array $headers Optional headers that will be sent with the request (useful for object metadata).
+     * @param string $returnType One of OpenCloud\ObjectStore\Enum\ReturnType::RESPONSE_ARRAY (to return an array of
+     *                           Guzzle\Http\Message\Response objects) or OpenCloud\ObjectStore\Enum\ReturnType::DATA_OBJECT_ARRAY
+     *                           (to return an array of OpenCloud\ObjectStore\Resource\DataObject objects).
      *
      * @throws \OpenCloud\Common\Exceptions\InvalidArgumentError
-     * @return \Guzzle\Http\Message\Response
+     * @return Guzzle\Http\Message\Response[] or OpenCloud\ObjectStore\Resource\DataObject[] depending on $returnType
      */
-    public function uploadObjects(array $files, array $commonHeaders = array())
+    public function uploadObjects(array $files, array $commonHeaders = array(), $returnType = ReturnType::RESPONSE_ARRAY)
     {
         $requests = $entities = array();
 
@@ -514,11 +518,22 @@ public function uploadObjects(array $files, array $commonHeaders = array())
 
         $responses = $this->getClient()->send($requests);
 
-        foreach ($entities as $entity) {
-            $entity->close();
+        if (ReturnType::RESPONSE_ARRAY === $returnType) {
+            foreach ($entities as $entity) {
+                $entity->close();
+            }
+            return $responses;
+        } else {
+            // Convert responses to DataObjects before returning
+            $dataObjects = array();
+            foreach ($responses as $index => $response) {
+                $dataObjects[] = $this->dataObject()
+                               ->populateFromResponse($response)
+                               ->setName($files[$index]['name'])
+                               ->setContent($entities[$index]);
+            }
+            return $dataObjects;
         }
-
-        return $responses;
     }
 
     /**

tests/OpenCloud/Tests/ObjectStore/Resource/ContainerTest.php

@@ -20,6 +20,7 @@
 use Guzzle\Http\Message\Response;
 use OpenCloud\Common\Constants\Size;
 use OpenCloud\Tests\ObjectStore\ObjectStoreTestCase;
+use OpenCloud\ObjectStore\Enum\ReturnType;
 
 class ContainerTest extends ObjectStoreTestCase
 {
@@ -225,6 +226,39 @@ public function test_Upload_Multiple()
         ));
     }
 
+    public function test_Upload_Multiple_Return_DataObject_Array()
+    {
+        $tempFileName = tempnam(sys_get_temp_dir(), "php-opencloud-test-");
+
+        $tempFile = fopen($tempFileName, 'w+');
+        fwrite($tempFile, 'BAZQUX');
+
+        $container = $this->container;
+
+        $dataObjects = $container->uploadObjects(array(
+            array('name' => 'test1', 'body' => 'FOOBAR'),
+            array('name' => 'test2', 'path' => $tempFileName),
+            array('name' => 'test2', 'body' => 'BARBAR')
+        ), array(), ReturnType::DATA_OBJECT_ARRAY);
+        fclose($tempFile);
+        unlink($tempFileName);
+
+        $this->assertInstanceOf('OpenCloud\ObjectStore\Resource\DataObject', $dataObjects[0]);
+        $this->assertEquals('test1', $dataObjects[0]->getName());
+        $this->assertInstanceOf('Guzzle\Http\EntityBody', $dataObjects[0]->getContent());
+        $this->assertEquals('FOOBAR', (string) $dataObjects[0]->getContent());
+
+        $this->assertInstanceOf('OpenCloud\ObjectStore\Resource\DataObject', $dataObjects[1]);
+        $this->assertEquals('test2', $dataObjects[1]->getName());
+        $this->assertInstanceOf('Guzzle\Http\EntityBody', $dataObjects[1]->getContent());
+        $this->assertEquals('BAZQUX', (string) $dataObjects[1]->getContent());
+
+        $this->assertInstanceOf('OpenCloud\ObjectStore\Resource\DataObject', $dataObjects[2]);
+        $this->assertEquals('test2', $dataObjects[2]->getName());
+        $this->assertInstanceOf('Guzzle\Http\EntityBody', $dataObjects[2]->getContent());
+        $this->assertEquals('BARBAR', (string) $dataObjects[2]->getContent());
+    }
+
     public function test_Upload()
     {
         $this->assertInstanceOf(