feat: Validate options no serializer (#8625)

* add validateOptions helper method

* add test

* style fix

* remove Message classname from supported validateOptions types

* add support without a serializer

* Remove the serializer usage inside the validateOptions method

* Added the JSON_FORCE_OBJECT flag to json_encode

---------

Co-authored-by: Brent Shaffer <betterbrent@google.com>

Author: Hectorhammett

Core/src/ApiHelperTrait.php

@@ -17,9 +17,12 @@
  */
 namespace Google\Cloud\Core;
 
+use Exception;
 use Google\ApiCore\ArrayTrait;
 use Google\ApiCore\Options\CallOptions;
+use Google\Protobuf\Internal\Message;
 use Google\Protobuf\NullValue;
+use LogicException;
 
 /**
  * @internal
@@ -260,8 +263,53 @@ private function splitOptionalArgs(array $input, array $extraAllowedKeys = []):
         $callOptionFields = array_keys((new CallOptions([]))->toArray());
         $keys = array_merge($callOptionFields, $extraAllowedKeys);
 
-        $optionalArgs = $this->pluckArray($keys, $input);
+        $callOptions = $this->pluckArray($keys, $input);
 
-        return [$input, $optionalArgs];
+        return [$input, $callOptions];
+    }
+
+    /**
+     * Helper method used to validate optons based on the supplied $optionTypes
+     * $optionTypes can be an array of string keys, a protobuf Message classname, or a
+     * the CallOptions classname. Parameters are split and returned in the order
+     * that the options types are provided.
+     */
+    private function validateOptions(array $options, array|Message|string ...$optionTypes): array
+    {
+        $splitOptions = [];
+        foreach ($optionTypes as $optionType) {
+            if (is_array($optionType)) {
+                $splitOptions[] = $this->pluckArray($optionType, $options);
+            } elseif ($optionType === CallOptions::class) {
+                $callOptionKeys = array_keys((new CallOptions([]))->toArray());
+                $splitOptions[] = $this->pluckArray($callOptionKeys, $options);
+            } elseif ($optionType instanceof Message) {
+                $messageKeys = array_map(
+                    fn ($method) => lcfirst(substr($method, 3)),
+                    array_filter(
+                        get_class_methods($optionType),
+                        fn ($m) => 0 === strpos($m, 'get')
+                    )
+                );
+                $messageOptions = $this->pluckArray($messageKeys, $options);
+                if ($optionType instanceof Message) {
+                    $optionType->mergeFromJsonString(json_encode($messageOptions, JSON_FORCE_OBJECT));
+                    $validatedOptionGroup = $optionType;
+                } else {
+                    $validatedOptionGroup = $messageOptions;
+                }
+                $splitOptions[] = $validatedOptionGroup;
+            } else {
+                throw new LogicException(sprintf('Invalid option type: %s', $optionType));
+            }
+        }
+
+        if (!empty($options)) {
+            throw new Exception(
+                'Unexpected option(s) provided: ' . implode(', ', array_keys($options))
+            );
+        }
+
+        return $splitOptions;
     }
 }

Core/tests/Unit/ApiHelperTraitTest.php

@@ -17,9 +17,13 @@
 
 namespace Google\Cloud\Core\Tests\Unit;
 
+use Google\ApiCore\Options\CallOptions;
+use Google\ApiCore\Serializer;
+use Google\ApiCore\Testing\MockRequest;
 use Google\Cloud\Core\Duration;
 use Google\Cloud\Core\Testing\GrpcTestTrait;
 use Google\Cloud\Core\Tests\Unit\Stubs\ApiHelpersTraitImpl;
+use LogicException;
 use PHPUnit\Framework\TestCase;
 use Prophecy\PhpUnit\ProphecyTrait;
 
@@ -36,6 +40,7 @@ class ApiHelperTraitTest extends TestCase
     public function setUp(): void
     {
         $this->implementation = new ApiHelpersTraitImpl();
+        $this->implementation->serializer = new Serializer();
     }
 
     public function testFormatsTimestamp()
@@ -258,4 +263,122 @@ public function unpackValueProvider()
             ]
         ];
     }
+
+    /**
+     * @dataProvider validateOptionsProvider
+     */
+    public function testValidateOptions($options, $optionTypes, $expected)
+    {
+        $this->assertEquals(
+            $expected,
+            $this->implementation->validateOptions($options, ...$optionTypes)
+        );
+        // test using an implementation without a serializer
+        $this->assertEquals(
+            $expected,
+            (new ApiHelpersTraitImpl)->validateOptions($options, ...$optionTypes)
+        );
+    }
+
+    public function validateOptionsProvider()
+    {
+        return [
+            [
+                [
+                    'foo' => 'bar',
+                    'baz' => 'bat',
+                    'qux' => 'quux',
+                ],
+                [
+                    ['foo', 'baz', 'qux'],
+                ],
+                [
+                    [
+                        'foo' => 'bar',
+                        'baz' => 'bat',
+                        'qux' => 'quux',
+                    ],
+                ]
+            ],
+            [
+                [
+                    'pageToken' => 'bat',
+                    'qux' => 'quux',
+                    'timeoutMillis' => 123,
+                ],
+                [
+                    CallOptions::class,
+                    new MockRequest(),
+                    ['qux'],
+                ],
+                [
+                    ['timeoutMillis' => 123],
+                    (new MockRequest())->setPageToken('bat'),
+                    ['qux' => 'quux'],
+                ]
+            ],
+            [
+                [
+                    'baz' => 'bat',
+                ],
+                [
+                    ['baz'],
+                    new MockRequest(),
+                    CallOptions::class,
+                ],
+                [
+                    ['baz' => 'bat'],
+                    new MockRequest(),
+                    [],
+                ]
+            ],
+            [
+                [
+                    'baz' => 'bat',
+                    'pageToken' => 'foo1',
+                ],
+                [
+                    ['baz'],
+                    new MockRequest(),
+                ],
+                [
+                    ['baz' => 'bat'],
+                    (new MockRequest())->setPageToken('foo1'),
+                ]
+            ],
+        ];
+    }
+
+    public function testValidateOptionsThrowsException()
+    {
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('Unexpected option(s) provided: bar');
+
+        $options = [
+            'foo' => 'bar',
+            'bar' => 'baz',
+        ];
+
+        $this->implementation->validateOptions($options, ['foo']);
+    }
+
+    public function testValidateOptionsWithClassnameThrowsException()
+    {
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('Invalid option type: ' . Blob::class);
+
+        $options = [
+            'foo' => 'bar',
+            'bar' => 'baz',
+        ];
+
+        [$blob, $validated] = $this->implementation->validateOptions(
+            $options,
+            Blob::class,
+            ['foo', 'bar']
+        );
+
+        $this->assertEquals([], $blob);
+        $this->assertEquals($options, $validated);
+    }
 }

Core/tests/Unit/Stubs/ApiHelpersTraitImpl.php

@@ -31,5 +31,8 @@ class ApiHelpersTraitImpl
         formatDurationForApi as public;
         formatValueForApi as public;
         unpackValue as public;
+        validateOptions as public;
     }
+
+    public $serializer;
 }