Add LRO support (#42)

- Generate operations API
- Add operations wrapper
- Address PR comments
  - Add max duration setting to pollUntilComplete
  - Add operationSucceeded and operationFailed functions
  - Update OperationsClient namespace
  - Edit OperationsClient comments

src/ApiCallable.php

@@ -120,6 +120,20 @@ private static function setPageStreaming($callable, $pageStreamingDescriptor)
         return $inner;
     }
 
+    private static function setLongRunnning($callable, $longRunningDescriptor)
+    {
+        $inner = function () use ($callable, $longRunningDescriptor) {
+            $response = call_user_func_array($callable, func_get_args());
+            $name = $response->getName();
+            $client = $longRunningDescriptor['operationsClient'];
+            $options = $longRunningDescriptor + [
+                'lastProtoResponse' => $response,
+            ];
+            return new OperationResponse($name, $client, $options);
+        };
+        return $inner;
+    }
+
     private static function setCustomHeader($callable, $headerDescriptor)
     {
         $inner = function () use ($callable, $headerDescriptor) {
@@ -138,16 +152,18 @@ private static function setCustomHeader($callable, $headerDescriptor)
     }
 
     /**
-     * @param Grpc\BaseStub $stub the gRPC stub to make calls through.
+     * @param \Grpc\BaseStub $stub the gRPC stub to make calls through.
      * @param string $methodName the method name on the stub to call.
-     * @param Google\GAX\CallSettings $settings the call settings to use for this call.
+     * @param \Google\GAX\CallSettings $settings the call settings to use for this call.
      * @param array $options {
      *     Optional.
-     *     @type Google\GAX\PageStreamingDescriptor $pageStreamingDescriptor
+     *     @type \Google\GAX\PageStreamingDescriptor $pageStreamingDescriptor
      *           the descriptor used for page-streaming.
-     *     @type Google\GAX\AgentHeaderDescriptor $headerDescriptor
+     *     @type \Google\GAX\AgentHeaderDescriptor $headerDescriptor
      *           the descriptor used for creating GAPIC header.
      * }
+     *
+     * @return callable
      */
     public static function createApiCall($stub, $methodName, CallSettings $settings, $options = [])
     {
@@ -176,6 +192,10 @@ public static function createApiCall($stub, $methodName, CallSettings $settings,
             $apiCall = self::setPageStreaming($apiCall, $options['pageStreamingDescriptor']);
         }
 
+        if (array_key_exists('longRunningDescriptor', $options)) {
+            $apiCall = self::setLongRunnning($apiCall, $options['longRunningDescriptor']);
+        }
+
         if (array_key_exists('headerDescriptor', $options)) {
             $apiCall = self::setCustomHeader($apiCall, $options['headerDescriptor']);
         }

src/GrpcCredentialsHelper.php

@@ -56,7 +56,7 @@ class GrpcCredentialsHelper
      *     will be passed as optional arguments to Google\Auth\FetchAuthTokenCache
      *     when caching is enabled.
      *
-     *     @var Google\Auth\CredentialsLoader $credentialsLoader
+     *     @var \Google\Auth\CredentialsLoader $credentialsLoader
      *          A user-created CredentialsLoader object. Defaults to using
      *          ApplicationDefaultCredentials
      *     @var boolean $enableCaching
@@ -111,7 +111,7 @@ public function createCallCredentialsCallback()
     /**
      * Creates a gRPC client stub.
      *
-     * @param function $generatedCreateStub
+     * @param callable $generatedCreateStub
      *        Function callback which must accept two arguments ($hostname, $opts)
      *        and return an instance of the stub of the specific API to call.
      *        Generally, this should just call the stub's constructor and return
@@ -121,10 +121,10 @@ public function createCallCredentialsCallback()
      * @param array $options {
      *     Optional. Options for configuring the gRPC stub.
      *
-     *     @type Grpc\ChannelCredentials $sslCreds
+     *     @type \Grpc\ChannelCredentials $sslCreds
      *           A `ChannelCredentials` for use with an SSL-enabled channel.
      *           Default: a credentials object returned from
-     *           Grpc\ChannelCredentials::createSsl()
+     *           \Grpc\ChannelCredentials::createSsl()
      * }
      */
     public function createStub($generatedCreateStub, $serviceAddress, $port, $options = [])