PHPackages                             yarri/link-finder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. yarri/link-finder

ActiveLibrary[Mail & Notifications](/categories/mail)

yarri/link-finder
=================

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

v2.8.2(1mo ago)18148.6k—3.9%21MITPHPPHP >=5.6.0CI passing

Since Mar 13Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/yarri/LinkFinder)[ Packagist](https://packagist.org/packages/yarri/link-finder)[ Docs](https://github.com/yarri/LinkFinder)[ RSS](/packages/yarri-link-finder/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (2)Versions (31)Used By (1)

LinkFinder
==========

[](#linkfinder)

[![Tests](https://github.com/yarri/LinkFinder/actions/workflows/tests.yml/badge.svg)](https://github.com/yarri/LinkFinder/actions/workflows/tests.yml)[![Downloads](https://camo.githubusercontent.com/2310533a67acf307158f2d7b7969fcb3b285f76186e077729faf3bb13754240e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f79617272692f6c696e6b2d66696e6465722e737667)](https://packagist.org/packages/yarri/link-finder)[![Codacy Badge](https://camo.githubusercontent.com/e4b9a778783c5b4121c015bd937dc5dea7ed3053ec101a774b393017af99dad5/68747470733a2f2f6170702e636f646163792e636f6d2f70726f6a6563742f62616467652f47726164652f3633623435366434316237633432333262336639366665346235646138626537)](https://app.codacy.com/gh/yarri/LinkFinder/dashboard)

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

- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Processing HTML](#processing-html)
- [Options reference](#options-reference)
- [Callbacks](#callbacks)
- [Custom templates](#custom-templates)
- [Testing](#testing)

Installation
------------

[](#installation)

```
composer require yarri/link-finder
```

Basic usage
-----------

[](#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 www.example.com!

echo $lf->process('Contact us on info@example.com.');
// Contact us on info@example.com.
```

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 ');
// Find more at <http://www.ourstore.com/>
```

Extra attributes can be set on the generated `` 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 www.example.com!
// Contact us on info@example.com.
```

Processing HTML
---------------

[](#processing-html)

Use `processHtml()` when the input is an HTML document. LinkFinder will skip content inside existing ``, ``, ``, ``, and `` tags, and will only linkify bare URLs and emails in the visible text.

```
$html = '

    Visit Cesky Krumlov or Prague.eu.

';

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

//
//   Visit Cesky Krumlov or Prague.eu.
//
```

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

By default, URLs inside headline elements (`` through ``) 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
-----------------

[](#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.

OptionTypeDefaultDescription`attrs`array`[]`HTML attributes added to every link `` element.`mailto_attrs`array`[]`HTML attributes added to every mailto `` 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 ``–`` 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`callableidentityTransform the URL before it is written into the `href` attribute. See [Callbacks](#callbacks).`mailto_callback`callable`"mailto:$email"`Transform an email address before it is written into the `href` attribute. See [Callbacks](#callbacks).`link_template`string`%url%`Template for link elements. See [Custom templates](#custom-templates).`mailto_template`string`%address%`Template for mailto elements. See [Custom templates](#custom-templates).`utf8`bool`true`Treat the input as UTF-8.### prefer\_https and secured\_websites

[](#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 example.com/login/ or visit plain.org.
```

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

[](#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
---------

[](#callbacks)

### href\_callback

[](#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');
// www.atk14.net
```

The callback can also be set after construction:

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

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

### mailto\_callback

[](#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');
// info@example.com
```

The callback can also be set after construction:

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

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

Custom templates
----------------

[](#custom-templates)

The `link_template` and `mailto_template` options let you replace the entire `` 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" => '%url%',
]);

echo $lf->process('www.example.com');
// www.example.com
```

Testing
-------

[](#testing)

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

Tests use the [atk14/tester](https://packagist.org/packages/atk14/tester) wrapper for [phpunit/phpunit](https://packagist.org/packages/phpunit/phpunit).

Install development dependencies:

```
composer update --dev
```

Run the test suite:

```
cd test
../vendor/bin/run_unit_tests
```

License
-------

[](#license)

LinkFinder is free software distributed [under the terms of the MIT license](http://www.opensource.org/licenses/mit-license).

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance89

Actively maintained with recent releases

Popularity41

Moderate usage in the ecosystem

Community14

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 99.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~126 days

Recently: every ~210 days

Total

30

Last Release

55d ago

Major Versions

v1.0 → v2.02016-03-15

PHP version history (3 changes)v1.0PHP >=5.0.0

v2.4.1PHP >=5.3.0

v2.7.8PHP >=5.6.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6304dffbd91d7a978f98632b0e4e30d662dcdb691daadb1388a58984e98faf5c?d=identicon)[yarri](/maintainers/yarri)

---

Top Contributors

[![yarri](https://avatars.githubusercontent.com/u/974278?v=4)](https://github.com/yarri "yarri (214 commits)")[![mgralikowski](https://avatars.githubusercontent.com/u/17027876?v=4)](https://github.com/mgralikowski "mgralikowski (1 commits)")[![yoeriboven](https://avatars.githubusercontent.com/u/4047804?v=4)](https://github.com/yoeriboven "yoeriboven (1 commits)")

---

Tags

urllinkemaile-mailLinkifyurlizeurlizer

### Embed Badge

![Health badge](/badges/yarri-link-finder/health.svg)

```
[![Health](https://phpackages.com/badges/yarri-link-finder/health.svg)](https://phpackages.com/packages/yarri-link-finder)
```

###  Alternatives

[egulias/email-validator

A library for validating emails against several RFCs

11.6k691.3M307](/packages/egulias-email-validator)[sendgrid/sendgrid

This library allows you to quickly and easily send emails through Twilio SendGrid using PHP.

1.5k47.5M164](/packages/sendgrid-sendgrid)[pelago/emogrifier

Converts CSS styles into inline style attributes in your HTML code

94944.1M110](/packages/pelago-emogrifier)[zbateson/mail-mime-parser

MIME email message parser

54149.2M79](/packages/zbateson-mail-mime-parser)[soundasleep/html2text

A PHP script to convert HTML into a plain text format

48519.5M75](/packages/soundasleep-html2text)[opcodesio/mail-parser

Parse emails without the mailparse extension

226.8M8](/packages/opcodesio-mail-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)