feat(php): add waitForApiKey method (#792)

Author: damcou

clients/algoliasearch-client-php/lib/Support/Helpers.php

@@ -2,7 +2,9 @@
 
 namespace Algolia\AlgoliaSearch\Support;
 
+use Algolia\AlgoliaSearch\Api\SearchClient;
 use Algolia\AlgoliaSearch\Exceptions\ExceededRetriesException;
+use Algolia\AlgoliaSearch\Exceptions\NotFoundException;
 
 final class Helpers
 {
@@ -138,4 +140,85 @@ public static function retryUntil(
             'Maximum number of retries (' . $maxRetries . ') exceeded.'
         );
     }
+
+    /**
+     * Helper for Api keys which retries a function until some conditions are met
+     *
+     * @param string $operation
+     * @param SearchClient $searchClient search client
+     * @param string $key
+     * @param array $apiKey
+     * @param int $maxRetries Max number of retries
+     * @param int $timeout Timeout
+     * @param string $timeoutCalculation name of the method to call to calculate the timeout
+     * @param array $requestOptions
+     *
+     * @throws ExceededRetriesException
+     *
+     * @return void
+     *
+     */
+    public static function retryForApiKeyUntil(
+        $operation,
+        $searchClient,
+        $key,
+        $apiKey,
+        $maxRetries,
+        $timeout,
+        $timeoutCalculation = 'Algolia\AlgoliaSearch\Support\Helpers::linearTimeout',
+        $requestOptions = []
+    ) {
+        $retry = 0;
+
+        while ($retry < $maxRetries) {
+            try {
+                $response = $searchClient->getApiKey($key, $requestOptions);
+
+                // In case of an addition, if there was no error, the $key has been added as it should be
+                if ($operation === 'add') {
+                    return;
+                }
+
+                // In case of an update, check if the key has been updated as it should be
+                if ($operation === 'update') {
+                    if (self::isKeyUpdated($response, $apiKey)) {
+                        return;
+                    }
+                }
+
+                // Else try again ...
+            } catch (NotFoundException $e) {
+                // In case of a deletion, if there was an error, the $key has been deleted as it should be
+                if (
+                    $operation === 'delete' &&
+                    $e->getMessage() === 'Key does not exist'
+                ) {
+                    return;
+                }
+
+                // Else try again ...
+            }
+
+            $retry++;
+            usleep(
+                call_user_func_array($timeoutCalculation, [$timeout, $retry])
+            );
+        }
+
+        throw new ExceededRetriesException(
+            'Maximum number of retries (' . $maxRetries . ') exceeded.'
+        );
+    }
+
+    private static function isKeyUpdated($key, $keyParams)
+    {
+        $upToDate = true;
+        foreach ($keyParams as $param => $value) {
+            if (isset($key[$param])) {
+                $upToDate &= $key[$param] === $value;
+            }
+        }
+
+        return $upToDate;
+    }
 }

templates/javascript/clients/client/api/helpers.mustache

@@ -19,7 +19,7 @@ waitForTask({
 },
 
 /**
- * Helper: Wait for an API key to be valid, updated or deleted based on a given `operation`.
+ * Helper: Wait for an API key to be added, updated or deleted based on a given `operation`.
  *
  * @summary Wait for an API key task to be processed.
  * @param waitForApiKeyOptions - The waitForApiKeyOptions object.

templates/php/api.mustache

@@ -322,6 +322,48 @@ use {{invokerPackage}}\Support\Helpers;
             $timeout
         );
     }
+
+    /**
+     * Wait for an API key to be added, updated or deleted based on a given `operation`.
+     *
+     * @param string $operation the `operation` that was done on a `key`
+     * @param string $key the `key` that has been added, deleted or updated
+     * @param array $apiKey Necessary to know if an `update` operation has been processed, compare fields of the response with it.
+     * @param int|null $maxRetries Maximum number of retries
+     * @param int|null $timeout Timeout
+     * @param array $requestOptions the requestOptions to send along with the query, they will be merged with the transporter requestOptions
+     *
+     * @throws ExceededRetriesException
+     *
+     * @return void
+     */
+    public function waitForApiKey(
+        $operation,
+        $key,
+        $apiKey = null,
+        $maxRetries = null,
+        $timeout = null,
+        $requestOptions = []
+    ) {
+        if ($timeout === null) {
+            $timeout = $this->config->getWaitTaskTimeBeforeRetry();
+        }
+
+        if ($maxRetries === null) {
+            $maxRetries = $this->config->getDefaultMaxRetries();
+        }
+
+        Helpers::retryForApiKeyUntil(
+            $operation,
+            $this,
+            $key,
+            $apiKey,
+            $maxRetries,
+            $timeout,
+            null,
+            $requestOptions
+        );
+    }
     {{/isSearchClient}}
 
     private function sendRequest($method, $resourcePath, $headers, $queryParameters, $httpBody, $requestOptions, $useReadTransporter = false)

website/docs/clients/guides/copy-or-move-index.mdx

@@ -41,7 +41,7 @@ await client.waitForTask({ indexName: '<SOURCE_INDEX_NAME>', taskID });
 ```php
 $client = SearchClient::create(
     '<YOUR_APP_ID>',
-    '<YOUR_APP_ID>'
+    '<YOUR_API_KEY>'
 );
 
 $response = $client->operationIndex(

website/docs/clients/guides/wait-for-a-task-to-finish.mdx

@@ -46,7 +46,7 @@ await client.waitForTask({
 ```php
 $client = SearchClient::create(
     '<YOUR_APP_ID>',
-    '<YOUR_APP_ID>'
+    '<YOUR_API_KEY>'
 );
 
 $response = $client->saveObject(

website/docs/clients/guides/wait-for-api-key-to-be-valid.mdx

@@ -47,6 +47,52 @@ await client.waitForApiKey({
   // We provide the updated fields to check if the changes have been applied
   apiKey: updatesToPerform,
 });
+
+// Call for delete
+await client.deleteApiKey({ key });
+
+// Wait for delete to be done
+await client.waitForApiKey({ operation: 'delete', key });
+```
+
+</TabItem>
+<TabItem value="php">
+
+> An `operation` can either be `add` | `update` | `delete`
+
+```php
+$client = SearchClient::create(
+    '<YOUR_APP_ID>',
+    '<YOUR_API_KEY>'
+);
+
+$response = $client->addApiKey([
+    'acl' => ['analytics', 'browse', 'editSettings'],
+]);
+
+$key = $response['key'];
+
+// Poll the task status with defaults values
+$client->waitForApiKey('add', $key);
+
+// The fields to update on your API key
+$updatesToPerform = [
+  'acl' => ['analytics', 'search'],
+  'indexes' => ['products'],
+];
+
+// Call for update
+$client->updateApiKey($key, $updatesToPerform);
+
+// Wait for update to be done
+$client->waitForApiKey('update', $key, $updatesToPerform);
+
+// Call for delete
+$client->deleteApiKey($key);
+
+// Wait for delete to be done
+$client->waitForApiKey('delete', $key);
+
 ```
 
 </TabItem>