vstelmakh / url-highlight
Library to parse urls from string input
Installs: 490 746
Dependents: 6
Suggesters: 0
Security: 0
Stars: 94
Watchers: 5
Forks: 0
Open Issues: 0
Requires
- php: ^7.1 || ^8
- ext-json: *
- ext-mbstring: *
- symfony/polyfill-php72: ^1.10
Requires (Dev)
- phpbench/phpbench: ^0.16 || ^1.2.6
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^7.5.3 || ^8 || ^9.3
- squizlabs/php_codesniffer: ^3.7.1
- vstelmakh/covelyzer: ^0.2
README
Url highlight - PHP library to parse URLs from string input. Works with complex URLs, edge cases and encoded input.
Features:
- Replace URLs in string by HTML tags (make clickable)
- Match URLs without scheme by top-level domain
- Work with HTML entities encoded input
- Extract URLs from string
- Check if string is URL
Installation
Install the latest version with Composer:
composer require vstelmakh/url-highlight
Also, there are Twig extension and Symfony bundle available.
Quick start
<?php require __DIR__ . '/vendor/autoload.php'; use VStelmakh\UrlHighlight\UrlHighlight; $urlHighlight = new UrlHighlight(); echo $urlHighlight->highlightUrls('Hello, http://example.com.'); // Output: // Hello, <a href="http://example.com">http://example.com</a>.
💡 Tip: For customizing highlight see Highlighter. To properly handle HTML entity escaped string see Encoder.
Usage
Check if string is URL
<?php $urlHighlight->isUrl('http://example.com'); // return: true $urlHighlight->isUrl('Other string'); // return: false
Parse URLs from string
<?php $urlHighlight->getUrls('Hello, http://example.com.'); // return: ['http://example.com']
Replace URLs by HTML tags (make clickable)
<?php $urlHighlight->highlightUrls('Hello, http://example.com.'); // return: 'Hello, <a href="http://example.com">http://example.com</a>.'
Configuration
There are 3 parts which could be configured according to your needs:
- Validator - define if match is valid and should be recognized as URL (e.g. allow/disallow specific schemes)
- Highlighter - define the way how URL should be highlighted (e.g. replaced by html
<a>
tag) - Encoder - define how to work with encoded input (e.g. html special chars)
Configuration provided via constructor implementing corresponding interface instance.
Use null
to keep default:
<?php use VStelmakh\UrlHighlight\Encoder\HtmlSpecialcharsEncoder; use VStelmakh\UrlHighlight\UrlHighlight; use VStelmakh\UrlHighlight\Validator\Validator; $validator = new Validator(); $encoder = new HtmlSpecialcharsEncoder(); $urlHighlight = new UrlHighlight($validator, null, $encoder);
Validator
There is one validator bundled with the library. Which is used by default with settings listed in example below.
🛠️ Validator usage example
<?php use VStelmakh\UrlHighlight\UrlHighlight; use VStelmakh\UrlHighlight\Validator\Validator; $validator = new Validator( true, // bool - if should use top level domain to match urls without scheme [], // string[] - array of blacklisted schemes [], // string[] - array of whitelisted schemes true // bool - if should match emails (if match by TLD set to "false" - will match only "mailto" urls) ); $urlHighlight = new UrlHighlight($validator);
💡 Tip: If you need custom behavior - create and use your own validator implementing ValidatorInterface.
Highlighter
There are 2 highlighters bundled with the library:
-
HtmlHighlighter - convert matches to html tags.
Example:http://example.com
→<a href="http://example.com">http://example.com</a>
-
MarkdownHighlighter - convert matches to markdown format.
Example:http://example.com
→[http://example.com](http://example.com)
By default, HtmlHighlighter
is used, with settings listed in example below.
🛠️ Highlighter usage example
<?php use VStelmakh\UrlHighlight\Highlighter\HtmlHighlighter; use VStelmakh\UrlHighlight\UrlHighlight; $highlighter = new HtmlHighlighter( 'http', // string - scheme to use for urls matched by top level domain [], // string[] - key/value map of tag attributes, e.g. ['rel' => 'nofollow', 'class' => 'light'] '', // string - content to add before highlight: {here}<a... '' // string - content to add after highlight: ...</a>{here} ); $urlHighlight = new UrlHighlight(null, $highlighter);
💡 Tip: If you need custom behavior - extend HtmlHighlighter or implement HighlighterInterface.
For more details and examples see 🖍️ Custom highlighter.
Encoder
Encoder should be used to handle encoded input properly. For example HTML escaped string could contain something
like: http://example.com?a=1"
or http://example.com?a=1&b=2
which will be wrongly matched as URL.
By default, there is no encoder used. There are 2 encoders bundled with library:
- HtmlEntitiesEncoder - to work with HTML entities encoded string (any character expected to be HTML entity encoded)
- HtmlSpecialcharsEncoder - to work with HTML escaped string (only
&
"
'
<
>
expected to be encoded)
🛠️ Encoder usage example
<?php use VStelmakh\UrlHighlight\Encoder\HtmlSpecialcharsEncoder; use VStelmakh\UrlHighlight\UrlHighlight; $encoder = new HtmlSpecialcharsEncoder(); $urlHighlight = new UrlHighlight(null, null, $encoder); $urlHighlight->highlightUrls('<a href="http://example.com">Example</a>'); // return: '<a href="<a href="http://example.com">http://example.com</a>">Example</a>'
💡 Tip: For custom behavior - create and use your own encoder implementing EncoderInterface.
Keep in mind - using encoder require more regex operations and could have performance impact. Better to not use encoder if you don't expect encoded string.
Credits
Volodymyr Stelmakh
Licensed under the MIT License. See LICENSE for more information.