Merge branch 'feature/priority'

.styleci.yml

@@ -11,3 +11,7 @@ disabled:
   - phpdoc_summary
   - post_increment
   - self_accessor
+
+finder:
+  not-name:
+    - "CommonMarkCoreExtension.php"

CHANGELOG.md

@@ -4,6 +4,31 @@ Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) princip
 
 ## [Unreleased][unreleased]
 
+### Added
+
+ - The priority of parsers, processors, and renderers can now be set when `add()`ing them; you no longer need to rely on the order in which they are added
+ - Added support for trying multiple parsers per block/inline
+ - Extracted two new bases interfaces from `Environment`:
+   - `EnvironmentInterface`
+   - `ConfigurableEnvironmentInterface`
+
+### Changed
+
+ - `Environment` is now a `final` class
+ - `Environment::getBlockRendererForClass()` was replaced with `Environment::getBlockRenderersForClass()` (note the added `s`)
+ - `Environment::getInlineRendererForClass()` was replaced with `Environment::getInlineRenderersForClass()` (note the added `s`)
+ - The `Environment::get____()` methods now return an iterator instead of an array
+
+### Removed
+
+ - Removed support for `add()`ing parsers with just the target block/inline class name - you need to include the full namespace now
+ - Removed the following unused methods from `Environment`:
+   - `getInlineParser($name)`
+   - `getInlineParsers()`
+   - `createInlineParserEngine()`
+
+### Changed
+
 ## [0.18.1] - 2018-12-29
 
 This is a **security update** release.

UPGRADE.md

@@ -1,5 +1,38 @@
 # Upgrade Instructions
 
