Versions

Getting Started

Usage

Extensions

Customization

This is the documentation for the unsupported version 1.5. Please consider upgrading your code to the latest stable version

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 or PSR-14 then this should be very familiar to you.

Event Class

All events must extend from the AbstractEvent class:

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:

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 to execute when that type of event is dispatched
  3. An optional priority (defaults to 0)

For example:

// 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:

$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 prior to rendering.

Example

Here’s an example of a listener which uses the DocumentParsedEvent to add an external-link class to external URLs:

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:

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):

<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>

Edit this page