Get URL-Maskierung¶

Extension for Magento 2¶

Bedienungsanleitung¶

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

Inhaltsverzeichnis¶

Abschnitt	Seite
1 Voraussetzungen	2
2 Installation	2
3 Konfiguration	3
4 Funktionsweise	6
5 Erweiterte Konfiguration	8
6 Fehlerbehandlung	9

1 Voraussetzungen¶

Magento 2.4 oder höher (kompatibel mit 2.4.8)
PHP 7.4 oder höher
Kompatibel mit Luma- und Hyvä-Themes
Optional: Smile ElasticSuite ab Version 2.9.0 (für 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 Konfiguration¶

Die Konfiguration des Moduls finden Sie im Magento 2 Backend unter Shops > Konfiguration > Allgemein > Web > CopeX PRG.

Das Modul ist standardmäßig mit einer Basiskonfiguration ausgeliefert, die häufig verwendete Magento-Templates und Layout-Blöcke bereits enthält.

3.1 Aktivierung¶

Aktiviert — Aktiviert oder deaktiviert das gesamte PRG-Modul. Wenn deaktiviert, werden keine Links maskiert und alle Templates werden ohne Veränderung ausgegeben.

3.2 Ausschluss-Konfiguration¶

Ausschluss-Konfiguration — Definiert Regeln für Links, die nicht maskiert werden sollen. Passende Links erhalten das Attribut data-noparse="", das verhindert, dass das Modul sie maskiert.

Tabellenstruktur:

Spalte	Beschreibung
Typ	`Template` oder `Name` (Layout-Name)
Wert	Template-Pfad oder Layout-Block-Name
CSS-Selektor	Optionaler CSS-Selektor zur Einschränkung (leer = alle `<a>`-Tags)

Typ "Template": Gibt den Pfad zur Template-Datei an, z. B.:

Magento_Theme::html/header/logo.phtml

Typ "Name": Gibt den Layout-Block-Namen an, z. B.:

catalog.topnav

Beispiel — Alle Links im Logo-Template vom Masking ausschließen:

Typ	Wert	CSS-Selektor
Template	`Magento_Theme::html/header/logo.phtml`	(leer)

Nach dieser Konfiguration sehen die Links im Logo-Template so aus:

<a href="https://meinshop.at/produkt.html" data-noparse=""></a>

3.3 Ersetzungs-Konfiguration¶

Ersetzungs-Konfiguration — Definiert Regeln für Links, die maskiert werden sollen. Passende Links werden in PRG-maskierte Links umgewandelt, bei denen der originale href-Wert durch # ersetzt und die originale URL base64-kodiert im Attribut data-prg gespeichert wird.

Tabellenstruktur: Identisch mit der Ausschluss-Konfiguration.

Ergebnis einer maskierten URL:

<a data-prg="aHR0cHM6Ly93d3cubWVpbnNob3AuYXQvcHJvZHVrdC5odG1s" href="#">
  Zum Produkt
</a>

Beispiel — Nur bestimmte Links innerhalb der Topnav maskieren:

Typ	Wert	CSS-Selektor
Name	`catalog.topnav`	`a.nav-item--link`

3.4 CSS-Selektoren¶

CSS-Selektoren können verwendet werden, um die Maskierung auf bestimmte Elemente innerhalb eines Templates oder Layout-Blocks zu beschränken. Mehrere Selektoren werden mit Komma getrennt:

a.nav-link,.category-link

Wenn kein Selektor angegeben wird, werden alle <a>-Tags innerhalb des betreffenden Templates/Blocks verarbeitet.

3.5 ElasticSuite-Maskierung¶

ElasticSuite maskieren — Aktiviert die PRG-Maskierung für die facettierte Navigation von Smile ElasticSuite. Diese Option ist nur sichtbar, wenn das Modul Smile_ElasticsuiteCore installiert ist.

Bei aktivierter ElasticSuite-Maskierung werden die Filterlinks in der Layered-Navigation automatisch maskiert, ohne dass Template-Anpassungen notwendig sind.

4 Funktionsweise¶

4.1 URL-Maskierungsablauf¶

Das Modul verarbeitet alle ausgelieferten HTML-Responses nach folgendem Ablauf:

Magento rendert ein Template oder einen Layout-Block.
Das PRG-Plugin/Observer ruft DomParser::processTemplate() auf.
Der Parser prüft, ob für den aktuellen Template-Pfad oder Layout-Namen eine Regel definiert ist.
Ausschluss-Regeln: Passende Links erhalten data-noparse="".
Ersetzungs-Regeln: Passende Links werden maskiert:
href wird durch # ersetzt
Die originale URL wird base64-kodiert in data-prg gespeichert
Der Browser lädt die modifizierte HTML-Seite.
Klickt der Benutzer auf einen maskierten Link, sendet JavaScript eine POST-Anfrage an die PRG-Route.
Der Controller/Router dekodiert die URL, validiert sie und leitet mit HTTP 303 weiter.

4.2 Redirect-Route¶

Maskierte Links werden über die Route /prg/index/index verarbeitet. Das Modul registriert einen eigenen Frontend-Router für diesen Pfad.

Validierung: - Die kodierte URL wird base64-dekodiert. - Es wird geprüft, ob es sich um eine valide URL handelt. - Ungültige oder leere URLs werden auf die Referrer-URL oder die Shop-Startseite umgeleitet.

4.3 Das `data-noparse` Attribut¶

Links mit dem Attribut data-noparse="" werden vom PRG-Modul nicht maskiert. Dieses Attribut kann auch direkt in eigene Templates eingefügt werden, um die Performance zu verbessern:

<a href="https://meinshop.at/startseite.html" data-noparse="">Startseite</a>

4.4 Konfigurationsbeispiele¶

Beispiel 1: Alle Links im Footer maskieren

Typ	Wert	CSS-Selektor
Name	`footer_links_block`	(leer)

Beispiel 2: Nur externe Links in der Navigation maskieren

Typ	Wert	CSS-Selektor
Name	`catalog.topnav`	`a[target="_blank"]`

Beispiel 3: Mein Konto Links maskieren (Standard-Konfiguration)

Typ	Wert	CSS-Selektor
Template	`Magento_Customer::account/navigation.phtml`	(leer)

5 Erweiterte Konfiguration¶

5.1 Apache-Rewrite (Magento-Bypass)¶

Für maximale Performance kann der PRG-Redirect ohne Magento-Bootstrap-Overhead verarbeitet werden. Fügen Sie folgende Konfiguration in Ihre Apache-Konfigurationsdatei ein:

<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-Konfiguration¶

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;
}

