PHPFUI/InstaDoc

Service Description: Manages long-running operations with an API service.

When an API method normally takes long time to complete, it can be designed to return [Operation][google.longrunning.Operation] to the client, and the client can use this interface to receive the real response asynchronously by polling the operation resource, or pass the operation resource to another API (such as Pub/Sub API) to receive the response. Any API service that returns long-running operations should implement the Operations interface so developers can have a consistent client experience.

This class provides the ability to make remote calls to the backing service through method calls that map to API methods. Sample code to get started:

$operationsClient = new OperationsClient();
try {
    $name = 'name';
    $operationsClient->cancelOperation($name);
} finally {
    $operationsClient->close();
}

deprecated Please use the new service client {@see \Google\LongRunning\Client\OperationsClient}.

CloneableInstantiable

Constants

public Google\LongRunning\Gapic\OperationsGapicClient::CODEGEN_NAME = 'gapic'

The name of the code generator, to be included in the agent header.

public Google\LongRunning\Gapic\OperationsGapicClient::DEFAULT_SERVICE_PORT = 443

The default port of the service.

public Google\LongRunning\Gapic\OperationsGapicClient::SERVICE_ADDRESS = 'longrunning.googleapis.com'

The default address of the service.

deprecated SERVICE_ADDRESS_TEMPLATE should be used instead.

public Google\LongRunning\Gapic\OperationsGapicClient::SERVICE_NAME = 'google.longrunning.Operations'

The name of the service.

Properties

public static $serviceScopes = []

The default scopes required by the service.

Methods

public __construct(array $options = [])

Constructor.

param array $options { Optional. Options for configuring the service API wrapper.

@type string $apiEndpoint
      The address of the API remote host. May optionally include the port, formatted
      as "<uri>:<port>". Default 'longrunning.googleapis.com:443'.
@type string|array|FetchAuthTokenInterface|CredentialsWrapper $credentials
      The credentials to be used by the client to authorize API calls. This option
      accepts either a path to a credentials file, or a decoded credentials file as a
      PHP array.
      *Advanced usage*: In addition, this option can also accept a pre-constructed
      {@see \Google\Auth\FetchAuthTokenInterface} object or
      {@see \Google\ApiCore\CredentialsWrapper} object. Note that when one of these
      objects are provided, any settings in $credentialsConfig will be ignored.
@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.

}

throws \ValidationException

public addMiddleware(callable $middlewareCallable) : void

Add a middleware to the call stack by providing a callable which will be invoked at the start of each call, and will return an instance of {@see MiddlewareInterface} when invoked.

The callable must have the following method signature:

callable(MiddlewareInterface): MiddlewareInterface

An implementation may look something like this:

$client->addMiddleware(function (MiddlewareInterface $handler) {
    return new class ($handler) implements MiddlewareInterface {
        public function __construct(private MiddlewareInterface $handler) {
        }

        public function __invoke(Call $call, array $options) {
            // modify call and options (pre-request)
            $response = ($this->handler)($call, $options);
            // modify the response (post-request)
            return $response;
        }
    };
});

param callable $middlewareCallable A callable which returns an instance of {@see \MiddlewareInterface} when invoked with a MiddlewareInterface instance as its first argument.
return void

public cancelOperation( $name, array $optionalArgs = [])

Starts asynchronous cancellation on a long-running operation. The server makes a best effort to cancel the operation, but success is not guaranteed. If the server doesn't support this method, it returns google.rpc.Code.UNIMPLEMENTED. Clients can use [Operations.GetOperation][google.longrunning.Operations.GetOperation] or other methods to check whether the cancellation succeeded or whether the operation completed despite cancellation. On successful cancellation, the operation is not deleted; instead, it becomes an operation with an [Operation.error][google.longrunning.Operation.error] value with a [google.rpc.Status.code][google.rpc.Status.code] of 1, corresponding to Code.CANCELLED.

Sample code:

$operationsClient = new OperationsClient();
try {
    $name = 'name';
    $operationsClient->cancelOperation($name);
} finally {
    $operationsClient->close();
}

param string $name The name of the operation resource to be cancelled.

param array $optionalArgs { Optional.

@type RetrySettings|array $retrySettings
      Retry settings to use for this call. Can be a {@see \RetrySettings} object, or an
      associative array of retry settings parameters. See the documentation on
      {@see \RetrySettings} for example usage.

}

throws \ApiException if the remote call fails

