Link Remediator

Link Remediator

Link Remediator helps Drupal administrators find, review,
and safely remediate broken links and absolute internal links in site
content.

Rather than stopping at link detection, Link Remediator provides a
controlled remediation workflow. Administrators can review proposed
changes, perform dry runs, apply approved replacements through Drupal APIs,
and retain an audit trail that supports rollback.

Entity-backed content is updated through Drupal's Entity API instead of
direct database manipulation. A plugin API allows other contributed or
custom modules to integrate non-standard storage systems without adding
storage-specific code to Link Remediator itself.

Who is this module for?

Link Remediator is intended for site administrators, content managers,
developers, and maintainers responsible for Drupal sites with large amounts
of content or long-lived links.

It can be particularly useful when:

• A site has accumulated broken links after migrations, redesigns, content
  moves, or external website changes.
• Content contains absolute URLs pointing back to the same Drupal site and
  those URLs should be converted to portable internal paths.
• Administrators want to review proposed link changes before content is
  modified.
• Link remediation must preserve Drupal revisions and use normal entity
  storage APIs.
• A site contains custom or non-standard content storage that requires its
  own remediation integration.

Features

Broken link discovery

• Crawls rendered site pages and discovers links visible in rendered
  content.
• Detects broken links and records the pages where they were discovered.
• Supports administrator review before remediation is attempted.
• Re-checks links before changes are applied.

Reviewed remediation workflow

• Separates discovery from content modification.
• Allows administrators to approve or reject proposed replacements.
• Provides a dry-run mode before making changes.
• Applies approved replacements only to identified writable sources.
• Records remediation activity for later review.

Drupal Entity API updates

For standard Drupal content, Link Remediator uses Drupal's Entity API to
locate and update field values. It does not use generated SQL scripts or
direct database updates as a fallback remediation mechanism.

• Supports fieldable Drupal content entities.
• Supports formatted text fields containing URLs.
• Supports Drupal link fields.
• Preserves Drupal's normal entity save behavior.
• Creates revisions for revisionable entities where supported.

Absolute internal link remediation

Link Remediator can identify absolute URLs that point to the current Drupal
site and convert them into portable internal references.

For example:

https://www.example.com/about

can be normalized to:

/about

Drupal link-field values can be stored using Drupal-compatible internal URI
forms where appropriate.

This is useful when content moves between development, staging, and
production environments or when a site's canonical hostname changes.

Configurable internal hosts

Additional hostnames can be configured as aliases for the local Drupal
site. This allows environments such as production, staging, and development
domains to be treated as equivalent internal hosts without hard-coded
domain assumptions.

Audit history and rollback

• Records successful remediation operations.
• Records the source and replacement values involved in each change.
• Supports rollback of supported remediation operations.
• Plugin-backed changes are returned to the same remediator plugin that
  originally performed the write.
• Supports partial rollback when only part of a remediation operation can be
  safely reverted.

Unresolved and manual remediation

A link may appear in rendered output even when Link Remediator cannot map it
to a writable Drupal entity field.

Examples can include links generated by custom code, Views, external data,
custom renderers, or another storage system.

Link Remediator does not attempt unsafe database-level changes in these
cases. Instead, the occurrence is reported as unresolved/manual so a site
administrator can investigate it or provide an integration plugin.

CSV and JSON reporting

• Export discovered and reviewed remediation information.
• Supports CSV and JSON workflows.
• Preserves source identifiers required for plugin-backed remediation.
• Imported remediation data is still validated against the authoritative
  source before a write is performed.

Extensible locator and remediator Plugin API

Link Remediator includes an extension API for content that cannot be
remediated through the built-in Drupal Entity API workflow.

The API separates integrations into two plugin types:

Locator plugins

Read-only plugins that identify link-bearing locations in non-standard
storage.

Remediator plugins

Plugins responsible for dry-run, apply, and rollback operations for
locations owned by that integration.

This means integrations for systems such as external databases, specialized
scientific content stores, custom APIs, or other contributed modules can be
implemented separately without adding their storage logic to Link
Remediator core.

Plugin-backed remediation participates in the same review, audit, and
rollback workflow as standard Drupal entity remediation.

Safety model

