LinkFinder

Converts non-clickable URLs and email addresses in text (plain or HTML) into clickable HTML links

Generate Convert Improve

Install / Use

/learn @yarri/LinkFinder

About this skill

Quality Score

0/100

README

LinkFinder

LinkFinder detects URLs and email addresses in plain text or HTML and wraps them in <a> tags. In HTML documents it only linkifies text that is not already linked.

Installation
Basic usage
Processing HTML
Options reference
Callbacks
Custom templates
Testing
License

Installation

composer require yarri/link-finder

Basic usage

Pass plain text to process(). URLs and email addresses are detected automatically.

$lf = new LinkFinder();

echo $lf->process('Welcome at www.example.com!');
// Welcome at <a href="https://www.example.com">www.example.com</a>!

echo $lf->process('Contact us on info@example.com.');
// Contact us on <a href="mailto:info@example.com">info@example.com</a>.

HTML entities in the input are escaped by default, so plain text containing <, >, or & is safe to pass directly:

echo $lf->process('Find more at <http://www.ourstore.com/>');
// Find more at &lt;<a href="http://www.ourstore.com/">http://www.ourstore.com/</a>&gt;

Extra attributes can be set on the generated <a> elements via the attrs and mailto_attrs options:

$lf = new LinkFinder([
  "attrs" => [
    "class"  => "external-link",
    "target" => "_blank",
    "rel"    => "nofollow",
  ],
  "mailto_attrs" => [
    "class" => "external-email",
  ],
]);

echo $lf->process('Welcome at www.example.com! Contact us on info@example.com.');
// Welcome at <a class="external-link" href="https://www.example.com" rel="nofollow" target="_blank">www.example.com</a>!
// Contact us on <a class="external-email" href="mailto:info@example.com">info@example.com</a>.

Processing HTML

Use processHtml() when the input is an HTML document. LinkFinder will skip content inside existing <a>, <script>, <style>, <textarea>, and <head> tags, and will only linkify bare URLs and emails in the visible text.

$html = '
  <p>
    Visit <a href="http://www.ckrumlov.info/">Cesky Krumlov</a> or Prague.eu.
  </p>
';

$lf = new LinkFinder();
echo $lf->processHtml($html);

// <p>
//   Visit <a href="http://www.ckrumlov.info/">Cesky Krumlov</a> or <a href="https://Prague.eu">Prague.eu</a>.
// </p>

processHtml() is equivalent to calling process($html, ["escape_html_entities" => false]).

By default, URLs inside headline elements (<h1> through <h6>) are left alone. To linkify them as well:

echo $lf->processHtml($html, ["avoid_headlines" => false]);

// or permanently via the constructor:
$lf = new LinkFinder(["avoid_headlines" => false]);

Options reference

All options can be passed to the constructor or as the second argument of process() / processHtml(). Options passed to a method override the constructor defaults for that call only.

| Option | Type | Default | Description | |---|---|---|---| | attrs | array | [] | HTML attributes added to every link <a> element. | | mailto_attrs | array | [] | HTML attributes added to every mailto <a> element. | | escape_html_entities | bool | true | Escape <, >, &, " in the input before processing. Disable when the input is already HTML. | | avoid_headlines | bool | true | Skip linkification inside <h1>–<h6> elements when processing HTML. | | prefer_https | bool | true | Use https:// when no protocol is specified (e.g. www.example.com). Can also be set globally via the LINK_FINDER_PREFER_HTTPS constant before the class is loaded. | | secured_websites | array | [] | When prefer_https is false, list domains that should still get https://. Populated automatically from $_SERVER["HTTP_HOST"] when the current request is over HTTPS. | | shorten_long_urls | bool | true | Truncate the visible link text for long URLs. The href is never shortened. | | shortened_url_max_length | int | 65 | Maximum character length of the visible link text before truncation. | | href_callback | callable | identity | Transform the URL before it is written into the href attribute. See Callbacks. | | mailto_callback | callable | "mailto:$email" | Transform an email address before it is written into the href attribute. See Callbacks. | | link_template | string | <a %attrs%>%url%</a> | Template for link elements. See Custom templates. | | mailto_template | string | <a %attrs%>%address%</a> | Template for mailto elements. See Custom templates. | | utf8 | bool | true | Treat the input as UTF-8. |

prefer_https and secured_websites

When prefer_https is true (the default), all bare URLs get https://. When it is false, you can still mark specific domains as secured:

$lf = new LinkFinder([
  "prefer_https"     => false,
  "secured_websites" => ["example.com", "webmail.example.com"],
]);

echo $lf->process('Sign in at example.com/login/ or visit plain.org.');
// Sign in at <a href="https://example.com/login/">example.com/login/</a> or visit <a href="http://plain.org">plain.org</a>.

When prefer_https is false and secured_websites is not set, LinkFinder automatically adds the current $_SERVER["HTTP_HOST"] (and its www. variant) if the request is served over HTTPS.

Long URL shortening

The visible link text is truncated at 65 characters by default. The href always contains the full URL.

// Disable shortening
$lf = new LinkFinder(["shorten_long_urls" => false]);

// Change the limit
$lf = new LinkFinder(["shortened_url_max_length" => 50]);

Callbacks

href_callback

Runs on every detected URL just before it is written into the href attribute. Use it to route all external links through a redirect proxy, or to rewrite URLs in any other way.

$lf = new LinkFinder([
  "href_callback" => function ($url) {
    return "https://redirect.example.com/?url=" . urlencode($url);
  },
]);

echo $lf->process('www.atk14.net');
// <a href="https://redirect.example.com/?url=https%3A%2F%2Fwww.atk14.net">www.atk14.net</a>

The callback can also be set after construction:

$lf->setHrefCallback(function ($url) { /* … */ });

Default: function($url){ return $url; }

mailto_callback

Runs on every detected email address before it is written into the href attribute. Use it to point email links at a webmail compose page instead of a mailto: URI.

$lf = new LinkFinder([
  "mailto_callback" => function ($email) {
    return "/compose.php?to=" . urlencode($email);
  },
]);

echo $lf->process('info@example.com');
// <a href="/compose.php?to=info%40example.com">info@example.com</a>

The callback can also be set after construction:

$lf->setMailtoCallback(function ($email) { /* … */ });

Default: function($email){ return "mailto:$email"; }

Custom templates

The link_template and mailto_template options let you replace the entire <a> element with your own markup. The placeholder %attrs% is replaced with all rendered HTML attributes; %url% and %address% are replaced with the visible link text.

$lf = new LinkFinder([
  "link_template" => '<span class="link-wrapper"><a %attrs% data-external="1">%url%</a></span>',
]);

echo $lf->process('www.example.com');
// <span class="link-wrapper"><a href="https://www.example.com" data-external="1">www.example.com</a></span>

Testing

LinkFinder is tested automatically via GitHub Actions across PHP 5.6 to PHP 8.5.

Tests use the atk14/tester wrapper for phpunit/phpunit.

Install development dependencies:

composer update --dev

Run the test suite:

cd test
../vendor/bin/run_unit_tests

License

LinkFinder is free software distributed under the terms of the MIT license.

Related Skills

node-connect

351.4k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

110.7k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

351.4k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

qqbot-media

351.4k

QQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。