About this document

The LinkValidator is provided by a system extension named linkvalidator which enables you to conveniently check your website for broken links.

This manual explains how to install and configure the extension for your needs.

What does it do?

The LinkValidator checks the links in your website for validity, reports broken links or missing files in your TYPO3 installation and provides a way to conveniently fix these problems.

It includes the following features:

• The LinkValidator can check all kinds of links. This includes internal links to pages and content elements, file links to files in the local file system and external links to resources somewhere else in the web.
• The LinkValidator checks a number of fields by default, for example header and bodytext fields of content elements. It can be configured to check any field you like.
• The LinkValidator offers a just in time check of your website. Additionally the TYPO3 Scheduler is fully supported to run checks automatically. In this case you can choose, if you want to receive an email report, if broken links were found.
• The LinkValidator is extendable. It provides hooks to check special types of links or override how the checking of external, file and page links works.

Screenshots

This is the Check Links backend module. It provides two actions: Report and Check Links. The Report action is always shown first. Here you can view the broken links which were found, when your website was last checked.

The Check Links tab is used to check links on demand and can be hidden with TSconfig, if desired.

The workflow in the module is the following:

• First you set the depth of pages you want to consider when checking for broken links in the Check Links tab. Then click the Check Links button.
• Once the checks are done, the module automatically switches to the Report tab where the results are displayed.
• The type and ID of the content containing the broken link become visible when you move the mouse over the icon for the content type. The pencil icons at the beginning of each row enable you to quickly fix the displayed elements.

The LinkValidator features full support of the TYPO3 Scheduler. This is the LinkValidator task:

• With this task you can run LinkValidator regularly via cron without having to manually update the stored information on broken links.
• You can for example overwrite the TSconfig configuration. Without any change, the LinkValidator settings which apply for the respective pages will be used. If you set values there, the former will be overwritten.
• The LinkValidator task can send you a status report via email. You can create your own email template as needed.

Credits

This extension is particularly based on the extension cag_linkchecker, which was originally developed for Connecta AG, Wiesbaden. cag_linkchecker is maintained by Jochen Rieger and Dimitri König.

Feedback

If you find a bug in this manual or in the extension in general, please file an issue in the TYPO3 bug tracker.

LinkValidator Report

1. Access the module Check Links.
2. Select the page you want to work on in the page tree

You will now see the Report with the list of broken links. In order to get results, select the checkboxes ("Internal Links", etc.) and choose the appropriate depth under Show this level. This will determine the page level, for example for depth This page, LinkValidator will only show broken links for the page that is currently selected in the page tree. The deeper you go, the more broken links may possibly be shown. After you change the settings, you must click Refresh display.

When you jump to a different page in the page tree, the Report will be refreshed.

Listing of broken links

The list shows the following, from left to right:

1. Element: The title of the field which contains the broken link
2. Path: The title of the page and its parents
3. Link: The anchor text of the link
4. URL / Link target: The link target, where the link points to.
5. Error message: Information about the error. Often, this will be a 404 error, which means the link target simply does not exist.
6. Last check: When the broken link was detected
7. The pencil icon can be used to edit the field where the broken link exists.

You can now fix the broken links one after another, by clicking on the pencil icon.

The corresponding form will open. The broken link will be marked in a special style to make it visually stand out.

You can now double-click on it to open the Link Browser and fix the link. When you are done, click on save and close in order to return to the Report.

Installation with Composer

Check whether you are already using the extension with:

composer show | grep linkvalidator

This should either give you no result or something similar to:

typo3/cms-linkvalidator       v12.4.11

If it is not installed yet, use the composer require command to install the extension:

composer require typo3/cms-linkvalidator

The given version depends on the version of the TYPO3 Core you are using.

Classic installation without Composer

In an installation without Composer, the extension is already shipped but might not be activated yet. Activate it as follows:

1. In the backend, navigate to the Admin Tools > Extensions module.
2. Click the Activate icon for the LinkValidator extension.

Next step

LinkValidator uses the HTTP request library shipped with TYPO3. Please have a look in the Global Configuration, particularly at the HTTP settings.

There, you may define a default timeout. Generally, it is recommended to always specify timeouts when working with the LinkValidator.

Minimal configuration

It is recommended to at least fill out httpAgentUrl and httpAgentEmail. The latter is only required if $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress'] is not set.

mod.linkvalidator.linktypesConfig.external.httpAgentUrl =
mod.linkvalidator.linktypesConfig.external.httpAgentEmail =

Reference

You can set the following options in the TSconfig for a page (for example the root page) and override them in user or groups TSconfig. You must prefix them with mod.linkvalidator, for example mod.linkvalidator.searchFields.pages = canonical_link.

