Current File : /var/www/html/hr/api/vendor/league/commonmark/src/Extension/ExternalLink/README.md
# Extension to denote external links for `league/commonmark`
This extension to the [`league/commonmark` PHP Markdown parser][link-league-commonmark] can detect links to external sites and adjust the markup accordingly:
- Adds a `rel="noopener noreferrer"` attribute
- Optionally adds any custom HTML classes
## Usage
Configure your `Environment` as usual and simply add the `ExternalLinkExtension` provided by this package:
```php
use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;
use League\CommonMark\Extension\ExternalLink\ExternalLinkExtension;
// Obtain a pre-configured Environment with all the CommonMark parsers/renderers ready-to-go
$environment = Environment::createCommonMarkEnvironment();
// Add this extension
$environment->addExtension(new ExternalLinkExtension());
// Set your configuration
$config = [
'external_link' => [
'internal_hosts' => 'www.example.com',
'open_in_new_window' => true,
'html_class' => 'external-link',
],
];
// Instantiate the converter engine and start converting some Markdown!
$converter = new CommonMarkConverter($config, $environment);
echo $converter->convertToHtml('I successfully installed the https://github.com/thephpleague/commonmark project with the Autolink extension!');
```
## Configuration
This extension supports three configuration options under the `external_link` configuration:
### `internal_hosts`
This option defines a whitelist of hosts which are considered non-external and should not receive the external link treatment.
This can be a single host name, like `'example.com'`, which must match exactly.
If you need to match subdomains, use a regular expression like `'/(^|\.)example\.com$/'`. Note that you must use `/` characters to delimit your regex.
This configuration option also accepts an array of multiple strings and/or regexes:
```php
$config = [
'external_link' => [
'internal_hosts' => ['foo.example.com', 'bar.example.com', '/(^|\.)google\.com$/],
],
];
```
By default, if this option is not provided, all links will be considered external.
### `open_in_new_window`
This option (which defaults to `false`) determines whether any external links should open in a new tab/window.
### `html_class`
This option allows you to provide a `string` containing one or more HTML classes that should be added to the external link `<a>` tags: No classes are added by default.
## Advanced Rendering
When an external link is detected, the `ExternalLinkProcessor` will set the `external` data option on the `Link` node to either `true` or `false`. You can therefore create a [custom link renderer](https://commonmark.thephpleague.com/customization/inline-rendering/) which checks this value and behaves accordingly:
```php
class MyCustomLinkRenderer implements InlineRendererInterface
{
/**
* @param Link $inline
* @param ElementRendererInterface $htmlRenderer
*
* @return HtmlElement
*/
public function render(AbstractInline $inline, ElementRendererInterface $htmlRenderer)
{
if (!($inline instanceof Link)) {
throw new \InvalidArgumentException('Incompatible inline type: ' . \get_class($inline));
}
if ($inline->getData('external')) {
// This is an external link - render it accordingly
} else {
// This is an internal link
}
// ...
}
}
```
[link-league-commonmark]: https://github.com/thephpleague/commonmark
Mini Shell