agrekom / filter-url-alias-module
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
Requires
- magento/framework: *
- smile/elasticsuite: *
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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:
- alias of the current store view,
- default alias (store 0),
- 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 inetc/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. |
| Value slugs | Model/OptionSlugProvider.php, Plugin/Layer/Filter/UseUrlAlias.php, Plugin/Layer/Filter/Item/UseValueSlugs.php | ElasticSuite 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. |
| Redirects | Observer/RedirectToUrlAlias.php | On 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¶m[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_filterableoris_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 inetc/di.xml, argumentskippedLocalePrefixes), - 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).