Advanced Search for Magento 2

Fast storefront autocomplete for Magento Open Source 2.4. Queries the catalog's OpenSearch or Elasticsearch index directly, with an optional bootstrap-free PHP endpoint that skips Magento's request startup cost entirely.

Requirements

Installation

Install via Composer after configuring your credentials. See your dashboard for your license key.

composer config repositories.ayasoftware composer https://www.ayasoftware.com/repo

composer config --global http-basic.www.ayasoftware.com your@email.com YOUR_LICENSE_KEY

composer require ayasoftware/advancedsearch:^1.0
bin/magento module:enable Ayasoftware_Advancedsearch
bin/magento setup:upgrade

# Adds as_url / as_image / as_price to every indexed product document
bin/magento indexer:reindex catalogsearch_fulltext

bin/magento advancedsearch:config:generate

cp vendor/ayasoftware/advancedsearch/pub/instant.php pub/advancedsearch.php
bin/magento cache:flush

bin/magento setup:di:compile

Verify the installation

bin/magento module:status Ayasoftware_Advancedsearch

# Standard controller
curl --fail-with-body 'https://your-store.example/advancedsearch/ajax/suggest?q=desk'

# Fast mode, if deployed
curl --fail-with-body 'https://your-store.example/advancedsearch.php?q=desk&store=1&limit=8'

A successful response is HTTP 200 with items, total, and currency keys. Finally, type at least two characters into the theme's search input and confirm the dropdown appears.

Admin Settings

All settings live under a single group: Stores → Configuration → Ayasoftware → Advanced Search → Instant Search. Every field supports website/store-view scope.

General & autocomplete

Suggestions

Fast Mode Endpoint

Three pieces make fast mode work:

1. Pre-generated config — bin/magento advancedsearch:config:generate writes var/advancedsearch/config_<store-id>.json per store view.
2. Bootstrap-free endpoint — pub/advancedsearch.php reads that JSON and queries the engine directly, with no Magento bootstrap, DI compilation, or database connection.
3. Index-time display data — a plugin on the product data mapper appends as_url, as_image, and as_price to every indexed document.

The standard Magento controller (/advancedsearch/ajax/suggest) provides the same response through the normal framework path, and is used automatically when fast mode is disabled or pub/advancedsearch.php is absent.

nginx: fast endpoint returns 404

Magento's default nginx config only allows a fixed whitelist of PHP entry points. Create <magento-root>/nginx.conf.advancedsearch (nginx auto-includes all nginx.conf* files in the Magento root) before Magento's catch-all deny rule:

nginx.conf.advancedsearchlocation ~ ^/advancedsearch\.php$ {
    try_files $uri =404;
    fastcgi_pass   fastcgi_backend;
    fastcgi_buffers 16 16k;
    fastcgi_buffer_size 32k;

    fastcgi_param  PHP_FLAG  "session.auto_start=off \n suhosin.session.cryptua=off";
    fastcgi_param  PHP_VALUE "memory_limit=256M \n max_execution_time=30";
    fastcgi_read_timeout 10s;
    fastcgi_connect_timeout 10s;

    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
    include        fastcgi_params;
}

Then reload nginx (nginx -s reload or service nginx reload).

Apache

No extra configuration needed — pub/.htaccess only rewrites requests to index.php when the requested file does not exist on disk, and pub/advancedsearch.php is a real file. If you still get a 404, check that the document root points to pub/ (not the Magento root) and that AllowOverride All (or at least FileInfo Options) is set for the pub/ directory.

Search Relevance

• name is always boosted to at least weight 10 so product-name matches dominate autocomplete — raw attribute weights often favor SKU/part-number, which otherwise ranks accessories above the products people actually search for.
• Weak searchable-attribute matches are suppressed in autocomplete when strong product name or SKU matches exist. Broad description/attribute matches remain available when no stronger match exists.
• The token x is dropped from multi-word queries by default (Stopterms, comma-separated). Without this, a dimension search like 30" x 72" desk matches and boosts every product whose text merely contains the letter x.
• Configurable-product index values are reduced to the parent display value in autocomplete, and HTML entities are decoded — Mars HeatTech™ Pullover displays as Mars HeatTech™ Pullover.

Endpoint reports "name" contains values separated by \n

Magento's catalogsearch indexer concatenates multi-value attributes (e.g. all configurable variant names) with newlines into a single string. Lib/SearchClient.php's firstScalar() strips the extra lines and returns only the first value (the parent product name).

Synonyms & Redirects

Synonyms (advancedsearch/general/synonyms) — add one row per bidirectional synonym group. Example: search term sofa, synonyms couch, settee.

Redirect Rules (advancedsearch/general/redirects) — add exact-query redirects shown in autocomplete. The target accepts https://example.com/page, /target-path, or target-path.

Search Analytics & Popular Queries

Analytics events cover submitted searches, autocomplete product clicks, redirect clicks, result positions, and add-to-cart conversions attributed to a prior search within the configured attribution window (per browser tab). Successful autocomplete queries and Magento search history feed Popular Search Suggestions, optionally weighted by recency using the configured half-life.