+## UNRELEASED
+
+The `Environment` and extension framework underwent some major changes in this release.
+
+### Environment interfaces
+
+We have extracted two interfaces from the `Environment` class:
+
+ - `EnvironmentInterface` - contains all the getters; use this in your parsers, renderers, etc.
+ - `ConfigurableEnvironmentInterface` - contains all the `add` methods, as well as `setConfig()` and `mergeConfig`
+
+As a result, `EnvironmentAwareInterface` now requires an `EnvironmentInterface` instead of an `Environment`, so update your parsers/processors/renderers accordingly.
+
+### Extensions
+
+Extensions work much differently now.  In the past, you'd have functions returning an array of things that the `Environment` would register for you.
+
+The `ExtensionInterface` was changed to have a single `register(ConfigurableEnvironmentInterface $environment)` method.  You must now manually `add()` all your parsers, processors, and renderers yourself directly within the environment you are provided.  See the changes made to `CommonMarkCoreExtension` for a good example.
+
+The `Environment` will still automatically inject the `Environment` or `Configuration` for any parsers, processors, and renderers implementing the `EnvironmentAwareInterface` or `ConfigurationAwareInterface` - that behavior hasn't changed.
+
+### Adding renderers with short names
+
+`Environment::add___Renderer()` now requires the fully-qualified class name with namespace as its first argument.  Providing just the class name without the namespace will no longer work.  
+
+### Prioritization of parsers, processors, and renderers
+
+The execution order of these things no longer depends on the order you add them - you can now specific custom priorities when `add()`ing them to the `Environment`!  The priority can be any integer you want.  The default value is `0`. All CommonMark Core things will have a priority between -255 and 255.  The higher the number, the earlier it will be executed.
+
+### Multiple block/inline renderers per class
+
+Thanks to the new prioritization system, we now support multiple renderers for the same block/inline class!  The first renderer to return a non-null result will be considered the "winner" and no subsequent renderers will execute for that block/inline.  No change should be required for most extensions unless you were using some weird workaround to support multiple renderers yourself. 
+
 ## 0.18.0
 
 No breaking changes were introduced, but we did add a new interface: `ConverterInface`. Consider depending on this interface in your code instead of the concrete implementation. (See #330)

src/Block/Renderer/HtmlBlockRenderer.php

@@ -17,7 +17,7 @@
 use League\CommonMark\Block\Element\AbstractBlock;
 use League\CommonMark\Block\Element\HtmlBlock;
 use League\CommonMark\ElementRendererInterface;
-use League\CommonMark\Environment;
+use League\CommonMark\EnvironmentInterface;
 use League\CommonMark\Util\Configuration;
 use League\CommonMark\Util\ConfigurationAwareInterface;
 
@@ -46,11 +46,11 @@ public function render(AbstractBlock $block, ElementRendererInterface $htmlRende
             return '';
         }
 
-        if ($this->config->getConfig('html_input') === Environment::HTML_INPUT_STRIP) {
+        if ($this->config->getConfig('html_input') === EnvironmentInterface::HTML_INPUT_STRIP) {
             return '';
         }
 
-        if ($this->config->getConfig('html_input') === Environment::HTML_INPUT_ESCAPE) {
+        if ($this->config->getConfig('html_input') === EnvironmentInterface::HTML_INPUT_ESCAPE) {
             return htmlspecialchars($block->getStringContent(), ENT_NOQUOTES);
         }
 

src/CommonMarkConverter.php

@@ -29,16 +29,19 @@ class CommonMarkConverter extends Converter
     /**
      * Create a new commonmark converter instance.
      *
-     * @param array            $config
-     * @param Environment|null $environment
+     * @param array                     $config
+     * @param EnvironmentInterface|null $environment
      */
-    public function __construct(array $config = [], Environment $environment = null)
+    public function __construct(array $config = [], EnvironmentInterface $environment = null)
     {
         if ($environment === null) {
             $environment = Environment::createCommonMarkEnvironment();
         }
 
-        $environment->mergeConfig($config);
+        if ($environment instanceof ConfigurableEnvironmentInterface) {
+            $environment->mergeConfig($config);
+        }
+
         parent::__construct(new DocParser($environment), new HtmlRenderer($environment));
     }
 }

src/ConfigurableEnvironmentInterface.php

@@ -0,0 +1,81 @@
+<?php
+
+/*
+ * This file is part of the league/commonmark package.
+ *
+ * (c) Colin O'Dell <colinodell@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace League\CommonMark;
+
+use League\CommonMark\Block\Parser\BlockParserInterface;
+use League\CommonMark\Block\Renderer\BlockRendererInterface;
+use League\CommonMark\Inline\Parser\InlineParserInterface;
+use League\CommonMark\Inline\Processor\InlineProcessorInterface;
+use League\CommonMark\Inline\Renderer\InlineRendererInterface;
+
+interface ConfigurableEnvironmentInterface extends EnvironmentInterface
+{
+    /**
+     * @param array $config
+     */
+    public function mergeConfig(array $config = []);
+
+    /**
+     * @param array $config
+     */
+    public function setConfig(array $config = []);
+
+    /**
+     * @param BlockParserInterface $parser
+     * @param int                  $priority
+     *
+     * @return self
+     */
+    public function addBlockParser(BlockParserInterface $parser, $priority = 0);
+
+    /**
+     * @param InlineParserInterface $parser
+     * @param int                   $priority
+     *
+     * @return self
+     */
+    public function addInlineParser(InlineParserInterface $parser, $priority = 0);
+
+    /**
+     * @param InlineProcessorInterface $processor
+     * @param int                      $priority
+     *
+     * @return self
+     */
+    public function addInlineProcessor(InlineProcessorInterface $processor, $priority = 0);
+
+    /**
+     * @param DocumentProcessorInterface $processor
+     * @param int                        $priority
+     *
+     * @return self
+     */
+    public function addDocumentProcessor(DocumentProcessorInterface $processor, $priority = 0);
+
+    /**
+     * @param string                 $blockClass
+     * @param BlockRendererInterface $blockRenderer
+     * @param int                    $priority
+     *
+     * @return self
+     */
+    public function addBlockRenderer($blockClass, BlockRendererInterface $blockRenderer, $priority = 0);
+
+    /**
+     * @param string                  $inlineClass
+     * @param InlineRendererInterface $renderer
+     * @param int                     $priority
+     *
+     * @return self
+     */
+    public function addInlineRenderer($inlineClass, InlineRendererInterface $renderer, $priority = 0);
+}

src/Context.php

@@ -23,7 +23,7 @@
 class Context implements ContextInterface
 {
     /**
-     * @var Environment
+     * @var EnvironmentInterface
      */
     protected $environment;
 
@@ -66,7 +66,7 @@ class Context implements ContextInterface
 
     protected $referenceParser;
 
-    public function __construct(Document $document, Environment $environment)
+    public function __construct(Document $document, EnvironmentInterface $environment)
     {
         $this->doc = $document;
         $this->tip = $this->doc;

src/DocParser.php

@@ -23,7 +23,7 @@
 class DocParser
 {
     /**
-     * @var Environment
+     * @var EnvironmentInterface
      */
     protected $environment;
 
@@ -38,17 +38,17 @@ class DocParser
     private $maxNestingLevel;
 
     /**
-     * @param Environment $environment
+     * @param EnvironmentInterface $environment
      */
-    public function __construct(Environment $environment)
+    public function __construct(EnvironmentInterface $environment)
     {
         $this->environment = $environment;
         $this->inlineParserEngine = new InlineParserEngine($environment);
         $this->maxNestingLevel = $environment->getConfig('max_nesting_level', INF);
     }
 
     /**
-     * @return Environment
+     * @return EnvironmentInterface
      */
     public function getEnvironment()
     {