asika / autolink
Auto convert url to link anchor.
Installs: 353 635
Dependents: 1
Suggesters: 0
Security: 0
Stars: 32
Watchers: 3
Forks: 10
Open Issues: 4
Requires
- php: >=8.0
Requires (Dev)
- phpunit/phpunit: ^9.0||^10.0||^11.0
- windwalker/test: ^4.0
- windwalker/utilities: ^4.0
README
A library to auto convert URLs to links.
Table of Content
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&foo[2]=b">http://example.com/?foo[1]=a&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:foo@example.com">foo@example.com</a>
Attributes Escaping
As htmlspecialchars()
in PHP 8.1 or higher will escape single quote as default,
Autolink will also escape single quote even in 8.0. Use this method to keep all escape
behavior same at any PHP versions:
$autolink->escape('...');
If you want to change the escape behavior, set your custom escape handler:
$autolink->setEscapeHandler(fn => ...);
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&yoo=baz" >http://www.google.com.tw?foo=bar&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); });