diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md index fb65a3ba..7d4a93d1 100644 --- 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. algolia_client
(setup publicly manually, you may not have been using it) Renamed - search.client + search.client or `SearchClient` class autowired diff --git a/example-search.png b/example-search.png new file mode 100644 index 00000000..25ad8491 Binary files /dev/null and b/example-search.png differ diff --git a/src/Command/SearchImportCommand.php b/src/Command/SearchImportCommand.php index 1136e86e..93a042f5 100644 --- 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 $batch * * @return array */ diff --git a/src/Engine.php b/src/Engine.php index 92abd7de..2d33478b 100644 --- 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 $searchableEntities - * @param array $requestOptions + * @param array $searchableEntities + * @param array|RequestOptions $requestOptions * * @return array * @@ -77,8 +78,8 @@ public function index($searchableEntities, $requestOptions) * * This method enables you to remove one or more objects from an index. * - * @param array $searchableEntities - * @param array $requestOptions + * @param array $searchableEntities + * @param array|RequestOptions $requestOptions * * @return array * @@ -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 $requestOptions + * @param string $indexName + * @param 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 $requestOptions + * @param string $indexName + * @param 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 $requestOptions + * @param string $query + * @param string $indexName + * @param array|RequestOptions $requestOptions * * @return 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 $requestOptions + * @param string $query + * @param string $indexName + * @param array|RequestOptions $requestOptions * * @return 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 $requestOptions + * @param string $query + * @param string $indexName + * @param array|RequestOptions $requestOptions * * @return int * diff --git a/src/Resources/config/services.xml b/src/Resources/config/services.xml index 4327afd8..059cad4f 100644 --- a/src/Resources/config/services.xml +++ b/src/Resources/config/services.xml @@ -21,6 +21,8 @@ %env(ALGOLIA_API_KEY)% + + diff --git a/src/SearchService.php b/src/SearchService.php index a9a4ec57..e7fe3326 100644 --- 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 $searchables - * @param array $requestOptions + * @param ObjectManager $objectManager + * @param object|array $searchables + * @param array|RequestOptions $requestOptions * * @return \Algolia\AlgoliaSearch\Response\AbstractResponse */ @@ -154,9 +155,9 @@ public function index(ObjectManager $objectManager, $searchables, $requestOption } /** - * @param object|array $searchables - * @param ObjectManager $objectManager - * @param array $requestOptions + * @param object|array $searchables + * @param ObjectManager $objectManager + * @param array|RequestOptions $requestOptions * * @return \Algolia\AlgoliaSearch\Response\AbstractResponse */ @@ -175,8 +176,8 @@ public function remove(ObjectManager $objectManager, $searchables, $requestOptio } /** - * @param string $className - * @param array $requestOptions + * @param string $className + * @param array|RequestOptions $requestOptions * * @return \Algolia\AlgoliaSearch\Response\AbstractResponse */ @@ -188,8 +189,8 @@ public function clear($className, $requestOptions = []) } /** - * @param string $className - * @param array $requestOptions + * @param string $className + * @param 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 $requestOptions + * @param ObjectManager $objectManager + * @param string $className + * @param string $query + * @param array|RequestOptions $requestOptions * * @return array * @@ -239,9 +240,9 @@ public function search(ObjectManager $objectManager, $className, $query = '', $r } /** - * @param string $className - * @param string $query - * @param array $requestOptions + * @param string $className + * @param string $query + * @param array|RequestOptions $requestOptions * * @return array * @@ -255,9 +256,9 @@ public function rawSearch($className, $query = '', $requestOptions = []) } /** - * @param string $className - * @param string $query - * @param array $requestOptions + * @param string $className + * @param string $query + * @param array|RequestOptions $requestOptions * * @return int * diff --git a/src/SearchServiceInterface.php b/src/SearchServiceInterface.php index a14cd165..3d3519b6 100644 --- a/src/SearchServiceInterface.php +++ b/src/SearchServiceInterface.php @@ -2,6 +2,7 @@ namespace Algolia\SearchBundle; +use Algolia\AlgoliaSearch\RequestOptions\RequestOptions; use Doctrine\Common\Persistence\ObjectManager; interface SearchServiceInterface @@ -33,18 +34,18 @@ public function getConfiguration(); public function searchableAs($className); /** - * @param ObjectManager $objectManager - * @param object|array $searchables - * @param array $requestOptions + * @param \Doctrine\Common\Persistence\ObjectManager $objectManager + * @param object|array $searchables + * @param array|RequestOptions $requestOptions * * @return \Algolia\AlgoliaSearch\Response\AbstractResponse */ public function index(ObjectManager $objectManager, $searchables, $requestOptions = []); /** - * @param ObjectManager $objectManager - * @param object|array $searchables - * @param array $requestOptions + * @param \Doctrine\Common\Persistence\ObjectManager $objectManager + * @param object|array $searchables + * @param array|RequestOptions $requestOptions * * @return \Algolia\AlgoliaSearch\Response\AbstractResponse */ @@ -65,10 +66,10 @@ public function clear($className); public function delete($className); /** - * @param ObjectManager $objectManager - * @param string $className - * @param string $query - * @param array $requestOptions + * @param \Doctrine\Common\Persistence\ObjectManager $objectManager + * @param string $className + * @param string $query + * @param array|RequestOptions $requestOptions * * @return array * @@ -77,9 +78,9 @@ public function delete($className); public function search(ObjectManager $objectManager, $className, $query = '', $requestOptions = []); /** - * @param string $className - * @param string $query - * @param array $requestOptions + * @param string $className + * @param string $query + * @param array|RequestOptions $requestOptions * * @return array * @@ -88,9 +89,9 @@ public function search(ObjectManager $objectManager, $className, $query = '', $r public function rawSearch($className, $query = '', $requestOptions = []); /** - * @param string $className - * @param string $query - * @param array $requestOptions + * @param string $className + * @param string $query + * @param array|RequestOptions $requestOptions * * @return int * diff --git a/tests/TestCase/SearchServiceTest.php b/tests/TestCase/SearchServiceTest.php index bed966de..86a51b0c 100644 --- a/tests/TestCase/SearchServiceTest.php +++ b/tests/TestCase/SearchServiceTest.php @@ -89,7 +89,7 @@ public function testIndexedDataAreSearchable() ]); $this->assertCount(1, $searchPost['hits']); - $searchPostEmpty = $this->searchService->rawSearch(Post::class, 'with no result', ); + $searchPostEmpty = $this->searchService->rawSearch(Post::class, 'with no result'); $this->assertCount(0, $searchPostEmpty['hits']); $searchComment = $this->searchService->rawSearch(Comment::class);