public close()

Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.

experimental

public deleteOperation( $name, array $optionalArgs = [])

Deletes a long-running operation. This method indicates that the client is no longer interested in the operation result. It does not cancel the operation. If the server doesn't support this method, it returns google.rpc.Code.UNIMPLEMENTED.

Sample code:

$operationsClient = new OperationsClient();
try {
    $name = 'name';
    $operationsClient->deleteOperation($name);
} finally {
    $operationsClient->close();
}

param string $name The name of the operation resource to be deleted.

param array $optionalArgs { Optional.

@type RetrySettings|array $retrySettings
      Retry settings to use for this call. Can be a {@see \RetrySettings} object, or an
      associative array of retry settings parameters. See the documentation on
      {@see \RetrySettings} for example usage.

}

throws \ApiException if the remote call fails

public getOperation( $name, array $optionalArgs = [])

Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at intervals as recommended by the API service.

Sample code:

$operationsClient = new OperationsClient();
try {
    $name = 'name';
    $response = $operationsClient->getOperation($name);
} finally {
    $operationsClient->close();
}

param string $name The name of the operation resource.

param array $optionalArgs { Optional.

@type RetrySettings|array $retrySettings
      Retry settings to use for this call. Can be a {@see \RetrySettings} object, or an
      associative array of retry settings parameters. See the documentation on
      {@see \RetrySettings} for example usage.

}

return \Google\LongRunning\Operation
throws \ApiException if the remote call fails

public listOperations( $name, $filter, array $optionalArgs = [])

Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns UNIMPLEMENTED.

Sample code:

$operationsClient = new OperationsClient();
try {
    $name = 'name';
    $filter = 'filter';
    // Iterate over pages of elements
    $pagedResponse = $operationsClient->listOperations($name, $filter);
    foreach ($pagedResponse->iteratePages() as $page) {
        foreach ($page as $element) {
            // doSomethingWith($element);
        }
    }
    // Alternatively:
    // Iterate through all elements
    $pagedResponse = $operationsClient->listOperations($name, $filter);
    foreach ($pagedResponse->iterateAllElements() as $element) {
        // doSomethingWith($element);
    }
} finally {
    $operationsClient->close();
}

param string $name The name of the operation's parent resource.
param string $filter The standard list filter.

param array $optionalArgs { Optional.

@type int $pageSize
      The maximum number of resources contained in the underlying API
      response. The API may return fewer values in a page, even if
      there are additional values to be retrieved.
@type string $pageToken
      A page token is used to specify a page of values to be returned.
      If no page token is specified (the default), the first page
      of values will be returned. Any page token used here must have
      been generated by a previous call to the API.
@type bool $returnPartialSuccess
      When set to `true`, operations that are reachable are returned as normal,
      and those that are unreachable are returned in the
      [ListOperationsResponse.unreachable] field.

      This can only be `true` when reading across collections e.g. when `parent`
      is set to `"projects/example/locations/-"`.

      This field is not by default supported and will result in an
      `UNIMPLEMENTED` error if set unless explicitly documented otherwise in
      service or product specific documentation.
@type RetrySettings|array $retrySettings
      Retry settings to use for this call. Can be a {@see \RetrySettings} object, or an
      associative array of retry settings parameters. See the documentation on
      {@see \RetrySettings} for example usage.

}

return \Google\ApiCore\PagedListResponse
throws \ApiException if the remote call fails

public prependMiddleware(callable $middlewareCallable) : void

Prepend a middleware to the call stack by providing a callable which will be invoked at the end of each call, and will return an instance of {@see MiddlewareInterface} when invoked.

The callable must have the following method signature:

callable(MiddlewareInterface): MiddlewareInterface

An implementation may look something like this:

$client->prependMiddleware(function (MiddlewareInterface $handler) {
    return new class ($handler) implements MiddlewareInterface {
        public function __construct(private MiddlewareInterface $handler) {
        }

        public function __invoke(Call $call, array $options) {
            // modify call and options (pre-request)
            $response = ($this->handler)($call, $options);
            // modify the response (post-request)
            return $response;
        }
    };
});

param callable $middlewareCallable A callable which returns an instance of {@see \MiddlewareInterface} when invoked with a MiddlewareInterface instance as its first argument.
return void

public static traitValidate(array $arr, array $requiredKeys)

param array $arr Associative array
param array $requiredKeys List of keys to check for in $arr
return array Returns $arr for fluent use

