PHPFUI/InstaDoc
 
Copied!

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.

    CloneableInstantiable
    Properties
    public static $serviceScopes = []
     

    The default scopes required by the service.

    Methods
    public __call( $method, $args)
     

    Handles execution of the async variants for each documented method.

    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.
      *Important*: If you accept a credential configuration (credential
      JSON/File/Stream) from an external source for authentication to Google Cloud
      Platform, you must validate it before providing it to any Google API or library.
      Providing an unvalidated credential configuration to Google APIs can compromise
      the security of your systems and data. For more information {@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
      }
    • 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(Google\LongRunning\CancelOperationRequest $request, array $callOptions = []) : void
     

    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.

    The async variant is {@see \OperationsClient::cancelOperationAsync()} .

    • example samples/OperationsClient/cancel_operation.php
    • param \CancelOperationRequest $request A request to house fields associated with the call.
    • param array $callOptions { 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 Thrown if the API call fails.
    public close()
     

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

    • experimental
    public deleteOperation(Google\LongRunning\DeleteOperationRequest $request, array $callOptions = []) : void
     

    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.

    The async variant is {@see \OperationsClient::deleteOperationAsync()} .

    • example samples/OperationsClient/delete_operation.php
    • param \DeleteOperationRequest $request A request to house fields associated with the call.
    • param array $callOptions { 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 Thrown if the API call fails.
    public getOperation(Google\LongRunning\GetOperationRequest $request, array $callOptions = []) : Google\LongRunning\Operation
     

    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.

    The async variant is {@see \OperationsClient::getOperationAsync()} .

    • example samples/OperationsClient/get_operation.php
    • param \GetOperationRequest $request A request to house fields associated with the call.
    • param array $callOptions { 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 \Operation
    • throws \ApiException Thrown if the API call fails.
    public listOperations(Google\LongRunning\ListOperationsRequest $request, array $callOptions = []) : Google\ApiCore\PagedListResponse
     

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

    The async variant is {@see \OperationsClient::listOperationsAsync()} .

    • example samples/OperationsClient/list_operations.php
    • param \ListOperationsRequest $request A request to house fields associated with the call.
    • param array $callOptions { 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 \PagedListResponse
    • throws \ApiException Thrown if the API call fails.
    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(Google\LongRunning\WaitOperationRequest $request, array $callOptions = []) : Google\LongRunning\Operation
     

    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.

    The async variant is {@see \OperationsClient::waitOperationAsync()} .

    • example samples/OperationsClient/wait_operation.php
    • param \WaitOperationRequest $request A request to house fields associated with the call.
    • param array $callOptions { 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 \Operation
    • throws \ApiException Thrown if the API 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\Client\OperationsClient::CODEGEN_NAME = 'gapic'
     

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

    private Google\LongRunning\Client\OperationsClient::DEFAULT_SERVICE_PORT = 443
     

    The default port of the service.

    private Google\LongRunning\Client\OperationsClient::SERVICE_ADDRESS = 'longrunning.googleapis.com'
     

    The default address of the service.

    • deprecated SERVICE_ADDRESS_TEMPLATE should be used instead.
    private Google\LongRunning\Client\OperationsClient::SERVICE_ADDRESS_TEMPLATE = 'longrunning.UNIVERSE_DOMAIN'
     

    The address template of the service.

    private Google\LongRunning\Client\OperationsClient::SERVICE_NAME = 'google.longrunning.Operations'
     

    The name 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 $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.

    1. Keys in $array2 take precedence over keys in $array1.
    2. 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(array $options)
    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
    © 2025 Bruce Wells
    Search Namespaces \ Classes
    Configuration