Update documentation for Datastore options

Author: Hectorhammett

Datastore/src/DatastoreClient.php

@@ -18,7 +18,9 @@
 namespace Google\Cloud\Datastore;
 
 use DomainException;
+use Google\ApiCore\Options\ClientOptions;
 use Google\Auth\FetchAuthTokenInterface;
+use Google\Cloud\Core\ApiHelperTrait;
 use Google\Cloud\Core\ArrayTrait;
 use Google\Cloud\Core\ClientTrait;
 use Google\Cloud\Core\Int64;
@@ -87,10 +89,10 @@
  */
 class DatastoreClient
 {
-    use ArrayTrait;
     use ClientTrait;
     use DatastoreTrait;
     use TimestampTrait;
+    use ApiHelperTrait;
 
     const VERSION = '1.34.0';
 
@@ -116,20 +118,76 @@ class DatastoreClient
      *
      * @param array $config [optional] {
      *     Configuration Options.
+     *     Some of this options details on {@see ClientOptions}.
      *
-     *     @type string $apiEndpoint A hostname with optional port to use in
-     *           place of the service's default endpoint.
      *     @type string $projectId The project ID from the Google Developer's
      *           Console.
-     *     @type CacheItemPoolInterface $authCache A cache for storing access
-     *           tokens. **Defaults to** a simple in memory implementation.
-     *     @type array $authCacheOptions Cache configuration options.
-     *     @type callable $authHttpHandler A handler used to deliver Psr7
-     *           requests specifically for authentication.
-     *     @type FetchAuthTokenInterface $credentialsFetcher A credentials
-     *           fetcher instance.
-     *     @type callable $httpHandler A handler used to deliver Psr7 requests.
-     *           Only valid for requests sent over REST.
+     *     @type string $namespaceId Partitions data under a namespace. Useful for
+     *           [Multitenant Projects](https://cloud.google.com/datastore/docs/concepts/multitenancy).
+     *     @type string $databaseId ID of the database to which the entities belong.
+     *     @type bool $returnInt64AsObject If true, 64 bit integers will be
+     *           returned as a {@see \Google\Cloud\Core\Int64} object for 32 bit
+     *           platform compatibility. **Defaults to** false.
+     *     @type GapicDatastoreClient $datastoreClient A client that is of
+     *           type {@see GapicDatastoreClient}
+     *     @type string $apiEndpoint
+     *           The address of the API remote host. May optionally include the port, formatted
+     *           as "<uri>:<port>". Default 'datastore.googleapis.com:443'.
+     *     @type FetchAuthTokenInterface|CredentialsWrapper $credentials
+     *           This option should only be used with a pre-constructed
+     *           {@see FetchAuthTokenInterface} or {@see CredentialsWrapper} object. Note that
+     *           when one of these objects are provided, any settings in $credentialsConfig will
+     *           be ignored.
+     *           **Important**: If you are providing a path to a credentials file, or a decoded
+     *           credentials file as a PHP array, this usage is now DEPRECATED. Providing an
+     *           unvalidated credential configuration to Google APIs can compromise the security
+     *           of your systems and data. It is recommended to create the credentials explicitly
+     *           ```
+     *           use Google\Auth\Credentials\ServiceAccountCredentials;
+     *           use Google\Cloud\Datastore\V1\DatastoreClient;
+     *           $creds = new ServiceAccountCredentials($scopes, $json);
+     *           $options = new DatastoreClient(['credentials' => $creds]);
+     *           ```
+     *           {@see
+     *           https://cloud.google.com/docs/authentication/external/externally-sourced-credentials}
+     *     @type array $credentialsConfig
+     *           Options used to configure credentials, including auth token caching, for the
+     *           client. For a full list of supporting configuration options, see
+     *           {@see \Google\ApiCore\CredentialsWrapper::build()} .
+     *     @type bool $disableRetries
+     *           Determines whether or not retries defined by the client configuration should be
+     *           disabled. Defaults to `false`.
+     *     @type string|array $clientConfig
+     *           Client method configuration, including retry settings. This option can be either
+     *           a path to a JSON file, or a PHP array containing the decoded JSON data. By
+     *           default this settings points to the default client config file, which is
+     *           provided in the resources folder.
+     *     @type string|TransportInterface $transport
+     *           The transport used for executing network requests. May be either the string
+     *           `rest` or `grpc`. Defaults to `grpc` if gRPC support is detected on the system.
+     *           *Advanced usage*: Additionally, it is possible to pass in an already
+     *           instantiated {@see \Google\ApiCore\Transport\TransportInterface} object. Note
+     *           that when this object is provided, any settings in $transportConfig, and any
+     *           $apiEndpoint setting, will be ignored.
+     *     @type array $transportConfig
+     *           Configuration options that will be used to construct the transport. Options for
+     *           each supported transport type should be passed in a key for that transport. For
+     *           example:
+     *           $transportConfig = [
+     *               'grpc' => [...],
+     *               'rest' => [...],
+     *           ];
+     *           See the {@see \Google\ApiCore\Transport\GrpcTransport::build()} and
+     *           {@see \Google\ApiCore\Transport\RestTransport::build()} methods for the
+     *           supported options.
+     *     @type callable $clientCertSource
+     *           A callable which returns the client cert as a string. This can be used to
+     *           provide a certificate and private key to the transport layer for mTLS.
+     *     @type false|LoggerInterface $logger
+     *           A PSR-3 compliant logger. If set to false, logging is disabled, ignoring the
+     *           'GOOGLE_SDK_PHP_LOGGING' environment flag
+     *     @type string $universeDomain
+     *           The service domain for the client. Defaults to 'googleapis.com'.
      *     @type array $keyFile [DEPRECATED]
      *           @deprecated This option is being deprecated because of a potential security risk.
      *           This option does not validate the credential configuration. The security
@@ -174,28 +232,13 @@ class DatastoreClient
      *           Regardless of the method used, it is always your responsibility to validate
      *           configurations received from external sources.
      *           @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
-     *     @type float $requestTimeout Seconds to wait before timing out the
-     *           request. **Defaults to** `0` with REST and `60` with gRPC.
-     *     @type int $retries Number of retries for a failed request. **Defaults
-     *           to** `3`.
-     *     @type array $scopes Scopes to be used for the request.
-     *     @type string $quotaProject Specifies a user project to bill for
-     *           access charges associated with the request.
-     *     @type string $namespaceId Partitions data under a namespace. Useful for
-     *           [Multitenant Projects](https://cloud.google.com/datastore/docs/concepts/multitenancy).
-     *     @type string $databaseId ID of the database to which the entities belong.
-     *     @type bool $returnInt64AsObject If true, 64 bit integers will be
-     *           returned as a {@see \Google\Cloud\Core\Int64} object for 32 bit
-     *           platform compatibility. **Defaults to** false.
-     *     @type GapicDatastoreClient $datastoreClient A client that is of
-     *           type {@see GapicDatastoreClient}
      * }
      * @throws \InvalidArgumentException
      */
     public function __construct(array $config = [])
     {
         $emulatorHost = getenv('DATASTORE_EMULATOR_HOST');
-
+        $this->validateConfigurationOptions($config);
         $connectionType = $this->getConnectionType($config);
 
         $config += [
@@ -1305,4 +1348,29 @@ private function getGapicClient(array $config): GapicDatastoreClient
 
         return $config['datastoreClient'] ?? new GapicDatastoreClient($config);
     }
+
+    private function validateConfigurationOptions(array $config): void
+    {
+        $availableOptions = [
+            'projectId',
+            'namespaceId',
+            'databaseId',
+            'returnInt64AsObject',
+            'datastoreClient',
+            'apiEndpoint',
+            'credentials',
+            'credentialsConfig',
+            'disableRetries',
+            'clientConfig',
+            'transport',
+            'transportConfig',
+            'clientCertSource',
+            'logger',
+            'universeDomain',
+            'keyFile',
+            'keyFilePath',
+        ];
+
+        $this->validateOptions($config, $availableOptions);
+    }
 }