Integrations / Platforms / Magento 2 / Upgrading to a New Version

Upgrading to a New Version

After installation, you can use Composer (recommended) or Magento’s extension manager to update your Algolia integration.

Using Composer

  1. Run Composer’s update command to update the extension to the newest version:

    Copy 
    $

     composer update algolia/algoliasearch-magento-2

  2. After updating the extension, save the configuration again even if you didn’t change the settings. To do this, navigate to Stores > Configuration > Algolia Search and hit save.

  3. After saving the configuration, reindex your Magento indices according to the indexing instructions.

Read the change log for any additional steps that you need to take.

Using the extension manager

Upgrade your extension using Magento’s extension manager in your store’s back office: Stores > Tools > Web Setup Wizard > Extension Manager

Read the Magento developer documentation for more information on updating your extension.

After upgrading

If enabled, it’s recommended that you clear your indexing queue and perform a full reindex after you have upgraded your extension. This prevents call_user_func_array() errors generated from deprecated or renamed job methods that have been stored before your upgrade.

To clear your indexing queue:

  1. Go to Stores > Algolia Search > Indexing Queue
  2. Click the Clear Queue button.
  3. Perform a complete reindex afterward by running the following command from the root of your Magento project:
Copy 
$

php bin/magento indexer:reindex algolia_products algolia_categories algolia_pages algolia_suggestions algolia_additional_sections

Upgrading to version 3 for Magento 2.4 compatibility

The Magento 2.4 release introduced several significant changes, including removing the MySQL search engine option.

To be compatible with Magento version 2.4, Algolia’s extension (starting from version 3.x) doesn’t include back-end rendering features that rely on the MySQL search adapter classes.

Legacy versions (v1.x and v2.x) of the extension aren’t compatible with Magento 2.4, and Algolia dropped support for these legacy branches at the end of 2020.

If you’re running Magento 2.4, you must install version 3.x of the extension to ensure compatibility.

The benefits of upgrading from version 2 to version 3

  • You get the latest version of InstantSearch and API client and all their new features
  • Improved performance and a significant reduction in the number of search requests sent
  • Better indexing queue logs
  • Support for Magento 2.4
  • Help from Algolia’s Support team (you need to be on version 3 for that).

Upgrading from version 1 to version 2

Version 2 updates:

Upgrading to version 2 from version 1 will break your Algolia integration. The following guidance indicates solutions to these breaking changes.

Customization

Review the InstantSearch migration guide to help upgrade any front-end customizations you may have made.

Styling

The algoliasearch.css style sheet was removed and restructured into the following files:

  • view/frontend/web/internals/algolia-reset.css
  • view/frontend/web/internals/grid.css
  • view/frontend/web/internals/autocomplete.css
  • view/frontend/web/internals/instantsearch.v3.css

Algolia introduced a reset theme to simplify theme customization.

Templates

Templates have a new HTML structure and modified class names:

  • view/frontend/templates/instant/wrapper.phtml
  • view/frontend/templates/instant/stats.phtml
  • view/frontend/templates/instant/hit.phtml
  • view/frontend/templates/instant/facet.phtml

You must copy these changes to your customized template for the update to work.

Layout

  • view/frontend/layout/algolia_search_handle.xml

You must copy these changes to your customized template for the update to work.

JavaScript

There are several changes included with the InstantSearch upgrade. Refer to the migration guide’s change log if you’re experiencing JavaScript errors with your customizations after the upgrade.

If you’ve overridden the extension’s JavaScript files, they have changed as well:

  • view/frontend/web/internals/common.js
  • view/frontend/web/instantsearch.js
  • view/frontend/web/click_conversion_analytics.js has been replaced by view/frontend/insights.js.

Search parameters

Configuring searchParameters on instantSearchOptions is no longer supported: instead, you must pass the arguments with the configure widget. If you have any customizations to modify searchParameters, you need to change the event from beforeInstantsearchInit to beforeWidgetInitialization.

See the example below of how to add a new ruleContexts with beforeWidgetInitialization:

Copy 
1
2
3
4
5
6

algolia.registerHook('beforeWidgetInitialization', function (allWidgetConfiguration) {
    allWidgetConfiguration.configure = allWidgetConfiguration.configure || {};
    allWidgetConfiguration.configure.ruleContexts.push('new-context');

    return allWidgetConfiguration;
});

collapsible

The collapsible widget option has been replaced with the collapsed option in the new panel widget introduced in InstantSearch v3. The panel widget wraps other widgets in a consistent panel design. The extension exposes it by adding panelOptions to the widget options, which accepts an object of options for the panel widget.

You can access the panelOptions using the beforeWidgetInitialization event:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

algolia.registerHook('beforeWidgetInitialization', function (
  allWidgetConfiguration,
  algoliaBundle
) {
  for (var i = 0; i < allWidgetConfiguration.refinementList.length; i++) {
    // Example which updates the header of a widget using `panelOptions`
    var panelOptions = allWidgetConfiguration.refinementList[i].panelOptions;
    panelOptions.templates['header'] =
      '<div class="updated-header">Updated Title</div>';
    allWidgetConfiguration.refinementList[i].panelOptions = panelOptions;
  }

  return allWidgetConfiguration;
});

The searchBox widget was upgraded in InstantSearch version 3 and no longer accepts input fields as containers anymore. To account for this change, the extension updated the wrapper template so that the default configuration for the InstantSearch input targets a <div> element:

Copy 
1

<div id="instant-search-bar"></div>

If your search input isn’t working, ensure that the upgrade correctly updated the view/frontend/templates/instant/wrapper.phtml file.

Routing

The uiState has been updated and is no longer backward-compatible with InstantSearch version 1. This affects users who have modified routing methods from the common.js file.

Previous
Moving to production
Next
Front end (UI/UX)
Did you find this page helpful?