Get URL Masking¶

Extension for Magento 2¶

User Manual¶

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Table of Contents¶

Section	Page
1 Requirements	2
2 Installation	2
3 Configuration	3
4 How It Works	6
5 Advanced Configuration	8
6 Troubleshooting	9

1 Requirements¶

Magento 2.4 or higher (compatible with 2.4.8)
PHP 7.4 or higher
Compatible with Luma and Hyvä themes
Optional: Smile ElasticSuite from version 2.9.0 (for ElasticSuite integration)

2 Installation¶

Via Composer¶

composer require copex/module-prg
php bin/magento module:enable CopeX_PRG
php bin/magento setup:upgrade
php bin/magento cache:flush

3 Configuration¶

The module configuration is located in the Magento 2 backend under Stores > Configuration > General > Web > CopeX PRG.

The module ships with a default configuration that already includes commonly used Magento templates and layout blocks.

3.1 Activation¶

Enabled — Activates or deactivates the entire PRG module. When disabled, no links are masked and all templates are rendered without modification.

3.2 Exclude Configuration¶

Exclude configuration — Defines rules for links that should not be masked. Matching links receive the attribute data-noparse="", which prevents the module from masking them.

Table columns:

Column	Description
Type	`Template` or `Name` (layout name)
Value	Template path or layout block name
CSS Selector	Optional CSS selector to narrow the scope (empty = all `<a>` tags)

Type "Template": Specifies the path to the template file, e.g.:

Magento_Theme::html/header/logo.phtml

Type "Name": Specifies the layout block name, e.g.:

catalog.topnav

Example — Exclude all links in the logo template from masking:

Type	Value	CSS Selector
Template	`Magento_Theme::html/header/logo.phtml`	(empty)

After this configuration, links in the logo template look like this:

<a href="https://myshop.com/product.html" data-noparse=""></a>

3.3 Replace Configuration¶

Replace configuration — Defines rules for links that should be masked. Matching links are converted to PRG-masked links where the original href value is replaced with # and the original URL is stored base64-encoded in the data-prg attribute.

Table columns: Identical to the exclude configuration.

Result of a masked URL:

<a data-prg="aHR0cHM6Ly93d3cubXlzaG9wLmNvbS9wcm9kdWN0Lmh0bWw=" href="#">
  View Product
</a>

Example — Mask only certain links within the top navigation:

Type	Value	CSS Selector
Name	`catalog.topnav`	`a.nav-item--link`

3.4 CSS Selectors¶

CSS selectors can be used to restrict masking to specific elements within a template or layout block. Multiple selectors are separated by a comma:

a.nav-link,.category-link

If no selector is specified, all <a> tags within the relevant template/block are processed.

3.5 ElasticSuite Masking¶

Mask ElasticSuite — Enables PRG masking for the faceted navigation of Smile ElasticSuite. This option is only visible when the module Smile_ElasticsuiteCore is installed.

When ElasticSuite masking is enabled, the filter links in the layered navigation are automatically masked without requiring template customizations.

4 How It Works¶

4.1 URL Masking Flow¶

The module processes all rendered HTML responses according to the following flow:

Magento renders a template or a layout block.
The PRG plugin/observer calls DomParser::processTemplate().
The parser checks whether a rule is defined for the current template path or layout name.
Exclude rules: Matching links receive data-noparse="".
Replace rules: Matching links are masked:
href is replaced with #
The original URL is stored base64-encoded in data-prg
The browser loads the modified HTML page.
When a user clicks a masked link, JavaScript sends a POST request to the PRG route.
The Controller/Router decodes the URL, validates it, and redirects with HTTP 303.

4.2 Redirect Route¶

Masked links are processed via the route /prg/index/index. The module registers its own frontend router for this path.

Validation: - The encoded URL is base64-decoded. - It is checked whether the result is a valid URL. - Invalid or empty URLs are redirected to the referrer URL or the shop homepage.

4.3 The `data-noparse` Attribute¶

Links with the attribute data-noparse="" are not masked by the PRG module. This attribute can also be added directly to custom templates to improve performance:

<a href="https://myshop.com/home.html" data-noparse="">Home</a>

4.4 Configuration Examples¶

Example 1: Mask all links in the footer

Type	Value	CSS Selector
Name	`footer_links_block`	(empty)

Example 2: Mask only external links in the navigation

Type	Value	CSS Selector
Name	`catalog.topnav`	`a[target="_blank"]`

Example 3: Mask My Account links (default configuration)

Type	Value	CSS Selector
Template	`Magento_Customer::account/navigation.phtml`	(empty)

5 Advanced Configuration¶

5.1 Apache Rewrite (Magento Bypass)¶

For maximum performance, the PRG redirect can be processed without the Magento bootstrap overhead. Add the following configuration to your Apache configuration file:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteCond %{REQUEST_URI} ^/prg/index/index/ [NC]
    RewriteCond %{DOCUMENT_ROOT}/vendor/copex/module-prg/prg.php -f
    RewriteRule ^(.*)$ %{DOCUMENT_ROOT}/vendor/copex/module-prg/prg.php [L]
</IfModule>

5.2 Nginx Configuration¶

location ~* ^/prg/index/index/ {
    root $MAGENTO_ROOT;
    include fastcgi_params;
    fastcgi_pass fastcgi_backend;
    fastcgi_param SCRIPT_FILENAME $document_root/vendor/copex/module-prg/prg.php;
    fastcgi_param REQUEST_URI $request_uri;
    try_files $uri /vendor/copex/module-prg/prg.php$is_args$args /index.php$is_args$args;
}

With these web server configurations, the PHP script prg.php is called directly without starting Magento. This significantly reduces the response time for redirects.

6 Troubleshooting¶

Links are not being masked — Make sure the module is enabled. Check that the rule has the correct type (Template/Name) and the correct value. The template path must match exactly with the Magento-internal template identifier.
All links are blocked (href="#") — If clicking a masked link produces no redirect, check that JavaScript is loading correctly and there are no JS errors in the browser console.
Page after the redirect is wrong — Check whether the CSS selector in the configuration is correct. An overly broad selector may unintentionally mask links.
ElasticSuite navigation stops working — If the module is affecting Smile ElasticSuite navigation, check that the Mask ElasticSuite option is configured correctly. If problems persist, this option can be disabled.
PRG route returns 404 — Make sure the module is correctly installed and the cache has been cleared. Check that the frontend routes are properly registered.
Redirect loop — This can occur when rules are configured to mask templates that appear on the PRG redirect page itself. Exclude such templates in the exclude configuration.

License¶

Proprietary — CopeX GmbH. One license per production Magento instance.