Algolia Search & Discovery for Magento 2

repository·main·Indexed 41 days ago

https://github.com/algolia/algoliasearch-magento-2

A high-performance, typo-tolerant search extension for Magento Open Source and Adobe Commerce. It replaces standard search with an autocompletion menu, InstantSearch results pages, and Algolia Recommend integration. Supports Magento 2.4 (version 3.x) and PHP 8.3, 8.4, or 8.5. Includes specialized modules for Multi-Source Inventory (MSI), a Search adapter for SSR/SEO, and an Ingestion module for API-driven indexing.

Tokens
6.1K
Snippets
26
Records
37
Agent score
71%

What's inside Algolia

  1. Overview of Algolia Search & Discovery for Magento 2

    main

    The Algolia extension replaces the default search functionality in Magento Open Source and Adobe Commerce with a high-performance, typo-tolerant search experience. It leverages Algolia's infrastructure to provide:

    • Autocompletion menu: An instant dropdown menu that provides access to the entire catalog regardless of category or attribute complexity.
    • Instantsearch results page: Real-time updates for search results, navigation, and pagination after every keystroke.
    • Recommend: Integration with Algolia Recommend to display features like "Frequently Bought Together" and "Related Products" on product detail pages.

    The extension is built upon algoliasearch-client-php, autocomplete.js, and instantsearch.js.

  2. How the Algolia async queue system works

    main

    All indexing operations are handled via a cron-driven asynchronous queue to ensure Magento performance is not impacted by API calls.

    • Persistence: Jobs are stored in the algoliasearch_queue table.
    • Processing: The Cron/ProcessQueue.php entry point triggers the queue processing.
    • Security: To prevent arbitrary code execution, the system uses a whitelist (ALLOWED_HANDLERS in the Job class). Only specific class/method pairs are permitted to be executed from the queue.
    • Job Prioritization: The queue uses a fixed ratio (FULL_REINDEX_TO_REALTIME_JOBS_RATIO = 0.33) to balance workloads. This ensures that full reindex jobs do not starve delta (incremental) updates, which are guaranteed at least 67% of the processing capacity.
    • Logging & Archiving: Execution logs are stored in algoliasearch_queue_log, and completed or failed jobs are moved to algoliasearch_queue_archive.
  3. Understand the Algolia indexing data flows

    main

    The extension uses two primary data flows to synchronize Magento 2 data with Algolia:

    1. Delta (Incremental) Indexing

    Used for real-time updates when catalog or CMS data changes. It uses Magento's materialized views (mview) or Plugin/Observer interceptors to detect changes. These changes are enqueued as buildIndexList jobs, and records are updated in-place on the live index.

    2. Full (Complete Rebuild) Indexing

    Used to rebuild an entire entity index from scratch. This is typically triggered via CLI commands (e.g., algolia:reindex:products).

    Note on Temporary Indexing: If enabled (via QueueHelper::useTmpIndex()), full indexing builds into a temporary index first. Once complete, the IndexMover atomically swaps the temporary index into production to prevent the live index from being in a partial state. If disabled (default), records are written directly to the live index.

    Delta (incremental):
      Catalog/CMS change
        -> mview subscription or Plugin/Observer
        -> executeList($ids) on the Magento indexer
        -> BatchQueueProcessor.handleDeltaIndex()
        -> buildIndexList queue jobs
        -> IndexBuilder -> RecordBuilder -> AlgoliaConnector
        -> records updated in-place on the live index
    
    Full (complete rebuild):
      CLI command (algolia:reindex:*) or executeFull() if enabled
        -> BatchQueueProcessor.handleFullIndex()
        -> buildIndexFull queue jobs
        -> IndexBuilder -> RecordBuilder -> AlgoliaConnector
        -> records written to the live index (default)
           OR to a temporary index (if temp indexing enabled)
        -> IndexMover atomically swaps temp -> production (when temp index used)
  4. Understand the Algolia frontend data flow

    main

    The frontend delivers search configuration from the Magento server to client-side JavaScript libraries.

    The Flow:

    1. Admin settings are configured in system.xml.
    2. ConfigHelper and specialized helpers read these settings.
    3. Block/Configuration.php serializes this configuration into a JSON object.
    4. This object is consumed by client-side libraries: autocomplete.js, instantsearch.js, insights.js, and recommend.js.
    5. Search results are rendered entirely on the client-side (no server-side search results are returned by Magento).
  5. Customize the Algolia Magento 2 frontend

    main

    The extension provides frontend implementations for Autocomplete, InstantSearch, and Search Insights.

    Important Implementation Note: As of version 3.15.x, the algoliaBundle global has been removed. Libraries are now loaded independently via RequireJS. When customizing, you should not attempt to customize the underlying libraries directly; instead, use hooks provided in the area between the extension and the libraries.

    Reference Documentation:

    JavaScript Library Versions by Extension Version:

    Extension Versionautocomplete.jsinstantsearch.jssearch-insights.jsrecommend-js.js
    3.x0.38.0*4.15.0*1.7.1N/A
    3.15.x1.17.94.77.02.17.31.16.0
    >=3.19.x1.19.94.106.02.17.3N/A (see note)
  6. Install the MSI compatibility module

    main

    Use this module if your store uses Magento's Multi-Source Inventory (MSI) and you need Algolia records to reflect aggregated stock status and per-source quantities.

    Requirements:

    • Base extension >=3.17.3
    • For base extension >=3.19.0, use MSI module ^1.5.0.

    Installation:

    composer require algolia/algoliasearch-inventory-magento-2
  7. Install the Ingestion module

    main

    This module routes product indexing through the Algolia Ingestion API. Use this if you require dashboard-managed JavaScript transformations, low-latency Collections support, or improved observability via Ingestion runs.

    Requirements:

    • PHP 8.3+
    • Magento 2.4+
    • Base extension ^3.19.0

    Installation:

    composer require algolia/algoliasearch-ingestion-magento-2
  8. Install the Search adapter module

    main

    This module registers Algolia as a native Magento search engine backend, enabling server-side rendered (SSR) category and search-results pages. This is ideal for SEO and crawler readability. It can run alongside InstantSearch for hybrid setups.

    Requirements:

    • PHP 8.2+
    • Magento 2.4+
    • Base extension ^3.18
    • For base extension >=3.19.0, use adapter module >=0.10.0.

    Installation:

    composer require algolia/algoliasearch-adapter-magento-2
  9. Install the Algolia Magento 2 extension via Composer

    main

    The recommended installation method is using Composer. To ensure you stay on a specific minor version while receiving automatic patch updates, use the tilde (~) operator in your composer.json file.

    Example for version 3.19.x:

    "algolia/algoliasearch-magento-2": "~3.19.0"
  10. Use Algolia CLI commands for reindexing

    main

    Full reindexing is an intentional, scheduled operation. Because full reindexing can be resource-intensive, it is disabled by default in the Magento indexer framework to prevent accidental triggers from third-party modules or ERP integrations.

    To perform a full reindex, use the provided CLI commands. Commands are organized by concern, including Indexer/ (for per-entity or all-entity reindexing), Queue/, and Replica/.

  11. Configure JavaScript bundling for Algolia libraries

    main

    The Algolia JavaScript libraries are compatible with standard Magento JavaScript bundling. If you use advanced bundling via the RequireJS optimizer, you must apply the Babel transpiler to the underlying source code.

    Below is a sample .babelrc configuration for the transpiler:

    {
        "presets": [
            [
                "@babel/preset-env",
                {
                    "exclude": ["@babel/plugin-transform-template-literals"]
                }
            ],
            ["minify", { "builtIns": false, "mangle": false }]
        ],
        "comments": false
    }