upgrade(v4): improve upgrade guide

algolia · Oct 11, 2019 · 7b02cea · 7b02cea
1 parent 00f197b
commit 7b02cea
Show file tree

Hide file tree

Showing 8 changed files with 145 additions and 72 deletions.
diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md
@@ -15,20 +15,92 @@ Upgrade your `algolia/search-bundle` dependency from `3.4` to `^4.0` in your `co
 We strongly encourage you to take a look at the [PHP Client v2 upgrade guide](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/php/) to get acquainted with the new features deployed in this version.
 
 
-## Features ✨
+## Improved DX with the usage of our PHP Client v2
+Its entire redesign makes it faster and easier to use, but don't worry about the method signature changes: most of the the previous usage stay the same, everything is transparent to you. You will also benefit from its new features, the Algolia Client being now public (it relies on your ALGOLIA_APP_ID and ALGOLIA_API_KEY env variables), like the possibility to copy a whole index, to copy all the rules from an index, to replace all data in one index, creating secured API keys, and more. We also added better Exceptions, made the instantiation of the clients easier, and created many more features to help you have the best possible experience with Algolia. Please head over the [PHP Client v2 upgrade guide](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/php/) to know more.
 
-### Improved DX with the usage of our PHP Client v2
-Its entire redesign makes it faster and easier to use, but don't worry about the method signature changes: most of the the previous usage stay unchanged, everything is transparent to you. You will also benefit from its new features, like the possibility to copy a whole index, to copy all the rules from an index, to replace all data in one index, and more. We also added better Exceptions, made the instantiation of the clients easier, and created many more features to help you have the best possible experience with Algolia. Please head over the [PHP Client v2 upgrade guide](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/php/) to know more.
+Examples:
 
-### Waitable operations
-Methods from the `SearchService` are now *waitable*. You can rely on the [`wait()`](https://www.algolia.com/doc/api-reference/api-methods/wait-task/) method to wait for your task to be completely handled by the Engine before moving on, while previously you had to make a separate query swith the taskID returned from the operation to achieve the same result. The `wait()` method can be chained on any methods from the `SearchService`. Example: `$searchService->index(...)->wait()`.
+```php
+/**
+* Either autowire the SearchClient service
+*/
+
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+
+class ArticleController extends AbstractController
+{
+    private $searchService;
+
+    public function __construct(SearchServiceInterface $searchService)
+    {
+        $this->searchService = $searchService;
+    }
+
+    public function test(SearchClient $client)
+    {
+        // Copy an index
+        $client->copyIndex(SRC_INDEX_NAME, DEST_INDEX_NAME);
+
+        // Copy all the rules from an index
+        $client->copyRules(SRC_INDEX_NAME, DEST_INDEX_NAME);
+
+        // Replace all objects
+        $index = $client->initIndex(DEST_INDEX_NAME);
+        $index->replaceAllObjects($objects);
+    }
+}
+```
+
+```php
+/**
+* Or fetch it directly from the container. Note that the Controller class is deprecated.
+*/
+
+use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+
+class ArticleController extends Controller
+{
+    private $searchService;
+
+    public function __construct(SearchServiceInterface $searchService)
+    {
+        $this->searchService = $searchService;
+    }
+
+    public function test(SearchClient $client)
+    {
+        $client = $this->get('search.client');
+        // Copy an index
+        $client->copyIndex(SRC_INDEX_NAME, DEST_INDEX_NAME);
+
+        // Copy all the rules from an index
+        $client->copyRules(SRC_INDEX_NAME, DEST_INDEX_NAME);
+
+        // Replace all objects
+        $index = $client->initIndex(DEST_INDEX_NAME);
+        $index->replaceAllObjects($objects);
+    }
+}
+```
+
+## Waitable operations
+Methods from the `SearchService` are now *waitable*. You can rely on the [`wait()`](https://www.algolia.com/doc/api-reference/api-methods/wait-task/) method to wait for your task to be completely handled by the Engine before moving on, while previously you had to make a separate query swith the taskID returned from the operation to achieve the same result. The `wait()` method can be chained on any methods from the `SearchService`. 
+
+Examples: 
+```php
+// index objects and wait for the task to finish
+$response = $this->searchService->index($entityManager, $objects)->wait();
+
+// clear an index
+$response = $this->searchService->clear($className)->wait();
+```
 
 That also means that the return type of those methods has changed. They now all return an Algolia `AbstractResponse`. Please update your code accordingly.
 
-### All the logic in one single service
+## All the logic in one single service
 The bundle has been made much more simple with the merge of the two classes `AlgoliaEngine` and `IndexManager` to one `SearchService`. The `SearchService` is your only entry point for any operation on the engine.
 
-### Add any options to your operations
+## Add any options to your operations
 To have the most consistent, predictable, and future-proof method signature, we followed three rules:
 
 - All required parameters have a single argument each
@@ -50,8 +122,8 @@ $result = $this->indexManager->remove(
 
 # v4
 $result = $this->searchService->remove(
-    $searchablePosts,
     $this->get('doctrine')->getManager(),
+    $searchablePosts,
     // here you can pass any requestOptions, for example 'X-Forwarded-For', 'X-Algolia-UserToken'...
     [
         'X-Forwarded-For' => '0.0.0.0',
@@ -76,9 +148,9 @@ $result = $this->indexManager->search(
 
 # v4
 $result = $this->searchService->search(
-    'foo',
-    Post::class,
     $this->get('doctrine')->getManager(),
+    Post::class,
+    'foo',
     // all the optional parameters are now sent as once in the $requestOptions
     // be careful as page argument now starts from 0
     [
@@ -91,11 +163,9 @@ $result = $this->searchService->search(
 );
 ```
 
