Skip to content
Permalink
Browse files

Merge branch 'feature/priority'

  • Loading branch information...
colinodell committed Mar 13, 2019
2 parents c687376 + d972ff9 commit 8a462581f9b37303d12e150a8f7b9d417c9cf61a
@@ -11,3 +11,7 @@ disabled:
- phpdoc_summary
- post_increment
- self_accessor

finder:
not-name:
- "CommonMarkCoreExtension.php"
@@ -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.
@@ -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)
@@ -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);
}
@@ -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));
}
}
@@ -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);
}
@@ -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;
@@ -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()
{

0 comments on commit 8a46258

Please sign in to comment.
You can’t perform that action at this time.