agrekom / filter-url-alias-module

v1.1.0 2026-10-22 13:35 UTC

Requires

• magento/framework: *
• smile/elasticsuite: *

OSL-3.0, AFL-3.0

Published on Packagist.org on 2026-10-22 13:35 UTC

README

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

Problem

ElasticSuite builds filter URLs as ?<attribute_code>=<option label>. Option labels are translated per store view, but the attribute code is global, so the German and UK stores got Polish parameter names, e.g. https://agrekom.de/spruhgerate.html?pojemnosc_zbiornika=19+Liter.

With this module the parameter name can be set per store view: https://agrekom.de/spruhgerate.html?behaelterinhalt=19+Liter.

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. attribute code (module behaviour is unchanged when no alias is set).

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:

• allowed characters: a-z, 0-9, -, _, 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

Part	File	Description
Storage	etc/db_schema.xml	Table agrekom_filter_url_alias (attribute_id, store_id, alias), rows removed together with the attribute or store.
Admin tab	Block/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>].
Saving	Observer/ValidateAttributeUrlAliases.php, Observer/SaveAttributeUrlAliases.php	catalog_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.
Frontend	Plugin/Layer/Filter/UseUrlAlias.php	Plugin 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.
Redirects	Observer/RedirectToUrlAlias.php	On catalog_category_view and catalogsearch_result_index (GET, non-ajax): a parameter that is the attribute code (old links) or an alias of another store view (store switcher) is redirected with 301 to the alias of the current store. When the source is another store view's alias, option labels are translated as well (e.g. ?tank-capacity=19+litres on DE → ?behaelterinhalt=19+Liter).

Not affected:

• Option labels (parameter values) – they are already translated per store view in Manage Options, the module does not change them.
• 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 = transliterated label, e.g. Behälterinhalt → behaelterinhalt, Tank capacity → tank-capacity (German umlauts → ae, oe, ue, ss),
• 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 label equal to the attribute code, 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.

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).