Introduce Cloud Firestore (#693)

* Add firestore protobuf classes

* Add Firestore public API classes

* Add firestore gapic

* Update composer for protos

* send API call

* Get a document.

* Add value mapping and move data objects to core

* Encode values and insert documents

* Add WriteBatch

* Update and delete documents

* Support FIELD DELETE Sentinel value

* Implement remainder of Collection and Document methods

* Start implementing firestore transactions

* Firestore Query beginning

* Implement remaining Query methods

* Get documents, add Query class

* WIP

* Remove unused connection methods

* Reorganize writer methods

* Fix field path decoding

* Rename Document to DocumentReference

* Documentation

* Manage Sentinel Values

* Rename Collection -> CollectionReference

* Unit Tests

* Fix regression in Cloud Spanner

* Setup docs and component

* Add Firestore Snippet Tests

* Fix firestore snapshot

* Add some system tests

* refresh gapic

* refresh client config

* Add system tests

* Run Query and yield Document Snapshots

* WIP

* Fix firestore tests

* rename method with reserved name

* update phpunit version

* Remove Protos

* Retry query if initial call fails

* Retry queries if the call fails up front

* Update for proto fix

* begin addressing code review

* Implement FieldPath class, escaping, and query fixes

* Add Transaction::runQuery()

* Add support for Unary Query Filters

* Split SnapshotTrait::createSnapshot into two methods

* Remove Firestore Admin GAPIC Client

* Docs and syntax fixes

* Update unit tests

* CollectionReference extends Query

* Fix tests and documentation

* Extend Unit Test coverage

* Update snippet tests

* Address code review

* Fix tests for hhvm

* Replace DocumentSnapshot::info() with timestamp methods

* Add API reference links

* Add system test coverage

* Remove test for example that doesnt exist

* Add resource prefix header

* fix unit tests

* Fix docs

* Remove  flag

* Update unit test extends

* Add `path()` method to resource objects and clarify documentation

* Revert sorting documents

* Refactor query results

* Move arrayMergeRecursive to ArrayTrait

* Refactor out update() and rename updatePaths() to update()

* Make FieldValue concrete and non-instantiable (is that a word?)

* Loosen time comparison

* Update cursor documentation

* Address final code review, handle document name query order

Author: jdpedrie

Database.php

@@ -712,8 +712,7 @@ public function runTransaction(callable $operation, array $options = [])
                 throw $e;
             }
 
-            $delay = $e->getRetryDelay();
-            time_nanosleep($delay['seconds'], $delay['nanos']);
+            return $e->getRetryDelay();
         };
 
         $transactionFn = function ($operation, $session, $options) use ($startTransactionFn) {

Operation.php

@@ -131,7 +131,7 @@ public function commit(Session $session, array $mutations, array $options = [])
             'database' => $session->info()['database']
         ]) + $options);
 
-        return $this->mapper->createTimestampWithNanos($res['commitTimestamp']);
+        return $this->mapper->createTimestampWithNanos($res['commitTimestamp'], Timestamp::class);
     }
 
     /**
@@ -336,7 +336,7 @@ public function createSnapshot(Session $session, array $res = [])
         ];
 
         if ($res['readTimestamp']) {
-            $res['readTimestamp'] = $this->mapper->createTimestampWithNanos($res['readTimestamp']);
+            $res['readTimestamp'] = $this->mapper->createTimestampWithNanos($res['readTimestamp'], Timestamp::class);
         }
 
         return new Snapshot($this, $session, $res);

Timestamp.php

@@ -17,6 +17,8 @@
 
 namespace Google\Cloud\Spanner;
 
+use Google\Cloud\Core\Timestamp as CoreTimestamp;
+
 /**
  * Represents a value with a data type of
  * [Timestamp](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.TypeCode).
@@ -40,48 +42,8 @@
  * echo (string) $timestamp;
  * ```
  */
