---
[](https://github.com/vstelmakh/url-highlight/actions)
[](https://packagist.org/packages/vstelmakh/url-highlight)
[](https://www.php.net/)
[](LICENSE)
**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
[🚀 **See examples** 👀](./docs/examples.md)
## Installation
Install the latest version with [Composer](https://getcomposer.org/):
```bash
composer require vstelmakh/url-highlight
```
Also, there are
[
Twig extension](https://github.com/vstelmakh/url-highlight-twig-extension)
and [
Symfony bundle](https://github.com/vstelmakh/url-highlight-symfony-bundle) available.
## Quick start
```php
highlightUrls('Hello, http://example.com.');
// Output:
// Hello, http://example.com.
```
> 💡 **Tip**: For customizing highlight see [Highlighter](#highlighter).
> To properly handle HTML entity escaped string see [Encoder](#encoder).
## Usage
#### Check if string is URL
```php
isUrl('http://example.com'); // return: true
$urlHighlight->isUrl('Other string'); // return: false
```
#### Parse URLs from string
```php
getUrls('Hello, http://example.com.');
// return: ['http://example.com']
```
#### Replace URLs by HTML tags (make clickable)
```php
highlightUrls('Hello, http://example.com.');
// return: 'Hello, http://example.com.'
```
## Configuration
There are 3 parts which could be configured according to your needs:
- [Validator](#validator) - define if match is valid and should be recognized as URL (e.g. allow/disallow specific schemes)
- [Highlighter](#highlighter) - define the way how URL should be highlighted (e.g. replaced by html `` tag)
- [Encoder](#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
🛠️ Validator usage example
```php
> 💡 **Tip**: If you need custom behavior - create and use your own validator implementing [ValidatorInterface](./src/Validator/ValidatorInterface.php).
### Highlighter
There are 2 highlighters bundled with the library:
- [HtmlHighlighter](./src/Highlighter/HtmlHighlighter.php) - convert matches to html tags.
Example: `http://example.com` → `http://example.com`
- [MarkdownHighlighter](./src/Highlighter/MarkdownHighlighter.php) - 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
'nofollow', 'class' => 'light']
'', // string - content to add before highlight: {here}{here}
);
$urlHighlight = new UrlHighlight(null, $highlighter);
```
> 💡 **Tip**: If you need custom behavior - extend [HtmlHighlighter](./src/Highlighter/HtmlHighlighter.php) or implement [HighlighterInterface](./src/Highlighter/HighlighterInterface.php).
> For more details and examples see [🖍️ Custom highlighter](./docs/highlighter-custom.md).
### 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](./src/Encoder/HtmlEntitiesEncoder.php) - to work with HTML entities encoded string (any character expected to be HTML entity encoded)
- [HtmlSpecialcharsEncoder](./src/Encoder/HtmlSpecialcharsEncoder.php) - to work with HTML escaped string (only `&` `"` `'` `<` `>` expected to be encoded)
🛠️ Encoder usage example
```php
highlightUrls('<a href="http://example.com">Example</a>');
// return: '<a href="http://example.com">Example</a>'
```
> 💡 **Tip**: For custom behavior - create and use your own encoder implementing [EncoderInterface](./src/Encoder/EncoderInterface.php).
> 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](https://github.com/vstelmakh)
Licensed under the MIT License. See [LICENSE](LICENSE) for more information.