Implementation of Google Cloud Datastore (#101)

* Implementation of Google Cloud Datastore * Refactor API * Implement __get and __set on Datastore\Entity * Datastore entity properties can now be referenced by their names as if they were properties on the instantiated object. Example: ```php $key = $datastore->key('Person', 'Bob'); $entity = $datastore->entity($key, [ 'firstName' => 'Bob', 'lastName' => 'Testguy' ]); $firstName = $entity['firstName']; // is equivalent to $firstName = $entity->firstName; ``` * IDs are allocated in `insertBatch()` rather than `keys()` * Updating entities is now safer. When running `updateBatch()` or `upsertBatch(), manually created entities will not save unless the `allowOverwrite` flag is set. This prevents accidental overwrite of existing data. * DateTime fields now transform back and forth as expected/ * `excludeFromIndexes` is now supported for entity keys. * Transactions have been refactored and improved. * Operation still exists, but it works as an underlying internal API for code reuse, rather than for direct interaction. It supplies functionality to DatastoreClient and Transaction. * Fix namespace propogation and map keys in entity save/fetch * Return useful response from mutate methods * Support concurrency control with baseVersion * Update to API v1 * Code review resolutions * Reorder filter parameters, add short comparison operators * Refactor, support Geopoints * Code review fixes * Update entity mapping * Support mapping different kinds to types
googleapis · Aug 31, 2016 · fb703d6 · fb703d6
1 parent 85889e2
commit fb703d6
Show file tree

Hide file tree

Showing 33 changed files with 8,333 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@ This client supports the following Google Cloud Platform services:
 * [Google BigQuery](#google-bigquery)
 * [Google Stackdriver Logging](#google-stackdriver-logging)
 * [Google Translate](#google-translate)
+* [Google Cloud Datastore](#google-cloud-datastore)
 * [Google Cloud Natural Language](#google-cloud-natural-language)
 * [Google Cloud Pub/Sub](#google-cloud-pubsub)
 * [Google Cloud Storage](#google-cloud-storage)
@@ -145,6 +146,37 @@ foreach ($languages as $language) {
 }
 ```
 
+## Google Cloud Datastore
+
+- [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/datastore/datastoreclient)
+- [Official Documentation](https://cloud.google.com/datastore/docs/)
+
+#### Preview
+
+```php
+require 'vendor/autoload.php';
+
+use Google\Cloud\Datastore\DatastoreClient;
+
+$datastore = new DatastoreClient([
+    'projectId' => 'my_project'
+]);
+
+// Create an entity
+$bob = $datastore->entity('Person');
+$bob['firstName'] = 'Bob';
+$bob['email'] = '[email protected]';
+$datastore->insert($bob);
+
+// Fetch an entity
+$key = $datastore->key('Person', 'Bob');
+$bob = $datastore->lookup($key);
+
+// Update an entity
+$bob['email'] = '[email protected]';
+$datastore->update($bob);
+```
+
 ## Google Cloud Natural Language
 
 - [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/naturallanguage/naturallanguageclient)

diff --git a/docs/toc.json b/docs/toc.json
@@ -55,6 +55,26 @@
         "type": "bigquery/table"
       }]
     },
+    {
+      "title": "Datastore",
+      "type": "datastore/datastoreclient",
+      "nav": [{
+        "title": "Transaction",
+        "type": "datastore/transaction"
+      }, {
+        "title": "Entity",
+        "type": "datastore/entity"
+      }, {
+        "title": "Key",
+        "type": "datastore/key"
+      }, {
+        "title": "Query",
+        "type": "datastore/query/query"
+      }, {
+        "title": "GQL Query",
+        "type": "datastore/query/gqlquery"
+      }]
+    },
     {
       "title": "Logging",
       "type": "logging/loggingclient",

diff --git a/scripts/DocGenerator.php b/scripts/DocGenerator.php
@@ -281,15 +281,18 @@ private function buildExamples($examples)
                 unset($lines[0]);
             }
 
+            $captionLines = [];
             foreach ($lines as $key => $line) {
                 if (substr($line, 0, 2) === '//') {
-                    $caption .= $this->markdown->parse(substr($line, 3));
+                    $captionLines[] = substr($line, 3);
                     unset($lines[$key]);
                 } else {
                     break;
                 }
             }
 