-class Timestamp implements ValueInterface
+class Timestamp extends CoreTimestamp implements ValueInterface
 {
-    const FORMAT = 'Y-m-d\TH:i:s.u\Z';
-    const FORMAT_INTERPOLATE = 'Y-m-d\TH:i:s.%\s\Z';
-
-    /**
-     * @var \DateTimeInterface
-     */
-    private $value;
-
-    /**
-     * @var int
-     */
-    private $nanoSeconds;
-
-    /**
-     * @param \DateTimeInterface $value The timestamp value.
-     * @param int $nanoSeconds [optional] The number of nanoseconds in the timestamp.
-     */
-    public function __construct(\DateTimeInterface $value, $nanoSeconds = null)
-    {
-        $this->value = $value;
-        $this->nanoSeconds = $nanoSeconds ?: (int) $this->value->format('u');
-    }
-
-    /**
-     * Get the underlying `\DateTimeInterface` implementation.
-     *
-     * Please note that nanosecond precision is not present in this method.
-     *
-     * Example:
-     * ```
-     * $dateTime = $timestamp->get();
-     * ```
-     *
-     * @return \DateTimeInterface
-     */
-    public function get()
-    {
-        return $this->value;
-    }
-
     /**
      * Get the type.
      *
@@ -96,34 +58,4 @@ public function type()
     {
         return Database::TYPE_TIMESTAMP;
     }
-
-    /**
-     * Format the value as a string.
-     *
-     * This method retains nanosecond precision, if available.
-     *
-     * Example:
-     * ```
-     * $value = $timestamp->formatAsString();
-     * ```
-     *
-     * @return string
-     */
-    public function formatAsString()
-    {
-        $this->value->setTimezone(new \DateTimeZone('UTC'));
-        $ns = str_pad((string) $this->nanoSeconds, 6, '0', STR_PAD_LEFT);
-        return sprintf($this->value->format(self::FORMAT_INTERPOLATE), $ns);
-    }
-
-    /**
-     * Format the value as a string.
-     *
-     * @return string
-     * @access private
-     */
-    public function __toString()
-    {
-        return $this->formatAsString();
-    }
 }

ValueMapper.php

@@ -19,6 +19,7 @@
 
 use Google\Cloud\Core\ArrayTrait;
 use Google\Cloud\Core\Int64;
+use Google\Cloud\Core\ValueMapperTrait;
 use Google\Spanner\V1\TypeCode;
 
 /**
@@ -27,8 +28,7 @@
 class ValueMapper
 {
     use ArrayTrait;
-
-    const NANO_REGEX = '/(?:\.(\d{1,9})Z)|(?:Z)/';
+    use ValueMapperTrait;
 
     const TYPE_BOOL = TypeCode::BOOL;
     const TYPE_INT64 = TypeCode::INT64;
@@ -185,23 +185,6 @@ public function decodeValues(array $columns, array $row, $format)
         }
     }
 
-    /**
-     * Convert a timestamp string to a Timestamp class with nanosecond support.
-     *
-     * @param string $timestamp The timestamp string
-     * @return Timestamp
-     */
-    public function createTimestampWithNanos($timestamp)
-    {
-        $matches = [];
-        preg_match(self::NANO_REGEX, $timestamp, $matches);
-        $timestamp = preg_replace(self::NANO_REGEX, '.000000Z', $timestamp);
-
-        $dt = \DateTimeImmutable::createFromFormat(Timestamp::FORMAT, str_replace('..', '.', $timestamp));
-
-        return new Timestamp($dt, (isset($matches[1])) ? $matches[1] : 0);
-    }
-
     /**
      * Convert a single value to its corresponding PHP type.
      *
@@ -223,7 +206,7 @@ private function decodeValue($value, array $type)
                 break;
 
             case self::TYPE_TIMESTAMP:
-                $value = $this->createTimestampWithNanos($value);
+                $value = $this->createTimestampWithNanos($value, Timestamp::class);
                 break;
 
             case self::TYPE_DATE: