linkhandler für TYPO3

linkhandler verhindert tote Links, wenn sich URLs ändern

In TYPO3 bezieht sich eine Typolink-Angabe direkt auf eine Seite, eine Datei oder eine URL - nicht auf einen Datensatz. Sobald eine Redaktion im Fliesstext auf Events, News-Artikel, Produkte oder Adressen verlinken will, muss sie entweder die URL hart eintragen oder eine Extension dazwischen schalten, die aus einer Record-ID eine stabile URL erzeugt. Genau das ist die Aufgabe von linkhandler. Die Extension von Cobwebsters registriert neue Link-Typen im TYPO3-RTE und im Link-Browser und verbindet sie mit beliebigen Datenbank-Tabellen. Bei einem Redaktionsprojekt mit mehr als hundert internen Querverweisen ist das der Unterschied zwischen einer funktionierenden Content-Architektur und einer Friedhof-Seite voller 404-Links.

Typische Einsatzszenarien treten bei jeder Redaktion mit mehr als einer Content-Domain auf

Sobald News, Events und Produkte im selben Projekt existieren, brauchen Redakteure ein sauberes Linking-System. Eine Hochschule verlinkt im Magazin-Artikel auf das Event in sf_event_mgt, im Event-Text auf den beteiligten Autor aus md_news_author und im Autor-Profil zurück auf alle seine Beiträge in GeorgRinger/news. Drei Extensions, drei Record-Typen, und ohne linkhandler wäre jede dieser Querverweise eine harte URL, die beim nächsten Slug-Refactoring bricht. Im Alltag heisst das: Ein einziges URL-Refactoring kann dann dutzende oder hunderte Broken Links erzeugen, die erst Wochen später im Google-Search-Console-Report auftauchen.

Ein zweites Szenario sind E-Commerce-Texte: Produktbeschreibungen, die auf Zubehör verweisen, oder Blog-Artikel, die auf Produkte aus aimeos verlinken. linkhandler erzeugt die URLs automatisch aus der Produkt-Routing-Konfiguration, und bei einem Kategorie-Refactoring wandern sämtliche Links mit.

Drittens tritt der Bedarf bei Standort-Listings auf. Wer eine Filialstruktur oder Ansprechpartner-Verzeichnisse mit tt_address oder einem eigenen Model pflegt, will aus Artikeln heraus auf die jeweilige Detailseite verlinken. Der linkhandler-Link bleibt stabil, selbst wenn der Standort umbenannt wird.

Technische Architektur registriert Linktypen per YAML und Handler-Klasse

linkhandler nutzt den TYPO3-LinkHandler-Mechanismus aus dem Core, der seit v8 verfügbar ist. Jeder Linktyp wird über eine YAML-Datei im Config-Verzeichnis registriert. Die YAML definiert den Handler-Bezeichner, die Tabelle, das Extbase-Modell und die Routing-Konfiguration. Im RTE und im Link-Browser erscheint der Linktyp als neuer Tab: “News”, “Event”, “Produkt”, “Adresse”. Jeder Tab zeigt eine Liste der verfügbaren Datensätze mit Such- und Filterfunktion, sodass Redakteure auch bei tausenden News-Einträgen gezielt den gewünschten Beitrag finden.

Der eigentliche Resolver ist eine PHP-Klasse, die von AbstractLinkHandler erbt und die Methoden modifyLinkField und generateRelativeUrl implementiert. Die Methoden erzeugen aus der Record-ID eine sprechende URL über die Site-Config und den Router der jeweiligen Extension. Im Frontend wird der Typolink mit dem Parameter t3://record aufgerufen und vom Page-Rendering in die finale URL aufgelöst. Das bedeutet: Selbst wenn zehntausende Artikel auf denselben News-Datensatz verlinken, muss bei einer Slug-Änderung nur der Artikel-Datensatz selbst aktualisiert werden - alle Links lösen sich automatisch auf die neue URL auf.

Die Konfiguration greift tief in das TYPO3-Linking-System ein, bleibt aber deklarativ: Nach der YAML-Registrierung und dem Cache-Clear steht der neue Linktyp im gesamten Projekt zur Verfügung, einschliesslich Fluid-Templates und Menü-Komponenten. Wer linkhandler nicht explizit nutzt, bekommt den Mechanismus über das TYPO3-Core-Linking ebenfalls, allerdings ohne die YAML-Abstraktionsschicht und das komfortable Backend-Picker-UI der Extension.

Häufige Probleme betreffen Cache, Sprachvarianten und Datei-Handler

Das häufigste Supportthema sind Cache-Inkonsistenzen nach dem Update eines Records. Wenn der Slug eines News-Artikels angepasst wird, muss der Page-Cache des Quell-Artikels, in dem der linkhandler-Link steht, ebenfalls geleert werden - sonst bleibt die alte URL in der Ausgabe stehen. Die Lösung ist ein Cache-Tag, das mit dem Typolink-Rendering gesetzt wird. Viele Installationen aktivieren das nicht und kämpfen dann mit vermeintlich defekten Links.

Das zweite Problem sind Sprachvarianten. Ein News-Artikel in DE verweist über linkhandler auf ein Event. Die englische Übersetzung des Artikels soll auf dieselbe Event-ID verweisen, aber die URL in der englischen Sprache erzeugen. linkhandler bietet diese Auflösung über den Language-Aspekt, aber die YAML-Konfiguration muss explizit auf die Routing-Varianten der Zielseiten zeigen. Wer Fallback-Sprachen verwendet, muss zusätzlich prüfen, wie sich der Handler bei fehlenden Übersetzungen verhält - er sollte in der Fallback-Sprache auflösen, nicht auf die Hauptsprache zurückfallen.

Drittens ist der Datei-Handler ein Sonderfall. Wer neben Record-Links auch auf TYPO3-FAL-Dateien verlinken will, muss den linkhandler-Datei-Handler separat konfigurieren oder auf den nativen TYPO3-File-Linker zurückgreifen. Die Kombination ist möglich, aber die Reihenfolge der Handler in der YAML entscheidet, welcher Tab zuerst erscheint.

TYPO3 v12 und v13 nutzen den Core-LinkHandler, Migration lohnt sich

Ab TYPO3 v11 ist der Core-LinkHandler produktionsreif und kann viele der Aufgaben von linkhandler selbst übernehmen. Trotzdem wird die Cobwebsters-Extension weiter gepflegt, weil sie zusätzliche Komfort-Features wie den YAML-Editor, den verbesserten Record-Picker und die Schema-freundliche Ausgabe mitbringt. Für TYPO3 v12 und v13 existiert eine aktuelle Version im TER und auf Packagist.

Beim Migrations-Review prüft Gosign, wie viele linkhandler-Aufrufe in den RTE-Inhalten stecken. Bei weniger als 50 Vorkommen lohnt sich oft der Umstieg auf den Core-LinkHandler, bei mehr als 100 Vorkommen oder stark individualisierten Handlern bleibt linkhandler die pragmatischere Wahl. Die Migration auf eine neue Major-Version läuft in der Regel ohne Inhalts-Änderungen, weil die t3://record-Syntax im Content stabil bleibt. Für die Analyse nutzen wir einen Scan über tt_content-Felder, der alle Links-Typen aufschlüsselt und eine Empfehlung pro Installation generiert.