linkhandler for TYPO3

linkhandler prevents dead links when URLs change

In TYPO3, a typolink reference points directly at a page, a file or a URL, not at a record. As soon as an editorial team wants to link from running text to events, news articles, products or addresses, they either have to type in the URL by hand or wire an extension between them that turns a record ID into a stable URL. That is exactly what linkhandler does. The extension from Cobwebsters registers new link types in the TYPO3 RTE and in the link browser and connects them to arbitrary database tables. On an editorial project with more than a hundred internal cross-references, that is the difference between a working content architecture and a graveyard page full of 404 links.

Typical use cases appear in every editorial setup with more than one content domain

As soon as news, events and products coexist in the same project, editors need a clean linking system. A university links from the magazine article to the event in sf_event_mgt, from the event text to the contributing author from md_news_author and from the author profile back to all their contributions in GeorgRinger/news. Three extensions, three record types, and without linkhandler each of these cross references would be a hard URL that breaks on the next slug refactor. In day-to-day operations that means: a single URL refactor can produce dozens or hundreds of broken links that only show up in the Google Search Console report weeks later.

A second scenario are e-commerce texts: product descriptions that point to accessories, or blog articles that link to products from aimeos. linkhandler generates the URLs automatically from the product routing configuration, and on a category refactor all the links move along.

Thirdly, the need appears on location listings. Anyone maintaining a branch structure or contact directories with tt_address or a custom model wants to link from articles to the respective detail page. The linkhandler link remains stable even if the location is renamed.

Technical architecture registers link types via YAML and handler class

linkhandler uses the TYPO3 core LinkHandler mechanism that has been available since v8. Every link type is registered through a YAML file in the config directory. The YAML defines the handler identifier, the table, the Extbase model and the routing configuration. In the RTE and in the link browser, the link type appears as a new tab: “News”, “Event”, “Product”, “Address”. Each tab shows a list of the available records with search and filter functionality, so that editors can find the desired entry even with thousands of news records.

The actual resolver is a PHP class that inherits from AbstractLinkHandler and implements the methods modifyLinkField and generateRelativeUrl. These methods turn the record ID into a speaking URL via the site config and the router of the respective extension. In the frontend, the typolink is called with the parameter t3://record and resolved by the page rendering into the final URL. That means: even if tens of thousands of articles link to the same news record, only the article record itself has to be updated on a slug change, and all links automatically resolve to the new URL.

The configuration reaches deep into the TYPO3 linking system but stays declarative: after the YAML registration and a cache clear, the new link type is available across the entire project, including Fluid templates and menu components. Anyone who does not use linkhandler explicitly still gets the mechanism via TYPO3 core linking, but without the YAML abstraction layer and the comfortable backend picker UI that the extension provides.

Common problems involve cache, language variants and file handlers

The most common support topic is cache inconsistency after updating a record. When the slug of a news article is adjusted, the page cache of the source article that holds the linkhandler link has to be cleared as well, otherwise the old URL stays in the output. The solution is a cache tag that is set along with the typolink rendering. Many installations do not enable this and then fight with apparently broken links.

The second problem is language variants. A news article in DE links via linkhandler to an event. The English translation of the article should point to the same event ID but generate the URL in the English language. linkhandler offers this resolution via the language aspect, but the YAML configuration has to explicitly point at the routing variants of the target pages. Anyone using fallback languages additionally has to check how the handler behaves when translations are missing: it should resolve in the fallback language and not drop back to the main language.

Thirdly, the file handler is a special case. Anyone who wants to link not only to records but also to TYPO3 FAL files has to configure the linkhandler file handler separately or rely on the native TYPO3 file linker. The combination is possible, but the order of the handlers in the YAML decides which tab appears first.

TYPO3 v12 and v13 use the core LinkHandler, migration pays off

From TYPO3 v11 onwards, the core LinkHandler is production-ready and can handle many of the jobs that linkhandler covers on its own. Nevertheless, the Cobwebsters extension is still maintained because it ships additional comfort features such as the YAML editor, the improved record picker and schema-friendly output. A current version for TYPO3 v12 and v13 exists in the TER and on Packagist.

During a migration review, Gosign checks how many linkhandler calls sit inside the RTE content. With fewer than 50 occurrences it often pays off to switch to the core LinkHandler, with more than 100 occurrences or with heavily customised handlers linkhandler remains the more pragmatic choice. The migration to a new major version usually runs without content changes, because the t3://record syntax in the content remains stable. For the analysis, we run a scan over tt_content fields that breaks down all link types and generates a recommendation per installation.