-### Direct access to Algolia Client
-We realized it was a common need to have a direct access to the Algolia Client anytime you had to perform advanced operations, so we decided to make it public by default. Moreover, with our PHP client v2 you now have way more features to interact with your indexes, like creating secured API keys, retrieving multiple objects accross different indexes, etc.
-
-### And also
+## And also
 * Better doc blocks to improve the public API and auto-completion.
+![alt text](./example-search.png)
 * Better quality tooling, so the bundle is now extra robust and future-proof.
 
 
@@ -203,7 +273,7 @@ used directly and may be up to changes in minor versions.
     <tr>
         <td><code>algolia_client</code><br>(setup publicly manually, you may not have been using it)</td>
         <td>Renamed</td>
-        <td><code>search.client</code></td>
+        <td><code>search.client</code> or `SearchClient` class autowired</td>
     </tr>
 </tbody>
 </table>

diff --git a/example-search.png b/example-search.png
diff --git a/src/Command/SearchImportCommand.php b/src/Command/SearchImportCommand.php
@@ -2,9 +2,7 @@
 
 namespace Algolia\SearchBundle\Command;
 
-use Algolia\AlgoliaSearch\Response\AbstractResponse;
 use Algolia\SearchBundle\Entity\Aggregator;
-use Algolia\SearchBundle\Responses\SearchServiceResponse;
 use Algolia\SearchBundle\SearchServiceInterface;
 use Doctrine\Common\Persistence\ManagerRegistry;
 use Symfony\Component\Console\Input\InputArgument;
@@ -112,7 +110,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
     }
 
     /**
-     * @param AbstractResponse $batch
+     * @param array<int, array> $batch
      *
      * @return array<string, int>
      */

diff --git a/src/Engine.php b/src/Engine.php
@@ -2,6 +2,7 @@
 
 namespace Algolia\SearchBundle;
 
+use Algolia\AlgoliaSearch\RequestOptions\RequestOptions;
 use Algolia\AlgoliaSearch\Response\BatchIndexingResponse;
 use Algolia\AlgoliaSearch\Response\NullResponse;
 use Algolia\AlgoliaSearch\SearchClient;
@@ -28,8 +29,8 @@ public function __construct(SearchClient $client)
      * This method allows you to create records on your index by sending one or more objects.
      * Each object contains a set of attributes and values, which represents a full record on an index.
      *
-     * @param array<int, SearchableEntity>    $searchableEntities
-     * @param array<string, int|string|array> $requestOptions
+     * @param array<int, SearchableEntity>                   $searchableEntities
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return array<string, BatchIndexingResponse>
      *
@@ -77,8 +78,8 @@ public function index($searchableEntities, $requestOptions)
      *
      * This method enables you to remove one or more objects from an index.
      *
-     * @param array<int, SearchableEntity>    $searchableEntities
-     * @param array<string, int|string|array> $requestOptions
+     * @param array<int, SearchableEntity>                   $searchableEntities
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return array<string, BatchIndexingResponse>
      *
@@ -124,8 +125,8 @@ public function remove($searchableEntities, $requestOptions)
      * If you want to remove the entire index and not just its records, use the
      * delete method instead.
      *
-     * @param string                          $indexName
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $indexName
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return \Algolia\AlgoliaSearch\Response\AbstractResponse
      */
