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

The Environment

The Environment contains all of the parsers, renderers, configurations, etc. that the library uses during the conversion process. You therefore must register all parsers, renderers, etc. with the Environment so that the library is aware of them.

A pre-configured Environment can be obtained like this:

use League\CommonMark\Environment;

$environment = Environment::createCommonMarkEnvironment();

All of the core renders, parsers, etc. needed to implement the CommonMark spec will be pre-registered and ready to go.

You can customize this default Environment (or even a new, empty one) using any of the methods below (from the ConfigurableEnvironmentInterface interface).

mergeConfig()

public function mergeConfig(array $config = []);

Merges the given configuration settings into any existing ones.

addExtension()

public function addExtension(ExtensionInterface $extension);

Registers the given extension with the environment. This is typically how you’d integrate third-party extensions with this library.

addBlockParser()

public function addBlockParser(BlockParserInterface $parser, int $priority = 0);

Registers the given BlockParserInterface with the environment with the given priority (a higher number will be executed earlier).

See Block Parsing for details.

addBlockRenderer()

public function addBlockRenderer(string $blockClass, BlockRendererInterface $blockRenderer, int $priority = 0);

Registers a BlockRendererInterface to handle a specific type of block ($blockClass) with the given priority (a higher number will be executed earlier).

See Block Rendering for details.

addInlineParser()

public function addInlineParser(InlineParserInterface $parser, int $priority = 0);

Registers the given InlineParserInterface with the environment with the given priority (a higher number will be executed earlier).

See Inline Parsing for details.

addInlineRenderer()

public function addInlineRenderer(string $inlineClass, InlineRendererInterface $renderer, int $priority = 0);

Registers an InlineRendererInterface to handle a specific type of inline ($inlineClass) with the given priority (a higher number will be executed earlier). A single renderer can handle multiple inline classes, but you must register it separately for each type. (The same renderer instance can be re-used if desired.)

See Inline Rendering for details.

addDelimiterProcessor()

public function addDelimiterProcessor(DelimiterProcessorInterface $processor);

Registers the given DelimiterProcessorInterface with the environment.

See Inline Parsing for details.

addEventListener()

public function addEventListener(string $eventClass, callable $listener, int $priority = 0);

Registers the given event listener with the environment.

See Event Dispatcher for details.

Priority

Several of these methods allows you to specify a numeric $priority. In cases where multiple things are registered, the internal engine will attempt to use the higher-priority ones first, falling back to lower priority ones if the first one(s) were unable to handle things.

Accessing the Environment and Configuration within parsers/renderers/etc

If your custom parser/renderer/listener/etc. implements either EnvironmentAwareInterface or ConfigurationAwareInterface we’ll automatically inject the environment or configuration into them once the environment has been fully initialized. This will provide your code with access to the finalized information it may need.


Edit this page