Example

mod.linkvalidator {
        searchFields {
                pages = url,canonical_link
                tt_content = bodytext,header_link,records
        }
        linktypes = db,file,external
        checkhidden = 0
        mail {
                fromname = TYPO3 LinkValidator
                fromemail = no_reply@mydomain.com
                replytoname =
                replytoemail =
                subject = TYPO3 LinkValidator report
        }
        external {
                httpAgentUrl = https://example.com/info.html
                httpAgentEmail = info@example.com
        }
}

Example

<?php

/*
 * This file is part of the TYPO3 CMS project. [...]
 */

namespace T3docs\Examples\LinkValidator\LinkType;

use TYPO3\CMS\Linkvalidator\Linktype\AbstractLinktype;

/**
 * This class provides Check Example Links plugin implementation
 */
class ExampleLinkType extends AbstractLinktype
{
    protected string $identifier = 'example';

    public function checkLink($url, $softRefEntry, $reference)
    {
        $isValidUrl = false;
        // TODO: Implement checkLink() method.
        return $isValidUrl;
    }

    public function getErrorMessage($errorParams)
    {
        $lang = $this->getLanguageService();
        return match ($errorParams['errno'] ?? 0) {
            404 => $lang->getLL('list.report.pagenotfound404'),
            // fall back to generic error message
            default => sprintf($lang->getLL('list.report.externalerror'), $errorParams['errno']),
        };
    }
}

mod.linkvalidator {
   # specify link types to be crawled
   linktypes = db,file,external,example
}

services:
  _defaults:
    autoconfigure: true

services:
  MyVendor\MyExtension\LinkValidator\LinkType\ExampleLinkType:
    tags:
      -  name: linkvalidator.linktype

<?php

namespace MyVendor\NyExtension\Linktype\ExternalLinktype;

use TYPO3\CMS\Linkvalidator\LinkAnalyzer;
use TYPO3\CMS\Linkvalidator\Linktype\ExternalLinktype as LinkvalidatorExternalLinkType;

// This class inherits from ExternalLinktype,
// so it is only necessary to override some methods.
class ExternalLinktype extends LinkvalidatorExternalLinkType
{
    // This class must use a different identifier because "external" is already used.
    protected string $identifier = 'custom_external';

    public function checkLink(
        string $origUrl,
        array $softRefEntry,
        LinkAnalyzer $reference
    ): bool {
        // do additional stuff here or after parent::checkLink
        // ...
        return parent::checkLink($origUrl, $softRefEntry, $reference);
    }

    public function fetchType(array $value, string $type, string $key): string
    {
        preg_match_all(
            '/((?:http|https))(?::\\/\\/)(?:[^\\s<>]+)/i',
            (string)$value['tokenValue'],
            $urls,
            PREG_PATTERN_ORDER
        );
        if (!empty($urls[0][0])) {
            $type = $this->getIdentifier();
        }
        return $type;
    }
}

mod.linkvalidator.linktypes = db,file,custom_external

mod.linkvalidator.linktypesConfig.custom_external < mod.linkvalidator.linktypesConfig.external

Migration from TYPO3 11 LTS and below

Remove $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['linkvalidator']['checkLinks'] from your ext_localconf.php file.

If autoconfigure is not enabled in your Configuration/Services.(yaml|php), add the tag linkvalidator.linktype manually to your linktype service.

Additionally, make sure to either implement public function getIdentifier(): string or, in case your linktype extends AbstractLinktype, to set the $identifier class property.

Problems with external links

The most relevant known problems currently concern "external broken links".

Be polite when crawling external sites: They should not be checked too often. The extension currently provides no functionality to limit such requests.

There are (at least) 2 possible counter-measures:

1. Turn off external link checking entirely by removing external from Page TSconfig linktypes
2. Override the ExternalLinktype class (in your own extension), to check only specific URLs or exclude specific URLs or handle only specific error types as errors.

Falsely reported broken links

Linkvalidator may find false negatives when checking links. This can be annoying for editors since there is no way to declare them "ok" manually, they will be shown to editors over and over again.

There are a couple of scenarios where linkvalidator may show a link as broken leading to a misleading result:

• Automatic server-side external link checking may fail. There are many possible reasons for false negatives in this area like server connectivity issues or funny deny rules on the target system.
• Sometimes links may not be broken as such, but are considered "broken" due to HTTP status like 4xx.
• The broken link information may be "stale", the link has been checked a while ago and did lead to a negative result due to temporary a system outage or similar, is now working again, but has not been rechecked yet.