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 set up a record link handler that turns a record ID into a stable URL. That is exactly what linkhandler does, and since TYPO3 8.6 the core can do it as well. The extension, originally by AOE and last maintained by Cobweb, 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 TSconfig and handler class

linkhandler uses the core LinkBrowser API, which has existed since TYPO3 7.6; since 8.6, the core also ships the record link handler itself. Every link type is registered in Page TSconfig under TCEMAIN.linkHandler, with handler class, table and tab label; TypoScript defines how the link is built in the frontend. 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 tab in the link browser is provided by a PHP class that inherits from AbstractLinkHandler; in the frontend, a typolink handler builds the link. It turns the record ID into a link to the detail page via the typolink configuration in TypoScript, and routing provides the speaking URL. 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 registration in TSconfig and TypoScript 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 since 8.6, including its own tab in the link browser.

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 to also clear the cache of the linking pages when the record is saved, for example via TCEMAIN.clearCacheCmd in Page TSconfig. Many installations do not set this up 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. The typolink rendering handles this resolution, but the TypoScript 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 uses the core file handler for that; linkhandler itself does not ship one. The combination is possible; displayBefore and displayAfter in Page TSconfig decide which tab appears first.

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

Since TYPO3 8.6, the functionality of linkhandler has been part of the core LinkHandler. The extension itself is no longer maintained: the last version by Cobweb, 3.1.3 from 2016, runs only on TYPO3 7.6. There is no version for TYPO3 v12 and v13; the TER only lists the outdated AOE version 0.3.1.

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 a script that rewrites the links into the core format t3://record helps. 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.