feat(Spanner): Add support for PG JSONB (#5482)

* Add support for JSONB datatype for PG dialect

* Added unit tests for JSONB

* Added system tests for PG_JSONB

* Change the JsonB class to PgJsonB, fix some tests

* Added snippet tests for JSONB

* Lint fixes

* Fixed unit tests for PHP 5.6

* Addressed PR comments

* Addressed PR comments

Co-authored-by: Brent Shaffer <[email protected]>

Spanner/src/Database.php

@@ -116,6 +116,7 @@ class Database
     const TYPE_STRUCT = TypeCode::STRUCT;
     const TYPE_NUMERIC = TypeCode::NUMERIC;
     const TYPE_PG_NUMERIC = 'pgNumeric';
+    const TYPE_PG_JSONB = 'pgJsonb';
     const TYPE_JSON = TypeCode::JSON;
 
     /**

Spanner/src/PgJsonb.php

@@ -0,0 +1,114 @@
+<?php
+/**
+ * Copyright 2022 Google LLC
+ *
+ * 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\Spanner;
+
+use Google\Cloud\Core\JsonTrait;
+use Google\Cloud\Spanner\V1\TypeAnnotationCode;
+use JsonSerializable;
+
+/**
+ * Represents a value with a data type of
+ * [PG JSONB](https://cloud.google.com/spanner/docs/reference/postgresql/data-types) for the
+ * Postgres Dialect database.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\Spanner\SpannerClient;
+ *
+ * $spanner = new SpannerClient();
+ * $pgJsonb = $spanner->pgJsonb('{}');
+ * ```
+ */
+class PgJsonb implements ValueInterface, TypeAnnotationInterface
+{
+    use JsonTrait;
+
+    /**
+     * @var string|null
+     */
+    private $value;
+
+    /**
+     * @param string|array|JsonSerializable|null $value The value to be used as the JSONB string.
+     */
+    public function __construct($value)
+    {
+        // null shouldn't be casted to an empty string
+        if (!is_null($value)) {
+            if (is_array($value) || $value instanceof JsonSerializable) {
+                $value = self::jsonEncode($value);
+            } else {
+                $value = (string) $value;
+            }
+        }
+        $this->value = $value;
+    }
+
+    /**
+     * Get the underlying value.
+     *
+     * @return string|null
+     */
+    public function get()
+    {
+        return $this->value;
+    }
+
+    /**
+     * Get the type.
+     *
+     * @access private
+     * @return int
+     */
+    public function type()
+    {
+        return ValueMapper::TYPE_JSON;
+    }
+
+    /**
+     * Get the type annotation code.
+     * This is to be used along type, to differentiate the value from TypeCode::JSON.
+     *
+     * @access private
+     * @return int
+     */
+    public function typeAnnotation()
+    {
+        return TypeAnnotationCode::PG_JSONB;
+    }
+
+    /**
+     * Format the value as a string.
+     *
+     * @return string
+     */
+    public function formatAsString()
+    {
+        return (string) $this->value;
+    }
+
+    /**
+     * Format the value as a string.
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return (string) $this->value;
+    }
+}

Spanner/src/SpannerClient.php

@@ -630,6 +630,21 @@ public function pgNumeric($value)
         return new PgNumeric($value);
     }
 
+    /**
+     * Represents a value with a data type of
+     * [PG JSONB](https://cloud.google.com/spanner/docs/reference/postgresql/data-types) for the
+     * Postgres Dialect database.
+     *
+     * Example:
+     * ```
+     * $pgJsonb = $spanner->pgJsonb('{}');
+     * ```
+     */
+    public function pgJsonb($value)
+    {
+        return new PgJsonb($value);
+    }
+
     /**
      * Create an Int64 object. This can be used to work with 64 bit integers as
      * a string value while on a 32 bit platform.

Spanner/src/ValueMapper.php

@@ -43,6 +43,7 @@ class ValueMapper
     const TYPE_NUMERIC = TypeCode::NUMERIC;
     const TYPE_JSON = TypeCode::JSON;
     const TYPE_PG_NUMERIC = 'pgNumeric';
+    const TYPE_PG_JSONB = 'pgJsonb';
 
     /**
      * @var array
@@ -60,6 +61,7 @@ class ValueMapper
         self::TYPE_NUMERIC,
         self::TYPE_JSON,
         self::TYPE_PG_NUMERIC,
+        self::TYPE_PG_JSONB,
     ];
 
     /*
@@ -73,6 +75,7 @@ class ValueMapper
      */
     private static $typeToClassMap = [
         self::TYPE_PG_NUMERIC => PgNumeric::class,
+        self::TYPE_PG_JSONB => PgJsonb::class,
     ];
 
     /*
@@ -83,6 +86,7 @@ class ValueMapper
      */
     private static $typeCodes = [
         self::TYPE_PG_NUMERIC => self::TYPE_NUMERIC,
+        self::TYPE_PG_JSONB => self::TYPE_JSON,
     ];
 
     /*
@@ -93,6 +97,7 @@ class ValueMapper
      */
     private static $typeAnnotations = [
         self::TYPE_PG_NUMERIC => TypeAnnotationCode::PG_NUMERIC,
+        self::TYPE_PG_JSONB => TypeAnnotationCode::PG_JSONB,
     ];
 
     /**
@@ -317,6 +322,12 @@ private function decodeValue($value, array $type)
                 }
                 break;
 
+            case self::TYPE_JSON:
+                if (isset($type['typeAnnotation']) && $type['typeAnnotation'] === TypeAnnotationCode::PG_JSONB) {
+                    $value = new PgJsonb($value);
+                }
+                break;
+
             case self::TYPE_FLOAT64:
                 // NaN, Infinite and -Infinite are possible FLOAT64 values,
                 // but when the gRPC response is decoded, they are represented

Spanner/tests/Snippet/PgJsonbTest.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Copyright 2022 Google LLC
+ *
+ * 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\Spanner\Tests\Snippet;
+
+use Google\Cloud\Core\Testing\Snippet\SnippetTestCase;
+use Google\Cloud\Spanner\PgJsonb;
+
+/**
+ * @group spanner
+ */
+class PgJsonbTest extends SnippetTestCase
+{
+    public function testClass()
+    {
+        $expected = new PgJsonb('{}');
+        $snippet = $this->snippetFromClass(PgJsonb::class);
+        $res = $snippet->invoke('pgJsonb');
+
+        $this->assertInstanceOf(PgJsonb::class, $res->returnVal());
+        $this->assertEquals($expected, $res->returnVal());
+    }
+}

Spanner/tests/Snippet/SpannerClientTest.php

@@ -39,6 +39,7 @@
 use Google\Cloud\Spanner\Timestamp;
 use Google\Cloud\Spanner\Numeric;
 use Google\Cloud\Spanner\PgNumeric;
+use Google\Cloud\Spanner\PgJsonb;
 use Prophecy\Argument;
 
 /**
@@ -259,6 +260,7 @@ public function factoriesProvider()
             [CommitTimestamp::class, 'commitTimestamp'],
             [Numeric::class, 'numeric'],
             [PgNumeric::class, 'pgNumeric'],
+            [PgJsonB::class, 'pgJsonb'],
         ];
     }