league/commonmark
Highly extensible PHP Markdown parser supporting full CommonMark and GitHub-Flavored Markdown. Convert Markdown to HTML with simple converters, customize rendering via extensions, and run safely with options like stripping HTML and blocking unsafe links.
layout: default title: Upgrading to Newer Versions description: Guide to upgrading to newer versions of this library redirect_from:
There are no breaking changes when upgrading from 2.7 to 2.8.
There are no breaking changes when upgrading from 2.6 to 2.7.
max_delimiters_per_line Configuration OptionThe max_delimiters_per_line configuration option was added in 2.6 to help protect against malicious input that could
cause excessive memory usage or denial of service attacks. It defaults to PHP_INT_MAX (no limit) for backwards
compatibility, which is safe when parsing trusted input. However, if you're parsing untrusted input from users, you
should probably set this to a reasonable value (somewhere between 100 and 1000) to protect against malicious inputs.
If you're implementing a custom delimiter processor, and getDelimiterUse() has more logic than just a
simple return statement, you should implement CacheableDelimiterProcessorInterface instead of
DelimiterProcessorInterface to improve performance and avoid possible quadratic performance issues.
DelimiterProcessorInterface has a getDelimiterUse() method that tells the engine how many characters from the
matching delimiters should be consumed. Simple processors usually always return a hard-coded integer like 1 or 2.
However, some more advanced processors may need to examine the opening and closing delimiters and perform additional
logic to determine whether they should be fully or partially consumed. Previously, these results could not be safely
cached, resulting in possible quadratic performance issues.
In 2.6, the CacheableDelimiterProcessorInterface was introduced to allow these "dynamic" processors to be safely
cached. It requires a new getCacheKey() method that returns a string that uniquely identifies the combination of
factors considered when determining the delimiter use. This key is then used to cache the results of the search for
a matching delimiter.
These are no significant changes since 2.4.
Prior to 2.4.0, this library did a poor job of using appropriate exception types and documenting which exceptions could
be thrown. For example, all of the main interfaces said that only RuntimeException could be thrown, but in reality
other exceptions like LogicException or InvalidArgumentException could be thrown in some cases!
This inconsistent behavior and inaccurate documentation has been fixed in 2.4.0 by:
CommonMarkException interface implemented by all exceptions thrown by this libraryIf you were previously catching exceptions thrown by this library in your code, you should consider changing your
catch blocks to either catch CommonMarkException (for all exceptions) or one of the exception types under the
League\CommonMark\Exception namespace.
MarkdownRendererInterface has been deprecated and will be removed in the next major version. Please use DocumentRendererInterface instead.
MarkdownConverterInterfaceThe MarkdownConverterInterface and its convertToHtml() method were deprecated in 2.2.0 and will be removed in 3.0.0.
You should switch your implementations to use ConverterInterface and convert() instead which provide the same behavior.
No changes or deprecations were made that require changes to upgrade to the new version.
Version 2.0 contains lots of changes throughout the library. We've split the upgrade guide into three sections to help you better identify the changes that are most relevant to you:
The upgrade guide for consumers is relevant for developers who use this library as-is to perform basic conversion of Markdown to HTML. You might enable some extensions or tweak the configuration settings, but you don't write your own custom parsers or anything like that. This condensed upgrade guide therefore only covers the most obvious changes that might impact your usage of this library.
If you develop open-source software that uses this library, read the upgrade guide for integrators. It contains all of the information from the Consumer guide above, but with additional details that may be relevant to you.
The upgrade guide for developers is aimed at developers who create custom extensions/parsers/renderers and need to know about all of the under-the-hood changes in 2.x. It is the most comprehensive guide, containing all of the information from the two guides above, and even more details about the under-the-hood changes that likely impact your customizations.
How can I help you explore Laravel packages today?