Upgrading to a New Version

We strongly recommend using composer to install the Algolia extension for Magento. Instructions on the installation process can be found in our quick start guide. Unfortunately, updating the extension using other installation methods is not supported at this time.

Using Composer

Run composer’s update command to update the extension to the newest version.

$
composer update algolia/algoliasearch-magento-2

After updating the extension, the configuration should be saved again even if the settings weren’t changed. Navigate to Stores > Configuration > Algolia Search and hit save.

With the configuration saved, you should reindex your Magento indices according to these indexing instructions.

Make sure you read the changelog for any additional steps that need to be taken.

Extension Manager

As an alternative, you can upgrade your extension using Magento’s extension manager in your store’s back office. You can find the manager by going to:

Stores > Tools > Web Setup Wizard > Extension Manager

Please read this Magento devdoc for more information on how to update your extension.

After upgrading

If enabled, we recommend to 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 prior to your upgrade. You can clear your indexing queue by going to Stores > Algolia Search > Indexing Queue and hitting the Clear Queue button. To make sure Algolia is up to date, perform a complete reindex afterwards. You can do this by running the following command from the root of you Magento project:

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

Upgrading from v1 to v2

The upgrade to version 2 contains updates of our main libraries:

• Algolia PHP Client from v1 to v2
• InstantSearch from v2 to v4

We highly recommend you to review the InstantSearch migration guide to help assist with your upgrade for any front-end customizations you may have done.

Styling

In an effort of better organize our styles, we removed the algoliasearch.css stylesheet and restructured it 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

Additionally, we’ve introduced a reset theme to simplify with theme customization.

Templates

We’ve updated templates with a new HTML structure and modified class names. Please note that these changes need to be carried over to your customized template for the update to work.

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

Layout

With the added stylesheets, please note that these changes need to be carried over to your customized layout for the update to work.

• view/frontend/layout/algolia_search_handle.xml

JavaScript

There are several changes included with the InstantSearch upgrade from v2 to v4. If you’re experiencing JavaScript errors with your customizations after the upgrade, please refer to the migration guide to review the full changelog.

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

• view/frontend/web/internals/common.js
• view/frontend/web/instantsearch.js

Please be advised that 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. You need to pass the arguments via the configure widget moving forward. 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 via beforeWidgetInitialization:

1
2
3
4
5
6
algolia.registerHook('beforeWidgetInitialization', function (allWidgetConfiguration) {
    allWidgetConfiguration.configure = allWidgetConfiguration.configure || {};
    allWidgetConfiguration.configure.ruleContexts.push('new-context');

    return allWidgetConfiguration;
});

collapsible

We’ve replaced the collapsible widget option 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:

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;
});

searchBox

The searchBox widget was upgraded in InstantSearch v3 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:

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

If your search input isn’t working, make sure that the view/frontend/templates/instant/wrapper.phtml file was properly updated.

Routing

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