public static validate(array $arr, array $requiredKeys)

param array $arr Associative array
param array $requiredKeys List of keys to check for in $arr
return array Returns $arr for fluent use

public static validateNotNull(array $arr, array $requiredKeys)

param array $arr Associative array
param array $requiredKeys List of keys to check for in $arr
return array Returns $arr for fluent use

public waitOperation(array $optionalArgs = [])

Waits until the specified long-running operation is done or reaches at most a specified timeout, returning the latest state. If the operation is already done, the latest state is immediately returned. If the timeout specified is greater than the default HTTP/RPC timeout, the HTTP/RPC timeout is used. If the server does not support this method, it returns google.rpc.Code.UNIMPLEMENTED.

Note that this method is on a best-effort basis. It may return the latest state before the specified timeout (including immediately), meaning even an immediate response is no guarantee that the operation is done.

Sample code:

$operationsClient = new OperationsClient();
try {
    $response = $operationsClient->waitOperation();
} finally {
    $operationsClient->close();
}

param array $optionalArgs { Optional.

@type string $name
      The name of the operation resource to wait on.
@type Duration $timeout
      The maximum duration to wait before timing out. If left blank, the wait
      will be at most the time permitted by the underlying HTTP/RPC protocol.
      If RPC context deadline is also specified, the shorter one will be used.
@type RetrySettings|array $retrySettings
      Retry settings to use for this call. Can be a {@see \RetrySettings} object, or an
      associative array of retry settings parameters. See the documentation on
      {@see \RetrySettings} for example usage.

}

return \Google\LongRunning\Operation
throws \ApiException if the remote call fails

Methods

protected getCredentialsWrapper()

Get the credentials for the client. This method is protected to support use by customized clients.

access private
return \CredentialsWrapper

protected getTransport()

Get the transport for the client. This method is protected to support use by customized clients.

access private
return \TransportInterface

protected modifyClientOptions(array $options)

Modify options passed to the client before calling setClientOptions.

param array $options
access private
internal

protected modifyStreamingCallable(callable $callable)

Modify the streaming callable.

param callable $callable
access private

protected modifyUnaryCallable(callable $callable)

Modify the unary callable.

param callable $callable
access private

Constants

private Google\LongRunning\Gapic\OperationsGapicClient::SERVICE_ADDRESS_TEMPLATE = 'longrunning.UNIVERSE_DOMAIN'

The address template of the service.

Properties

private array $agentHeader = []

private bool $backwardsCompatibilityMode

private ?Google\ApiCore\HeaderCredentialsInterface $credentialsWrapper = NULL

private array $descriptors = []

private static $gapicVersionFromFile = NULL

private array $middlewareCallables = []

var callable[] $middlewareCallables

private array $prependMiddlewareCallables = []

var callable[] $prependMiddlewareCallables

private array $retrySettings = []

var \RetrySettings[] $retrySettings

private string $serviceName = ''

private ?Google\ApiCore\Transport\TransportInterface $transport = NULL

private array $transportCallMethods = ['startUnaryCall', 'startBidiStreamingCall', 'startClientStreamingCall', 'startServerStreamingCall']

Methods

private arrayFilterRemoveNull(array $arr)

Just like array_filter(), but preserves falsey values except null.

param array $arr
return array

private arrayMergeRecursive(array $array1, array $array2)

A method, similar to PHP's array_merge_recursive, with two differences.

Keys in $array2 take precedence over keys in $array1.
Non-array keys found in both inputs are not transformed into an array and appended. Rather, the value in $array2 is used.

param array $array1
param array $array2
return array

private buildClientOptions(Google\ApiCore\Options\ClientOptions|array $options)

Resolve client options based on the client's default ({@see ClientOptionsTrait::getClientDefault}) and the default for all Google APIs.

Set default client option values
Set default logger (and log user-supplied configuration options)
Set default transport configuration
Call "modifyClientOptions" (for backwards compatibility)
Use "defaultScopes" when custom endpoint is supplied
Load mTLS from the environment if configured
Resolve endpoint based on universe domain template when possible
Load sysvshm grpc config when possible

private buildMethod(?string $interfaceName = NULL, ?string $methodName = NULL)

param string $interfaceName
param string $methodName
return string

private buildRequestParamsHeader(array $headerParams, ?Google\Protobuf\Internal\Message $request = NULL)

param array $headerParams
param \Message|null $request
return array

