1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
---
layout: default
title: Event Dispatcher
description: How to leverage the event dispatcher to hook into the library
---
# Event Dispatcher
This library includes basic event dispatcher functionality. This makes it possible to add hook points throughout the library and third-party extensions which other code can listen for and execute code. If you're familiar with [Symfony's EventDispatcher](https://symfony.com/doc/current/components/event_dispatcher.html) or [PSR-14](https://www.php-fig.org/psr/psr-14/) then this should be very familiar to you.
## Event Class
All events must extend from the `AbstractEvent` class:
```php
use League\CommonMark\Event\AbstractEvent;
class MyCustomEvent extends AbstractEvent {}
```
An event can have any number of methods on it which return useful information the listeners can use or modify.
## Registering Listeners
Listeners can be registered with the `Environment` using the `addEventListener()` method:
```php
public function addEventListener(string $eventClass, callable $listener, int $priority = 0)
```
The parameters for this method are:
1. The fully-qualified name of the event class you wish to observe
2. Any [PHP callable](https://www.php.net/manual/en/language.types.callable.php) to execute when that type of event is dispatched
3. An optional priority (defaults to `0`)
For example:
```php
// Telling the environment which method to call:
$customListener = new MyCustomListener();
$environment->addEventListener(MyCustomEvent::class, [$customListener, 'onDocumentParsed']);
// Or if MyCustomerListener has an __invoke() method:
$environment->addEventListener(MyCustomEvent::class, new MyCustomListener(), 10);
// Or use any other type of callable you wish!
$environment->addEventListener(MyCustomEvent::class, function (MyCustomEvent $event) {
// TODO: Stuff
}, 10);
```
## Dispatching Events
Events can be dispatched via the `$environment->dispatch()` method which takes a single argument - an instance of `AbstractEvent` to dispatch:
```php
$environment->dispatch(new MyCustomEvent());
```
Listeners will be called in order of priority (higher priorities will be called first). If multiple listeners have the same priority, they'll be called in the order in which they were registered. If you'd like your listener to prevent other subsequent events from running, simply call `$event->stopPropagation()`.
Listeners may call any method on the event to get more information about the event, make changes to event data, etc.
## List of Available Events
This library supports the following default events which you can register listeners for:
### `League\CommonMark\Event\DocumentPreParsedEvent`
This event is dispatched just before any processing is done. It can be used to pre-populate reference map of a document or manipulate the Markdown contents before any processing is performed.
### `League\CommonMark\Event\DocumentParsedEvent`
This event is dispatched once all other processing is done. This offers extensions the opportunity to inspect and modify the [Abstract Syntax Tree](/1.6/customization/abstract-syntax-tree/) prior to rendering.
## Example
Here's an example of a listener which uses the `DocumentParsedEvent` to add an `external-link` class to external URLs:
```php
use League\CommonMark\EnvironmentInterface;
use League\CommonMark\Event\DocumentParsedEvent;
use League\CommonMark\Inline\Element\Link;
class ExternalLinkProcessor
{
private $environment;
public function __construct(EnvironmentInterface $environment)
{
$this->environment = $environment;
}
public function onDocumentParsed(DocumentParsedEvent $event)
{
$document = $event->getDocument();
$walker = $document->walker();
while ($event = $walker->next()) {
$node = $event->getNode();
// Only stop at Link nodes when we first encounter them
if (!($node instanceof Link) || !$event->isEntering()) {
continue;
}
$url = $node->getUrl();
if ($this->isUrlExternal($url)) {
$node->data['attributes']['class'] = 'external-link';
}
}
}
private function isUrlExternal(string $url): bool
{
// Only look at http and https URLs
if (!preg_match('/^https?:\/\//', $url)) {
return false;
}
$host = parse_url($url, PHP_URL_HOST);
return $host != $this->environment->getConfig('host');
}
}
```
And here's how you'd use it:
```php
use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;
use League\CommonMark\Event\DocumentParsedEvent;
$env = Environment::createCommonMarkEnvironment();
$listener = new ExternalLinkProcessor($env);
$env->addEventListener(DocumentParsedEvent::class, [$listener, 'onDocumentParsed']);
$converter = new CommonMarkConverter(['host' => 'commonmark.thephpleague.com'], $env);
$input = 'My two favorite sites are <https://google.com> and <https://commonmark.thephpleague.com>';
echo $converter->convertToHtml($input);
```
Output (formatted for readability):
```html
<p>
My two favorite sites are
<a class="external-link" href="https://google.com">https://google.com</a>
and
<a href="https://commonmark.thephpleague.com">https://commonmark.thephpleague.com</a>
</p>
```
|