Link Remediator is designed around reviewed content modification rather
than automatic database mutation.

• Discovery and remediation are separate operations.
• Administrators review proposed replacements before applying them.
• Dry-run support is available before content is changed.
• Standard Drupal content is saved through the Entity API.
• Direct SQL remediation is not used.
• Rendered links that cannot be mapped to writable storage are left for
  manual review.
• Specialized storage can only be modified by an explicitly installed
  remediator plugin responsible for that storage.

Typical workflow

1. Configure Link Remediator for the site.
2. Run a broken-link or absolute-link scan.
3. Review the discovered findings.
4. Choose or enter the desired replacement where applicable.
5. Approve the findings that should be remediated.
6. Run a dry run to preview the changes.
7. Apply the approved remediation.
8. Review the activity/audit history.
9. Rollback a supported change if necessary.

Requirements

• Drupal 10.2 or later, or Drupal 11.
• PHP and extensions required by the corresponding supported Drupal core release.

Link Remediator does not require an external SaaS link-checking service.

Installation

Install with Composer:

composer require drupal/link_remediator

Then enable the module:

drush en link_remediator

The module can also be enabled through Drupal's Extend
administration page.

Configuration and permissions

After installation, review the Link Remediator permissions before granting
access to administrative roles.

Because remediation can modify content, permissions to scan, review, apply,
and rollback remediation should only be granted to trusted users who are
authorized to manage site content.

It is strongly recommended to use dry-run and review workflows before
applying changes to production content.

Similar projects and how they are different

Link checker

Link checker is an established Drupal module focused on extracting links
from configured entity fields, periodically checking them, recording broken
links, and presenting broken-link reports. It also includes functionality
for handling some permanently moved links.

Link Remediator has a different primary focus: a reviewed
remediation workflow.

Link Remediator emphasizes:

• administrator approval before changes are made;
• dry-run previews;
• mapping discovered links back to exact writable sources;
• Drupal Entity API-based content updates;
• absolute internal URL normalization;
• change auditing and rollback;
• manual handling of discoveries that cannot be safely mapped;
• a locator/remediator Plugin API for integrating non-standard storage.

The projects may therefore be complementary depending on the site's
requirements: Link checker can provide ongoing link monitoring, while Link
Remediator focuses on controlled remediation and change management.

Analyze Broken Links

Analyze Broken Links is part of the Analyze ecosystem and focuses on
continuous content analysis, per-page link health scoring, automatic
rechecking, and site-wide reporting.

Link Remediator focuses instead on administrator-reviewed replacement of
link values, safe writes to content storage, auditing, rollback, and
extensible remediation providers.

Broken Link

Broken Link primarily tracks inbound 404 requests and allows administrators
to configure redirect patterns for those requests.

Link Remediator operates on links contained in or generated from Drupal
content and focuses on correcting the source content rather than creating
redirects for incoming requests.

Project status

The current release is an alpha release. It is intended for
testing and evaluation before API and workflow behavior are declared stable.

Because this module can modify stored content, administrators should test
remediation against a development or staging environment and maintain
appropriate backups before applying changes to production sites.

Testing and quality

Development uses the Drupal.org GitLab CI infrastructure and includes
automated checks for Drupal coding standards, static analysis, JavaScript
and CSS standards, spelling, and PHPUnit tests.

Contributions that improve automated test coverage for entity types,
translations, revision workflows, Content Moderation, and third-party
storage integrations are welcome.

Contributing

Bug reports, feature requests, documentation improvements, test coverage,
and integration plugins are welcome through the Drupal.org issue queue.

When reporting a remediation issue, please include:

• Drupal core version;
• Link Remediator version;
• entity type and field type involved, when applicable;
• whether the issue occurred during scan, dry run, apply, or rollback;
• the expected behavior;
• the observed behavior;
• relevant logs or reproducible steps without sensitive site data.

Maintainers and supporting organizations

Link Remediator is maintained as a reusable Drupal contributed project.

The project originated from link-management and remediation work developed
for a larger Drupal application environment and was subsequently
generalized to remove site-specific storage and business logic.

Storage-specific integrations should be implemented through the
locator/remediator Plugin API rather than incorporated into the generic
module.