feat: support client options in ClientOptionsTrait::buildClientOptions (#621)

Author: bshaffer

src/ClientOptionsTrait.php

@@ -32,6 +32,7 @@
 
 namespace Google\ApiCore;
 
+use Google\ApiCore\Options\ClientOptions;
 use Google\Auth\ApplicationDefaultCredentials;
 use Google\Auth\CredentialsLoader;
 use Google\Auth\FetchAuthTokenInterface;
@@ -84,8 +85,26 @@ private static function getClientDefaults()
         return [];
     }
 
-    private function buildClientOptions(array $options)
+    /**
+     * Resolve client options based on the client's default
+     * ({@see ClientOptionsTrait::getClientDefault}) and the default for all
+     * Google APIs.
+     *
+     * 1. Set default client option values
+     * 2. Set default logger (and log user-supplied configuration options)
+     * 3. Set default transport configuration
+     * 4. Call "modifyClientOptions" (for backwards compatibility)
+     * 5. Use "defaultScopes" when custom endpoint is supplied
+     * 6. Load mTLS from the environment if configured
+     * 7. Resolve endpoint based on universe domain template when possible
+     * 8. Load sysvshm grpc config when possible
+     */
+    private function buildClientOptions(array|ClientOptions $options)
     {
+        if ($options instanceof ClientOptions) {
+            $options = $options->toArray();
+        }
+
         // Build $defaultOptions starting from top level
         // variables, then going into deeper nesting, so that
         // we will not encounter missing keys

src/Options/CallOptions.php

@@ -44,7 +44,7 @@
  * {@see \Google\ApiCore\Transport\TransportInterface::startClientStreamingCall()}, and
  * {@see \Google\ApiCore\Transport\TransportInterface::startServerStreamingCall()}.
  */
-class CallOptions implements ArrayAccess
+class CallOptions implements ArrayAccess, OptionsInterface
 {
     use OptionsTrait;
 

src/Options/ClientOptions.php

@@ -59,7 +59,7 @@
  * Note: It's possible to pass an associative array to the API clients as well,
  * as ClientOptions will still be used internally for validation.
  */
-class ClientOptions implements ArrayAccess
+class ClientOptions implements ArrayAccess, OptionsInterface
 {
     use OptionsTrait;
 

src/Options/OptionsInterface.php

@@ -0,0 +1,38 @@
+<?php
+/*
+ * Copyright 2025 Google LLC
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+namespace Google\ApiCore\Options;
+
+interface OptionsInterface
+{
+    public function toArray(): array;
+}

src/Options/OptionsTrait.php

@@ -83,7 +83,9 @@ public function toArray(): array
     {
         $arr = [];
         foreach (get_object_vars($this) as $key => $value) {
-            $arr[$key] = $value;
+            $arr[$key] = $value instanceof OptionsInterface
+                 ? $value->toArray()
+                 : $value;
         }
         return $arr;
     }

src/Options/TransportOptions.php

@@ -37,7 +37,7 @@
 use Google\ApiCore\Options\TransportOptions\GrpcTransportOptions;
 use Google\ApiCore\Options\TransportOptions\RestTransportOptions;
 
-class TransportOptions implements ArrayAccess
+class TransportOptions implements ArrayAccess, OptionsInterface
 {
     use OptionsTrait;
 

src/Options/TransportOptions/GrpcFallbackTransportOptions.php

@@ -34,14 +34,15 @@
 
 use ArrayAccess;
 use Closure;
+use Google\ApiCore\Options\OptionsInterface;
 use Google\ApiCore\Options\OptionsTrait;
 use Psr\Log\LoggerInterface;
 
 /**
  * The GrpcFallbackTransportOptions class provides typing to the associative array of options used
  * to configure {@see \Google\ApiCore\Transport\GrpcFallbackTransport}.
  */
-class GrpcFallbackTransportOptions implements ArrayAccess
+class GrpcFallbackTransportOptions implements ArrayAccess, OptionsInterface
 {
     use OptionsTrait;
 

src/Options/TransportOptions/GrpcTransportOptions.php

@@ -34,6 +34,7 @@
 
 use ArrayAccess;
 use Closure;
+use Google\ApiCore\Options\OptionsInterface;
 use Google\ApiCore\Options\OptionsTrait;
 use Google\ApiCore\Transport\Grpc\UnaryInterceptorInterface;
 use Grpc\Channel;
@@ -44,7 +45,7 @@
  * The GrpcTransportOptions class provides typing to the associative array of options used to
  * configure {@see \Google\ApiCore\Transport\GrpcTransport}.
  */
-class GrpcTransportOptions implements ArrayAccess
+class GrpcTransportOptions implements ArrayAccess, OptionsInterface
 {
     use OptionsTrait;
 

src/Options/TransportOptions/RestTransportOptions.php

@@ -34,14 +34,15 @@
 
 use ArrayAccess;
 use Closure;
+use Google\ApiCore\Options\OptionsInterface;
 use Google\ApiCore\Options\OptionsTrait;
 use Psr\Log\LoggerInterface;
 
 /**
  * The RestTransportOptions class provides typing to the associative array of options used to
  * configure {@see \Google\ApiCore\Transport\RestTransport}.
  */
-class RestTransportOptions implements ArrayAccess
+class RestTransportOptions implements ArrayAccess, OptionsInterface
 {
     use OptionsTrait;
 

tests/Unit/ClientOptionsTraitTest.php

@@ -34,6 +34,7 @@
 
 use Google\ApiCore\ClientOptionsTrait;
 use Google\ApiCore\CredentialsWrapper;
+use Google\ApiCore\Options\ClientOptions;
 use Google\ApiCore\ValidationException;
 use Google\Auth\CredentialsLoader;
 use Google\Auth\FetchAuthTokenInterface;
@@ -558,6 +559,16 @@ public function testBuildClientOptionsTwice()
         $this->assertEquals($options, $options2);
     }
 
+    public function testBuildClientOptionsWithClientOptions()
+    {
+        $client = new StubClientOptionsClient();
+        $clientOptions = new ClientOptions([]);
+        $clientOptions->setApiEndpoint('TestEndpoint.com');
+        $builtOptions = $client->buildClientOptions($clientOptions);
+
+        $this->assertEquals($clientOptions['apiEndpoint'], $builtOptions['apiEndpoint']);
+    }
+
     /**
      * @runInSeparateProcess
      */