README

Automatically link URLs and email addresses in a given block of text/HTML 🖇️

Framework-agnostic: pass an HTML fragment, get an HTML fragment back with plain urls and email addresses turned into links. Wire it into your CMS / framework yourself (e.g. a WordPress acf/format_value filter).

Requirements

• PHP 8.4+ (uses the new Dom\HTMLDocument API)

Installation

composer require hirasso/autolinker

Usage

Pass a string, get a string back:

use Hirasso\Autolinker\Autolinker;

echo Autolinker::link('Visit https://example.com or mail me@example.com');
// Visit <a href="https://example.com">example.com</a>
// or mail <a href="mailto:me@example.com">me@example.com</a>

Autolinker::link() accepts an HTML fragment (not a full document) or an existing Dom\HTMLDocument. Only text is linked — content inside existing links and inside head, script, style, svg, noscript, title, textarea, select, iframe, canvas, pre, code is left untouched, and no nested anchors are created.

What gets linked

• http:// and https:// urls
• Schemeless www. urls (the href is prefixed with https://)
• Email addresses (turned into mailto: links)

Trailing sentence punctuation stays out of the link:

echo Autolinker::link('See https://example.com.');
// See <a href="https://example.com">example.com</a>.

Options

Configure the output with named arguments:

use Dom\HTMLElement;
use Hirasso\Autolinker\Autolinker;

echo Autolinker::link(
    $html,
    urls: true,          // link urls (default: true)
    emails: true,        // link emails (default: true)
    stripScheme: true,   // strip the scheme from link texts (default: true)
    truncateText: 50,    // truncate link texts, ellipsis included; 0 disables (default: 50)
    postProcess: function (HTMLElement $a) {
        // called for each anchor this library creates
        $a->setAttribute('rel', 'noopener');
    },
);

stripScheme only affects the visible text, never the href:

echo Autolinker::link('https://example.com/path');
// <a href="https://example.com/path">example.com/path</a>

echo Autolinker::link('https://example.com/path', stripScheme: false);
// <a href="https://example.com/path">https://example.com/path</a>

Use postProcess to decorate the generated anchors — e.g. mark external links, add classes or target / rel attributes. It receives every anchor this library creates and never touches links that were already in your HTML.

Working with a Dom\HTMLDocument

If you already have a document, pass it directly. It is modified by reference and link() returns null:

use Dom\HTMLDocument;
use Hirasso\Autolinker\Autolinker;

$doc = HTMLDocument::createFromString($html, LIBXML_NOERROR);
Autolinker::link($doc); // $doc is now mutated in place

License

MIT © Rasso Hilber