private configureCallConstructionOptions(string $methodName, array $optionalArgs)

param string $methodName

param array $optionalArgs { Optional arguments

@type RetrySettings|array $retrySettings [optional] A retry settings
      override for the call.

}

return array

private configureCallOptions(array $optionalArgs) : array

return array

private createCallStack(array $callConstructionOptions)

param array $callConstructionOptions { Call Construction Options

@type RetrySettings $retrySettings [optional] A retry settings override
      For the call.
@type array<string, string> $autoPopulationSettings Settings for
      auto population of particular request fields if unset.

}

return callable

private createCredentialsWrapper( $credentials, array $credentialsConfig, string $universeDomain)

param mixed $credentials
param array $credentialsConfig
return \CredentialsWrapper
throws \ValidationException

private createOperationsClient(array $options)

param array $options
return \OperationsClient

private createTransport(string $apiEndpoint, $transport, $transportConfig, ?callable $clientCertSource = NULL, bool $hasEmulator = false)

param string $apiEndpoint
param string $transport
param \TransportOptions|array $transportConfig
param callable $clientCertSource
param bool $hasEmulator
return \TransportInterface
throws \ValidationException

private static defaultTransport()

return string

private static determineMtlsEndpoint(string $apiEndpoint)

private static getClientDefaults()

private static getDefaultAudience()

The SERVICE_ADDRESS constant is set by GAPIC clients

private static getGapicVersion(array $options)

private static getGrpcDependencyStatus()

return bool

private getPagedListResponse(string $methodName, array $optionalArgs, string $decodeType, Google\Protobuf\Internal\Message $request, ?string $interfaceName = NULL)

param string $methodName
param array $optionalArgs
param string $decodeType
param \Message $request
param string $interfaceName
return \PagedListResponse

private getPagedListResponseAsync(string $methodName, array $optionalArgs, string $decodeType, Google\Protobuf\Internal\Message $request, ?string $interfaceName = NULL)

param string $methodName
param array $optionalArgs
param string $decodeType
param \Message $request
param string $interfaceName
return \PromiseInterface

private static initGrpcGcpConfig(string $hostName, string $confPath)

private isAssoc(array $arr)

Determine whether given array is associative.

param array $arr
return bool

private isBackwardsCompatibilityMode() : bool

internal

private logConfiguration(Psr\Log\LoggerInterface|false|?null $logger, array $options) : void

param null|false|\LoggerInterface $logger
param string $options

private pluck(string $key, array $arr, bool $isRequired = true)

Pluck a value out of an array.

param string $key
param array $arr
param bool $isRequired
return mixed|null
throws \InvalidArgumentException

private pluckArray(array $keys, array $arr)

Pluck a subset of an array.

param array $keys
param array $arr
return array

private setClientOptions(array $options)

Configures the GAPIC client based on an array of options.

