asika/autolink

Auto convert url to link anchor.

2.0.3 2024-01-13 06:17 UTC

Requires

• php: >=8.0

Requires (Dev)

• phpunit/phpunit: ^8.0||^9.0||^10.0
• windwalker/test: ^4.0
• windwalker/utilities: ^4.0

MIT

• Simon Asika

• link
• autolink
• Linkify

README

A library to auto convert URLs to links.

Table of Content

• Installation via Composer
• Getting Started
• Use Autolink Object
• Convert Text
• Convert Email
• Options
• Scheme
• Link Builder

Requirement

• Version 2.x require PHP 8.0 or higher.
• Version 1.x supports PHP 5.3 to 7.4

Installation via Composer

Add this to composer.json require block.

{
    "require": {
        "asika/autolink": "^2.0"
    }
}

Getting Started

This is a quick start to convert URL to link:

use Asika\Autolink\AutolinkStatic;

$text = AutolinkStatic::convert($text);
$text = AutolinkStatic::convertEmail($text);

Use Autolink Object

Create the object:

use Asika\Autolink\Autolink;

$autolink = new Autolink();

Create with options.

$options = [
    'strip_scheme' => false,
    'text_limit' => false,
    'auto_title' => false,
    'escape' => true,
    'link_no_scheme' => false
];

$schemes = ['http', 'https', 'skype', 'itunes'];

$autolink = new Autolink($options, $schemes);

Convert Text

This is an example text:

This is Simple URL:
http://www.google.com.tw

This is SSL URL:
https://www.google.com.tw

This is URL with multi-level query:
http://example.com/?foo[1]=a&foo[2]=b

We convert all URLs.

$text = $autolink->convert($text);

Output:

This is Simple URL:
<a href="http://www.google.com.tw">http://www.google.com.tw</a>

This is SSL URL:
<a href="https://www.google.com.tw">https://www.google.com.tw</a>

This is URL with multi-level query:
<a href="http://example.com/?foo[1]=a&amp;foo[2]=b">http://example.com/?foo[1]=a&amp;foo[2]=b</a>

Add Attributes

$text = $autolink->convert($text, ['class' => 'center']);

All link will add this attributes:

This is Simple URL:
<a href="http://www.google.com.tw" class="center">http://www.google.com.tw</a>

This is SSL URL:
<a href="https://www.google.com.tw" class="center">https://www.google.com.tw</a>

Convert Email

Email url has no scheme, we use anoter method to convert them, and it will add mailto: at begin of href.

$text = $aurolink->convertEmail($text);

Output

<a href="mailto:[e-mail]">[e-mail]</a>

Options

text_limit

We can set this option by constructor or setter:

$auitolink->textLimit(50);

$text = $autolink->convert($text);

The link text will be:

http://campus.asukademy.com/learning/job/84-fin...

Use Your own limit handler by set a callback:

$auitolink->textLimit(function($url) {
    return substr($url, 0, 50) . '...';
});

Or use \Asika\Autolink\LinkHelper::shorten() Pretty handler:

$auitolink->textLimit(function($url) {
    return \Asika\Autolink\Autolink::shortenUrl($url, 15, 6);
});

Output:

http://campus.asukademy.com/....../84-find-interns......

auto_title

Use AutoTitle to force add title on anchor element.

$autolink->autoTitle(true);

$text = $autolink->convert($text);

Output:

<a href="http://www.google.com.tw" title="http://www.google.com.tw">http://www.google.com.tw</a>

strip_scheme

Strip Scheme on link text:

$auitolink->stripScheme(true);

$text = $autolink->convert($text);

Output

<a href="http://www.google.com.tw" >www.google.com.tw</a>

escape

Auto escape URL, default is true:

$auitolink->autoEscape(false);

$text = $autolink->convert($text);

$auitolink->autoEscape(true);

$text = $autolink->convert($text);

Output

<a href="http://www.google.com.tw?foo=bar&yoo=baz" >http://www.google.com.tw?foo=bar&yoo=baz</a>
<a href="http://www.google.com.tw?foo=bar&amp;yoo=baz" >http://www.google.com.tw?foo=bar&amp;yoo=baz</a>

link_no_scheme

Convert URL which no scheme. If you pass TRUE to this option, Autolink will use http as default scheme, you can also provide your own default scheme.

$auitolink->linkNoScheme('https');

$text = $autolink->convert('www.google.com.tw');

Output

<a href="https://www.google.com.tw" >www.google.com.tw</a>

Scheme

You can add new scheme to convert URL begin with it, for example: vnc://example.com

$autolink->addScheme('skype', 'vnc');

Default schemes is http, https, ftp, ftps.

Link Builder

If you don't want to use <a> element as your link, you can set a callback to build link HTML.

$autolink->setLinkBuilder(function(string $url, array $attribs) {
    $attribs['src'] = htmlspecialchars($url);

    return \Asika\Autolink\HtmlBuilder::create('img', $attribs, null);
});