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 extensions, parsers, renderers, etc. with the Environment so that the library is aware of them.
An empty Environment can be obtained like this:
use League\CommonMark\Environment\Environment;
$config = [];
$environment = new Environment($config);
You can customize the Environment using any of the methods below (from the EnvironmentBuilderInterface interface).
Once your Environment is configured with whatever configuration and extensions you want, you can instantiate a MarkdownConverter and start converting MD to HTML:
use League\CommonMark\MarkdownConverter;
// Using $environment from the previous code sample
$converter = new MarkdownConverter($environment);
echo $converter->convert('# Hello World!');
addExtension()
public function addExtension(ExtensionInterface $extension);
Registers the given extension with the environment. For example, if you want core CommonMark functionality plus footnote support:
use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\Footnote\FootnoteExtension;
$config = [];
$environment = new Environment($config);
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new FootnoteExtension());
addBlockStartParser()
public function addBlockStartParser(BlockStartParserInterface $parser, int $priority = 0);
Registers the given BlockStartParserInterface with the environment with the given priority (a higher number will be executed earlier).
See Block Parsing 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.
addDelimiterProcessor()
public function addDelimiterProcessor(DelimiterProcessorInterface $processor);
Registers the given DelimiterProcessorInterface with the environment.
See Inline Parsing for details.
addRenderer()
public function addRenderer(string $nodeClass, NodeRendererInterface $renderer, int $priority = 0);
Registers a NodeRendererInterface to handle a specific type of AST node ($nodeClass) with the given priority (a higher number will be executed earlier).
See Rendering 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.