Popular query refresh

Fast-mode query data refreshes automatically via a cron job:

crontab.xmlayasoftware_advancedsearch_refresh_popular_queries  17 * * * *  (hourly)

Or immediately by re-running bin/magento advancedsearch:config:generate.

Zero-result reporting

Zero-result query reporting is available under Marketing → Advanced Search → Zero Results, where synonyms and redirects can be created directly from a reported query.

JSON API

Both suggestion endpoints accept the same query parameters:

Example response

{
  "q": "desk",
  "total": 3,
  "items": [
    {
      "name": "Example Desk",
      "sku": "DESK-01",
      "url": "https://example.test/example-desk.html",
      "image": "https://example.test/media/catalog/product/desk.jpg",
      "price": 199
    }
  ],
  "suggestions": [],
  "categories": [],
  "pages": [],
  "redirect_url": "",
  "currency": "$"
}

Treat this response as a storefront API, not a stable public integration contract — validate it when upgrading the module.

Security notes

• The fast endpoint only ever executes a fixed, parameterized _search query — user input lands in a multi_match value, never in query syntax, field names, or the URL path.
• Engine errors are logged, never returned to the client.
• Responses expose only fields intended for the storefront (name, sku, url, image, price).
• Rate-limit /advancedsearch.php at your CDN/WAF like any search endpoint.

Headless storefronts

1. Proxy /advancedsearch.php or /advancedsearch/ajax/suggest through the storefront dev/production server so requests remain same-origin.
2. Debounce input and call the endpoint after the configured minimum number of characters.
3. Render and keyboard-navigate the returned products, queries, categories, and pages.
4. Route Magento product/category URLs appropriately for the headless app.

For Daffodil specifically, proxying /graphql is not sufficient — add an explicit proxy rule for the chosen endpoint and build an Angular autocomplete component.

Troubleshooting

Typing in the search box does nothing

1. View the page source and confirm it contains Ayasoftware_Advancedsearch/js/advancedsearch.
2. Confirm the configured selector matches a real text/search input (default #search).
3. Open the browser Network panel, type at least the configured minimum number of characters, and locate the suggest request.
4. Test that request URL with curl — the frontend intentionally closes the dropdown when the endpoint returns an error.
5. On a headless storefront, Magento layout XML is not executed there — see Headless storefronts.

Endpoint returns 502 or "search unavailable"

The public response deliberately hides search-engine details. Check connectivity from the same PHP runtime that serves Magento:

curl http://your-search-host:9200/
curl http://your-search-host:9200/<index-alias>/_count

Then inspect the host, port, index alias, and timeout_ms in var/advancedsearch/config_<store-id>.json — regenerate if stale. Intermittent failures, especially on the first request after idle time, can mean the configured timeout is too aggressive for DNS resolution or a cold search node. Temporarily disable Fast Mode and test /advancedsearch/ajax/suggest to isolate fast-mode/web-server issues.

Configuration was not generated

bin/magento advancedsearch:config:generate
ls -la var/advancedsearch/

Verify the web/PHP user can read the generated files.

Deprecation warning at the top of the JSON response

PHP 8.5 deprecated curl_close(). If a deprecation notice leaks into the response body it breaks JSON parsing on the frontend — update to the latest Lib/SearchClient.php, which no longer calls it (a no-op in PHP 8+ anyway).

Endpoint works but no products are returned

1. Confirm the engine is reachable and the configured alias contains documents.
2. Re-run bin/magento indexer:reindex catalogsearch_fulltext to rebuild the index with as_url, as_image, and as_price.
3. Re-run bin/magento advancedsearch:config:generate.
4. Check that products have Search or Catalog/Search visibility.

Changelog

New Features

• FeatMixed autocomplete sections for products, categories, CMS pages, and popular searches
• FeatCategory suggestions with store-aware URLs and breadcrumb paths
• FeatCMS page suggestions searching titles, headings, URL keys, and visible Page Builder or HTML body content
• FeatPopular-query suggestions sourced from Magento search history and successful autocomplete queries
• FeatOptional recent-usage weighting with a configurable half-life and hourly config refresh
• FeatSearch analytics events for submitted searches, autocomplete clicks, redirects, result positions, and attributed add-to-cart conversions
• FeatPer-tab search attribution with a configurable conversion window

Search Relevance

• ImprProduct names have a minimum relevance boost so name matches rank above weak description or URL matches
• ImprWeak searchable-attribute matches are suppressed in autocomplete when strong product name or SKU matches exist
• FeatConfigurable stop terms for noisy tokens such as x in dimension searches
• FeatConfigurable synonym groups and exact-query redirects

Improvements

• ImprProduct display names stored separately at index time; HTML entities decoded in autocomplete
• ImprConfigurable-product index values reduced to the parent display value in autocomplete
• ImprDistinct, responsive dropdown sections for each suggestion type
• ImprFast-mode configuration now includes content suggestions, popular queries, tracking secrets, and suggestion limits

Database

• FeatAggregate storage for successful autocomplete queries
• FeatAppend-only search analytics event storage — query, result count, click position, product, quantity, source, session hash, and timestamp