@@ -149,8 +150,8 @@ public function clear($indexName, $requestOptions)
      * If the index has replicas, they will be preserved but will no longer be
      * linked to their primary index. Instead, they’ll become independent indices.
      *
-     * @param string                          $indexName
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $indexName
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return \Algolia\AlgoliaSearch\Response\AbstractResponse
      */
@@ -168,9 +169,9 @@ public function delete($indexName, $requestOptions)
     /**
      * Method used for querying an index.
      *
-     * @param string                          $query
-     * @param string                          $indexName
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $query
+     * @param string                                         $indexName
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return array<string, int|string|array>
      *
@@ -184,9 +185,9 @@ public function search($query, $indexName, $requestOptions)
     /**
      * Search the index and returns the objectIDs.
      *
-     * @param string                          $query
-     * @param string                          $indexName
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $query
+     * @param string                                         $indexName
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return array<string, int|string|array>
      *
@@ -202,9 +203,9 @@ public function searchIds($query, $indexName, $requestOptions)
     /**
      * Search the index and returns the number of results.
      *
-     * @param string                          $query
-     * @param string                          $indexName
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $query
+     * @param string                                         $indexName
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return int
      *

diff --git a/src/Resources/config/services.xml b/src/Resources/config/services.xml
@@ -21,6 +21,8 @@
             <argument key="$apiKey">%env(ALGOLIA_API_KEY)%</argument>
         </service>
 
+        <service id="Algolia\AlgoliaSearch\SearchClient" alias="search.client" />
+
         <service id="Algolia\SearchBundle\SearchServiceInterface" alias="search.service"/>
         <service id="Algolia\SearchBundle\Settings\SettingsManager" alias="search.settings_manager"/>
 

diff --git a/src/SearchService.php b/src/SearchService.php
@@ -2,6 +2,7 @@
 
 namespace Algolia\SearchBundle;
 
+use Algolia\AlgoliaSearch\RequestOptions\RequestOptions;
 use Algolia\SearchBundle\Entity\Aggregator;
 use Algolia\SearchBundle\Responses\SearchServiceResponse;
 use Doctrine\Common\Persistence\ObjectManager;
@@ -121,9 +122,9 @@ public function searchableAs($className)
     }
 
     /**
-     * @param ObjectManager                   $objectManager
-     * @param object|array<int, object>       $searchables
-     * @param array<string, int|string|array> $requestOptions
+     * @param ObjectManager                                  $objectManager
+     * @param object|array<int, object>                      $searchables
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return \Algolia\AlgoliaSearch\Response\AbstractResponse
      */
@@ -154,9 +155,9 @@ public function index(ObjectManager $objectManager, $searchables, $requestOption
     }
 
     /**
-     * @param object|array<int, object>       $searchables
-     * @param ObjectManager                   $objectManager
-     * @param array<string, int|string|array> $requestOptions
+     * @param object|array<int, object>                      $searchables
+     * @param ObjectManager                                  $objectManager
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return \Algolia\AlgoliaSearch\Response\AbstractResponse
      */
@@ -175,8 +176,8 @@ public function remove(ObjectManager $objectManager, $searchables, $requestOptio
     }
 
     /**
-     * @param string                          $className
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $className
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return \Algolia\AlgoliaSearch\Response\AbstractResponse
      */
@@ -188,8 +189,8 @@ public function clear($className, $requestOptions = [])
     }
 
     /**
-     * @param string                          $className
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $className
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return \Algolia\AlgoliaSearch\Response\AbstractResponse
      */
@@ -201,10 +202,10 @@ public function delete($className, $requestOptions = [])
     }
 
     /**
-     * @param ObjectManager                   $objectManager
-     * @param string                          $className
-     * @param string                          $query
-     * @param array<string, int|string|array> $requestOptions
+     * @param ObjectManager                                  $objectManager
+     * @param string                                         $className
+     * @param string                                         $query
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return array<int, object>
      *
@@ -239,9 +240,9 @@ public function search(ObjectManager $objectManager, $className, $query = '', $r
     }
 
     /**
-     * @param string                          $className
-     * @param string                          $query
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $className
+     * @param string                                         $query
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return array<string, int|string|array>
      *
@@ -255,9 +256,9 @@ public function rawSearch($className, $query = '', $requestOptions = [])
     }
 
     /**
-     * @param string                          $className
-     * @param string                          $query
-     * @param array<string, int|string|array> $requestOptions
+     * @param string                                         $className
+     * @param string                                         $query
+     * @param array<string, int|string|array>|RequestOptions $requestOptions
      *
      * @return int
      *