+            $caption = $this->markdown->parse(implode(' ', $captionLines));
+
             $examplesArray[] = [
                 'caption' => $caption,
                 'code' => implode(PHP_EOL, $lines)
@@ -329,15 +332,19 @@ private function buildParams($params)
             $description = $param->getDescription();
             $nestedParamsArray = [];
 
-            if ($param->getType() === 'array' && $this->hasNestedParams($description)) {
+            if (($param->getType() === 'array' || $param->getType() === 'array[]') && $this->hasNestedParams($description)) {
                 $description = substr($description, 1, -1);
                 $nestedParams = explode('@type', $description);
                 $description = trim(array_shift($nestedParams));
                 $nestedParamsArray = $this->buildNestedParams($nestedParams, $param);
             }
 
+            $varName = substr($param->getVariableName(), 1);
+            if (!$varName) {
+                throw new \Exception('invalid or missing parameter name in "'. $param->getDocBlock()->getShortDescription() .'"');
+            }
             $paramsArray[] = [
-                'name' => substr($param->getVariableName(), 1),
+                'name' => $varName,
                 'description' => $this->buildDescription($param->getDocBlock(), $description),
                 'types' => $this->handleTypes($param->getTypes()),
                 'optional' => null, // @todo
@@ -359,7 +366,12 @@ private function buildNestedParams($nestedParams, $origParam)
         $paramsArray = [];
 
         foreach ($nestedParams as $param) {
-            list($type, $name, $description) = explode(' ', trim($param), 3);
+            $nestedParam = explode(' ', trim($param), 3);
+            if (count($nestedParam) < 3) {
+                throw new \Exception('nested param is in an invalid format: '. $param);
+            }
+
+            list($type, $name, $description) = $nestedParam;
             $name = substr($name, 1);
             $description = preg_replace('/\s+/', ' ', $description);
             $types = explode('|', $type);
@@ -418,7 +430,7 @@ private function buildReturns($returns)
         foreach ($returns as $return) {
             $returnsArray[] = [
                 'types' => $this->handleTypes($return->getTypes()),
-                'description' => $this->markdown->parse($return->getDescription())
+                'description' => $this->buildDescription(null, $return->getDescription())
             ];
         }
 

diff --git a/src/Datastore/Connection/ConnectionInterface.php b/src/Datastore/Connection/ConnectionInterface.php
@@ -0,0 +1,55 @@
+<?php
+/**
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * 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\Connection;
+
+/**
+ * Represents a connection to
+ * [Datastore](https://cloud.google.com/datastore/).
+ */
+interface ConnectionInterface
+{
+    /**
+     * @param array $args
+     */
+    public function allocateIds(array $args);
+
+    /**
+     * @param array $args
+     */
+    public function beginTransaction(array $args);
+
+    /**
+     * @param array $args
+     */
+    public function commit(array $args);
+
+    /**
+     * @param array $args
+     */
+    public function lookup(array $args);
+
+    /**
+     * @param array $args
+     */
+    public function rollback(array $args);
+
+    /**
+     * @param array $args
+     */
+    public function runQuery(array $args);
+}
diff --git a/src/Datastore/Connection/Rest.php b/src/Datastore/Connection/Rest.php
@@ -0,0 +1,95 @@
+<?php
+/**
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * 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\Connection;
+
+use Google\Cloud\RequestBuilder;
+use Google\Cloud\RequestWrapper;
+use Google\Cloud\RestTrait;
+use Google\Cloud\UriTrait;
+
+/**
+ * Implementation of the
+ * [Google Datastore JSON API](https://cloud.google.com/datastore/reference/rest/).
+ */
+class Rest implements ConnectionInterface
+{
+    use RestTrait;
+    use UriTrait;
+
+    const BASE_URI = 'https://datastore.googleapis.com/';
+
+    /**
+     * @param array $config
+     */
+    public function __construct(array $config = [])
+    {
+        $this->setRequestWrapper(new RequestWrapper($config));
+        $this->setRequestBuilder(new RequestBuilder(
+            __DIR__ . '/ServiceDefinition/datastore-v1.json',
+            self::BASE_URI
+        ));
+    }
+
+    /**
+     * @param array $args
+     */
+    public function allocateIds(array $args)
+    {
+        return $this->send('projects', 'allocateIds', $args);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function beginTransaction(array $args)
+    {
+        return $this->send('projects', 'beginTransaction', $args);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function commit(array $args)
+    {
+        return $this->send('projects', 'commit', $args);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function lookup(array $args)
+    {
+        return $this->send('projects', 'lookup', $args);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function rollback(array $args)
+    {
+        return $this->send('projects', 'rollback', $args);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function runQuery(array $args)
+    {
+        return $this->send('projects', 'runQuery', $args);
+    }
+}