param
array $options { An array of required and optional arguments.
```
@type string $apiEndpoint
      The address of the API remote host, for example "example.googleapis.com. May also
```
- ```
      include the port, for example "example.googleapis.com:443"
```
  @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|array|FetchAuthTokenInterface|CredentialsWrapper $credentials The credentials to be used by the client to authorize API calls. This option accepts either a path to a credentials file, or a decoded credentials file as a PHP array. Advanced usage: In addition, this option can also accept a pre-constructed \Google\Auth\FetchAuthTokenInterface object or \Google\ApiCore\CredentialsWrapper object. Note that when one of these objects are provided, any settings in $authConfig will be ignored. @type array $credentialsConfig Options used to configure credentials, including auth token caching, for the client. For a full list of supporting configuration options, see \Google\ApiCore\CredentialsWrapper::build. @type string|TransportInterface $transport The transport used for executing network requests. May be either the string rest, grpc, or 'grpc-fallback'. Defaults to grpc if gRPC support is detected on the system. Advanced usage: Additionally, it is possible to pass in an already instantiated TransportInterface object. Note that when this objects 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' => [...], 'grpc-fallback' => [...], ]; See the GrpcTransport::build and RestTransport::build methods for the supported options. @type string $versionFile The path to a file which contains the current version of the client. @type string $descriptorsConfigPath The path to a descriptor configuration file. @type string $serviceName The name of the service. @type string $libName The name of the client application. @type string $libVersion The version of the client application. @type string $gapicVersion The code generator version of the GAPIC library. @type callable $clientCertSource A callable which returns the client cert as a string. }
throws \ValidationException

private shouldUseMtlsEndpoint(array $options)

private startApiCall(string $methodName, ?Google\Protobuf\Internal\Message $request = NULL, array $optionalArgs = [])

param string $methodName
param \Message $request

param array $optionalArgs { Call Options

@type array $headers [optional] key-value array containing headers
@type int $timeoutMillis [optional] the timeout in milliseconds for the call
@type array $transportOptions [optional] transport-specific call options
@type RetrySettings|array $retrySettings [optional] A retry settings
      override for the call.

}

experimental
return \PromiseInterface|\PagedListResponse|\BidiStream|\ClientStream|\ServerStream

private startAsyncCall(string $methodName, Google\Protobuf\Internal\Message $request, array $optionalArgs = [])

param string $methodName
param \Message $request

param array $optionalArgs { Call Options

@type array $headers                     [optional] key-value array containing headers
@type int $timeoutMillis                 [optional] the timeout in milliseconds for the call
@type array $transportOptions            [optional] transport-specific call options
@type RetrySettings|array $retrySettings [optional] A retry settings override for the call.

}

experimental
return \PromiseInterface

private startCall(string $methodName, string $decodeType, array $optionalArgs = [], ?Google\Protobuf\Internal\Message $request = NULL, int $callType = 0Google\ApiCore\Call::UNARY_CALL, ?string $interfaceName = NULL)

param string $methodName
param string $decodeType

param array $optionalArgs { Call Options

@type array $headers [optional] key-value array containing headers
@type int $timeoutMillis [optional] the timeout in milliseconds for the call
@type array $transportOptions [optional] transport-specific call options
@type RetrySettings|array $retrySettings [optional] A retry settings
      override for the call.

}

param \Message $request
param int $callType
param string $interfaceName
return \PromiseInterface|\BidiStream|\ClientStream|\ServerStream

private startOperationsCall(string $methodName, array $optionalArgs, Google\Protobuf\Internal\Message $request, $client, ?string $interfaceName = NULL, ?string $operationClass = NULL)

param string $methodName

param array $optionalArgs { Call Options

@type array $headers [optional] key-value array containing headers
@type int $timeoutMillis [optional] the timeout in milliseconds for the call
@type array $transportOptions [optional] transport-specific call options

}

param \Message $request
param \OperationsClient|object $client
param string $interfaceName
param string $operationClass If provided, will be used instead of the default operation response class of {@see \Google\LongRunning\Operation}.
return \PromiseInterface

private subsetArray(array $keys, array $arr)

Return a subset of an array, like pluckArray, without modifying the original array.

param array $keys
param array $arr
return array

private static supportedTransports()

This defaults to all three transports, which One-Platform supports.

Discovery clients should define this function and only return ['rest'].

private validateCallConfig(string $methodName)

private static validateFileExists(string $filePath)

param string $filePath
throws \ValidationException

private static validateGrpcSupport()

throws \ValidationException

private static validateImpl( $arr, $requiredKeys, $allowNull)

Properties

private static $gapicVersionFromFile = NULL

public static $serviceScopes = []

The default scopes required by the service.

Methods

private static defaultTransport()

return string

private static determineMtlsEndpoint(string $apiEndpoint)

private static getClientDefaults()

private static getDefaultAudience()

The SERVICE_ADDRESS constant is set by GAPIC clients

private static getGapicVersion(array $options)

private static getGrpcDependencyStatus()

return bool

private static initGrpcGcpConfig(string $hostName, string $confPath)

private static supportedTransports()

This defaults to all three transports, which One-Platform supports.

Discovery clients should define this function and only return ['rest'].

public static traitValidate(array $arr, array $requiredKeys)

param array $arr Associative array
param array $requiredKeys List of keys to check for in $arr
return array Returns $arr for fluent use

public static validate(array $arr, array $requiredKeys)

param array $arr Associative array
param array $requiredKeys List of keys to check for in $arr
return array Returns $arr for fluent use

private static validateFileExists(string $filePath)

param string $filePath
throws \ValidationException

private static validateGrpcSupport()

throws \ValidationException

private static validateImpl( $arr, $requiredKeys, $allowNull)

public static validateNotNull(array $arr, array $requiredKeys)

param array $arr Associative array
param array $requiredKeys List of keys to check for in $arr
return array Returns $arr for fluent use

ConfigurationCode Formating StyleTab Stop SpacesNumbers (0-9.) only