Mit diesen Webserver-Konfigurationen wird das PHP-Script prg.php direkt aufgerufen, ohne Magento zu starten. Dadurch wird die Antwortzeit für Redirects erheblich reduziert.

6 Fehlerbehandlung¶

Links werden nicht maskiert — Stellen Sie sicher, dass das Modul aktiviert ist. Überprüfen Sie, ob die Regel den richtigen Typ (Template/Name) und den korrekten Wert enthält. Der Template-Pfad muss exakt mit dem Magento-internen Template-Bezeichner übereinstimmen.
Alle Links werden blockiert (href="#") — Wenn nach dem Klick keine Weiterleitung erfolgt, prüfen Sie, ob JavaScript korrekt geladen wird und keine JS-Fehler in der Browser-Konsole vorliegen.
Seite nach dem Redirect stimmt nicht — Überprüfen Sie, ob der CSS-Selektor in der Konfiguration korrekt ist. Ein zu allgemeiner Selektor kann unbeabsichtigt Links maskieren.
ElasticSuite-Navigation funktioniert nicht mehr — Wenn das Modul Smile ElasticSuite-Navigation beeinflusst, überprüfen Sie, ob die Option ElasticSuite maskieren korrekt konfiguriert ist. Bei Problemen kann diese Option deaktiviert werden.
PRG-Route gibt 404 zurück — Stellen Sie sicher, dass das Modul korrekt installiert und der Cache geleert wurde. Überprüfen Sie, ob die Frontend-Routen korrekt registriert sind.
Redirect-Schleife — Dies kann auftreten, wenn Regeln so konfiguriert sind, dass sie Templates maskieren, die sich auf der PRG-Redirect-Seite selbst befinden. Schließen Sie solche Templates in der Ausschluss-Konfiguration aus.

Lizenz¶

Proprietär — CopeX GmbH. Eine Lizenz pro produktiver Magento-Instanz.