Search by

agrekom / filter-url-alias-module

macpain

Agrekom Filter URL Alias Module - translatable layered navigation filter URL parameters per store view

Package info

bitbucket.org/agrekom/filter-url-alias-module

Type:magento2-module

pkg:composer/agrekom/filter-url-alias-module

Statistics

Installs: 13

Dependents: 0

Suggesters: 0

v2.0.0 2026-10-22 13:35 UTC

This package is auto-updated.

Last update: 2026-11-04 16:44:46 UTC


README

Translatable URL parameter names for layered navigation filters (Smile ElasticSuite).

Problem

ElasticSuite builds filter URLs as ?<attribute_code>=<option label>, with ?code[0]=a&code[1]=b for several values. The attribute code is global, so the German and UK stores got Polish parameter names, and labels bring special characters into the URL, e.g. https://agrekom.de/spruhgerate.html?pojemnosc_zbiornika=19+Liter or ?cisnienie_robocze=12%2C5+BAR.

With this module the parameter name can be set per store view and filter URLs contain only lowercase letters, digits and hyphens (a-z, 0-9, -): https://agrekom.de/spruhgerate.html?behaelterinhalt=19-liter, ?behaelterinhalt=19-liter--20-liter (two values), ?betriebsdruck=12-5-bar.

The rule is general and applies to every current and future attribute, option and alias (Model/Slugifier.php), no list of characters has to be maintained. Examples: 60 + 19 litrów → 60-19-litrow, Größe_ÄÖÜ → groesse-aeoeue, Żółć & Łódź! → zolc-lodz.

Usage

Stores → Attributes → Product → attribute → tab Filter URL (URL filtra).

The tab has one field for the default value (admin, store 0) and one field per store view. The parameter name is resolved in this order:

  1. alias of the current store view,
  2. default alias (store 0),
  3. slug of the attribute code (cisnienie_robocze → cisnienie-robocze).

The grey placeholder in an empty field is only a suggestion generated from the translated attribute label. It is not saved; type it in to use it.

Validation on save:

  • anything entered is converted to a slug (Tank Capacity_Ü! → tank-capacity-ue), max. 64 characters,
  • reserved names are rejected: p, q, id, cat, product_list_order, product_list_dir, product_list_limit, product_list_mode, filterName (AliasValidator::RESERVED_PARAMS, more can be added in etc/di.xml),
  • the resulting parameter name must be unique in every store view, also against filterable attributes without an alias (their attribute code is the parameter name).

How it works

PartFileDescription
Storageetc/db_schema.xmlTable agrekom_filter_url_alias (attribute_id, store_id, alias), rows removed together with the attribute or store.
Admin tabBlock/Adminhtml/Product/Attribute/Edit/Tab/UrlAlias.php, view/adminhtml/...Tab added to the attribute edit form after Manage Labels. Inputs are posted as filter_url_alias[<store_id>].
SavingObserver/ValidateAttributeUrlAliases.php, Observer/SaveAttributeUrlAliases.phpcatalog_entity_attribute_save_before normalizes and validates (Model/AliasValidator.php), catalog_entity_attribute_save_after writes the rows. A validation error rolls back the attribute save.
FrontendPlugin/Layer/Filter/UseUrlAlias.phpPlugin on Magento\Catalog\Model\Layer\Filter\AbstractFilter (frontend area only). afterGetRequestVar() returns the alias, so all URLs built from the filter use it: filter items, multi-select, reset links, swatches, ElasticSuite "show more" (ajax). beforeApply() sets _requestVar to the alias, because ElasticSuite filters read that protected property directly when applying the filter.
Value slugsModel/OptionSlugProvider.php, Plugin/Layer/Filter/UseUrlAlias.php, Plugin/Layer/Filter/Item/UseValueSlugs.phpElasticSuite still works on option labels. beforeApply() converts slugs from the URL to labels in request params only; the plugin on Smile\ElasticsuiteCatalog\Model\Layer\Filter\Item\Attribute rewrites getUrl() and getRemoveUrl() to slugs. Several values are joined with --, which a slug can never contain. Labels giving the same or an empty slug get the option ID appended, or use it alone.
RedirectsObserver/RedirectToUrlAlias.phpOn catalog_category_view and catalogsearch_result_index (GET, non-ajax), 301 to the slug form of the current store from: attribute codes, aliases of other store views (store switcher, values are translated too), option labels and param[0]=a&param[1]=b. E.g. ?tank-capacity=19-litres on DE → ?behaelterinhalt=19-liter.

Not affected:

  • Option labels in the database and in the storefront – only their URL form changes.
  • Attributes without option rows (price, decimal, boolean) keep their own value format, e.g. ?price=100-200.
  • Hreflang (MageSuite_SeoHreflang) – alternate links of filtered category pages point to the unfiltered category in other stores, the current store link keeps the current query.
  • Category filter (cat) and attributes without an attribute model.

Aliases

Attributes differ between environments (dev / test / production), so aliases are not hard-coded. The data patch Setup/Patch/Data/GenerateFilterUrlAliases.php (logic in Model/AliasGenerator.php) fills them from the database of the environment it runs in, once, during setup:upgrade:

  • for every filterable product attribute (is_filterable or is_filterable_in_search),
  • for every store view label from Manage Labels (eav_attribute_label),
  • alias = slug of the label, e.g. Behälterinhalt → behaelterinhalt, Tank capacity → tank-capacity,
  • store views with a Polish locale (pl_*, i.e. pl_pl and ewarsztat) are skipped, so existing Polish URLs do not change (prefixes configurable in etc/di.xml, argument skippedLocalePrefixes),
  • existing aliases are never overwritten; a slug equal to the attribute code slug, a reserved name or a name already used by another filter in the same store view is skipped.

After the patch, review the generated aliases in the admin tab. Labels which are not good URL names should be corrected by hand, e.g. on dev: typ DE art-von (label "Art von") → art, zastosowanie EN for-use (label "For use") → application.

The data patch Setup/Patch/Data/NormalizeFilterUrlAliases.php converts aliases already stored in an environment to slugs, e.g. entered earlier with an underscore. An alias whose slug is reserved or empty is removed so the fallback applies; one whose slug is already used by another filter stays unchanged. Option values need no patch, their slugs are computed from the current labels.

To generate aliases again (e.g. for attributes added later), only empty ones are filled:

bin/magento setup:db-data:upgrade

does not rerun an applied patch; remove the patch entry first:

DELETE FROM patch_list WHERE patch_name = 'Agrekom\\FilterUrlAlias\\Setup\\Patch\\Data\\GenerateFilterUrlAliases';

Deployment

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

Flush full page cache / Varnish after adding or changing aliases, otherwise cached pages keep the old filter links (old links still work through the 301 redirect).