Convert blobValue back to a resource on fetch (#126)

* Convert blobValue back to a resource on fetch

* Add test coverage to property and exclude mapper

* Add Blob class and client factories

* Store blob values as resource

docs/manifest.json

@@ -6,6 +6,7 @@
   "defaultService": "servicebuilder",
   "markdown": "php",
   "versions": [
+    "v0.7.1",
     "v0.7.0",
     "v0.6.0",
     "v0.5.1",

src/Datastore/Blob.php

@@ -0,0 +1,79 @@
+<?php
+/**
+ * Copyright 2016 Google 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 Google\Cloud\Datastore;
+
+use GuzzleHttp\Psr7;
+use Psr\Http\Message\StreamInterface;
+
+/**
+ * Represents a Blob value.
+ *
+ * Blobs can be used to store binary data in Google Cloud Datastore.
+ *
+ * Example:
+ * ```
+ * $blob = $datastore->blob(file_get_contents(__DIR__ .'/family-photo.jpg'));
+ * ```
+ */
+class Blob
+{
+    /**
+     * @var mixed
+     */
+    private $value;
+
+    /**
+     * Create a blob
+     *
+     * @param string|resource|StreamInterface $value The blob value
+     */
+    public function __construct($value)
+    {
+        $this->value = Psr7\stream_for($value);
+    }
+
+    /**
+     * Get the blob contents as a stream
+     *
+     * Example:
+     * ```
+     * $value = $blob->value();
+     * ```
+     *
+     * @returns StreamInterface
+     */
+    public function get()
+    {
+        return $this->value;
+    }
+
+    /**
+     * Cast the blob to a string
+     *
+     * Example:
+     * ```
+     * echo (string) $blob->value();
+     * ```
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return (string) $this->value;
+    }
+}

src/Datastore/DatastoreClient.php

@@ -311,6 +311,46 @@ public function entity($key, array $entity = [], array $options = [])
         return $this->operation->entity($key, $entity, $options);
     }
 
+    /**
+     * Create a new GeoPoint
+     *
+     * Example:
+     * ```
+     * $geoPoint = $datastore->geoPoint(37.4220, -122.0841);
+     * ```
+     *
+     * @see https://cloud.google.com/datastore/reference/rest/Shared.Types/LatLng LatLng
+     *
+     * @param float $latitude The latitude
+     * @param float $longitude The longitude
+     * @return GeoPoint
+     */
+    public function geoPoint($latitude, $longitude)
+    {
+        return new GeoPoint($latitude, $longitude);
+    }
+
+    /**
+     * Create a new Blob
+     *
+     * Example:
+     * ```
+     * $blob = $datastore->blob('hello world');
+     * ```
+     *
+     * ```
+     * // Blobs can be used to store binary data
+     * $blob = $datastore->blob(file_get_contents(__DIR__ .'/family-photo.jpg'));
+     * ```
+     *
+     * @param string|resource|StreamInterface $value
+     * @return Blob
+     */
+    public function blob($value)
+    {
+        return new Blob($value);
+    }
+
     /**
      * Allocates an available ID to a given incomplete key
      *

src/Datastore/Entity.php

@@ -27,6 +27,26 @@
  * Entity implements PHP's [ArrayAccess](http://php.net/arrayaccess), allowing
  * access via the array syntax (example below).
  *
+ * Properties are mapped automatically to their corresponding Datastore value
+ * types. Refer to the table below for a guide to how types are stored.
+ *
+ * | **PHP Type**                               | **Datastore Value Type**             |
+ * |--------------------------------------------|--------------------------------------|
+ * | `\DateTimeInterface`                       | `timestampValue`                     |
+ * | {@see Google\Cloud\Datastore\Key}          | `keyValue`                           |
+ * | {@see Google\Cloud\Datastore\GeoPoint}     | `geoPointValue`                      |
+ * | {@see Google\Cloud\Datastore\Entity}       | `entityValue`                        |
+ * | {@see Google\Cloud\Datastore\Blob}         | `blobValue`                          |
+ * | Associative Array                          | `entityValue` (No Key)               |
+ * | Non-Associative Array                      | `arrayValue`                         |
+ * | `float`                                    | `doubleValue`                        |
+ * | `int`                                      | `integerValue`                       |
+ * | `string`                                   | `stringValue`                        |
+ * | `resource`                                 | `blobValue`                          |
+ * | `NULL`                                     | `nullValue`                          |
+ * | `bool`                                     | `booleanValue`                       |
+ * | `object` (Outside types specified above)   | **ERROR** `InvalidArgumentException` |
+ *
  * Example:
  * ```
  * use Google\Cloud\ServiceBuilder;

src/Datastore/EntityMapper.php

@@ -81,8 +81,6 @@ public function responseToExcludeFromIndexes(array $entityData)
         $excludes = [];
 
         foreach ($entityData as $key => $property) {
-            $type = key($property);
-
             if (isset($property['excludeFromIndexes']) && $property['excludeFromIndexes']) {
                 $excludes[] = $key;
             }
@@ -205,6 +203,15 @@ public function convertValue($type, $value)
 
                 break;
 
+            case 'blobValue':
+                if ($this->isEncoded($value)) {
+                    $value = base64_decode($value);
+                }
+
+                $result = new Blob($value);
+
+                break;
+
             default:
                 $result = $value;
                 break;
@@ -316,16 +323,25 @@ public function valueObject($value, $exclude = false)
     public function objectProperty($value)
     {
         switch (true) {
+            case $value instanceof Blob:
+                return [
+                    'blobValue' => ($this->encode)
+                        ? base64_encode((string) $value)
+                        : (string) $value
+                ];
+
+                break;
+
             case $value instanceof \DateTimeInterface:
                 return [
                     'timestampValue' => $value->format(\DateTime::RFC3339)
                 ];
 
                 break;
 
-            case $value instanceof Key:
+            case $value instanceof Entity:
                 return [
-                    'keyValue' => $value->keyObject()
+                    'entityValue' => $this->objectToRequest($value)
                 ];
 
                 break;
@@ -337,11 +353,13 @@ public function objectProperty($value)
 
                 break;
 
-            case $value instanceof Entity:
+            case $value instanceof Key:
                 return [
-                    'entityValue' => $this->objectToRequest($value)
+                    'keyValue' => $value->keyObject()
                 ];
 
+                break;
+
             default:
                 throw new InvalidArgumentException(
                     sprintf('Value of type `%s` could not be serialized', get_class($value))
@@ -390,4 +408,25 @@ private function convertArrayToEntityValue(array $value)
             ]
         ];
     }
+
+    private function isEncoded($value)
+    {
+        // Check if there are valid base64 characters
+        if (!preg_match('/^[a-zA-Z0-9\/\r\n+]*={0,2}$/', $value)) {
+            return false;
+        }
+
+        // Decode the string in strict mode and check the results
+        $decoded = base64_decode($value, true);
+        if ($decoded == false) {
+            return false;
+        }
+
+        // Encode the string again
+        if (base64_encode($decoded) != $value) {
+            return false;
+        }
+
+        return true;
+    }
 }

src/ServiceBuilder.php

@@ -46,7 +46,7 @@
  */
 class ServiceBuilder
 {
-    const VERSION = '0.7.0';
+    const VERSION = '0.7.1';
 
     /**
      * @var array Configuration options to be used between clients.

tests/Datastore/BlobTest.php

@@ -0,0 +1,56 @@
+<?php
+/**
+ * Copyright 2016 Google 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 Google\Cloud\Tests\Datastore;
+
+use Google\Cloud\Datastore\Blob;
+use GuzzleHttp\Psr7;
+
+/**
+ * @group datastore
+ */
+class BlobTest extends \PHPUnit_Framework_TestCase
+{
+    public function testBlobString()
+    {
+        $blob = new Blob('hello world');
+        $this->assertEquals('hello world', (string) $blob);
+    }
+
+    public function testBlobResource()
+    {
+        $string = 'hello world';
+        $stream = fopen('php://memory','r+');
+        fwrite($stream, $string);
+        rewind($stream);
+
+        $blob = new Blob($stream);
+        $this->assertEquals('hello world', (string) $blob);
+    }
+
+    public function testBlobStreamInterface()
+    {
+        $blob = new Blob(Psr7\stream_for('hello world'));
+        $this->assertEquals('hello world', (string) $blob);
+    }
+
+    public function testToString()
+    {
+        $blob = new Blob('hello world');
+        $this->assertEquals((string)$blob->get(), (string) $blob);
+    }
+}

tests/Datastore/DatastoreClientTest.php

@@ -17,9 +17,11 @@
 
 namespace Google\Cloud\Tests\Datastore;
 
+use Google\Cloud\Datastore\Blob;
 use Google\Cloud\Datastore\Connection\ConnectionInterface;
 use Google\Cloud\Datastore\DatastoreClient;
 use Google\Cloud\Datastore\Entity;
+use Google\Cloud\Datastore\GeoPoint;
 use Google\Cloud\Datastore\Key;
 use Google\Cloud\Datastore\Operation;
 use Google\Cloud\Datastore\Query\GqlQuery;
@@ -144,6 +146,23 @@ public function testEntity()
         $this->assertEquals($entity['foo'], 'bar');
     }
 
+    public function testBlob()
+    {
+        $blob = $this->datastore->blob('foo');
+        $this->assertInstanceOf(Blob::class, $blob);
+        $this->assertEquals('foo', (string) $blob);
+    }
+
+    public function testGeoPoint()
+    {
+        $point = $this->datastore->geoPoint(1.1, 0.1);
+        $this->assertInstanceOf(GeoPoint::class, $point);
+        $this->assertEquals($point->point(), [
+            'latitude' => 1.1,
+            'longitude' => 0.1
+        ]);
+    }
+
     public function testAllocateId()
     {
         $datastore = new DatastoreClientStubNoService;