Upgrading from 0.18 to 0.19
The Environment
and extension framework underwent some major changes in this release. Please read this if you maintain any community extensions or have written custom functionality on top of this library.
PHP support
This library no longer supports PHP 5.6 or 7.0. Feel free to remove support for those from your extensions as well.
HTML attribute escaping
Previously, any attributes passed into an HtmlElement
would need to be pre-escaped. This is now done for you so be sure to remove any references to Xml::escape()
when applied to attributes.
This does not affect inner contents which may still need pre-escaping of untrusted user input.
Removed classes and interface methods
The getName()
method has been removed from several classes:
BlockParserInterface
andAbstractBlockParser
InlineParserInterface
andAbstractInlineParser
This method was originally intended for supporting XML rendering, which was never implemented, and will likely define names a bit differently if/when we do add support.
After doing this, the two abstract classes mentioned above had nothing left in them, so those were removed. Any parsers previously extending them should directly implement the corresponding interface instead.
InlineContainer
was also removed.
Xml::escape()
no longer accepts the deprecated $preserveEntities
parameter.
Removed deprecated RegexHelper
methods
Several previously-deprecated methods inside of RegexHelper
were finally removed. That functionality was made available with static methods and constants, so use those instead.
Parameter and return types
Pretty much every method now uses parameter and return types, including several interfaces. Update your implementations accordingly.
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 theadd
methods, as well assetConfig()
andmergeConfig
As a result, EnvironmentAwareInterface
now requires an EnvironmentInterface
instead of an Environment
, so update your parsers/processors/renderers accordingly.
Block Elements
A few methods from AbstractBlock
have been extracted into a new AbstractStringContainerBlock
class and corresponding StringContainerInterface
interface:
addLine(string $line)
getStringContent()
handleRemainingContents(ContextInterface $context, Cursor $cursor)
These are used to represent a block which can contain strings of text inside (even if those strings do not contain “inline” elements but just plain text).
To determine how to best upgrade your existing block element classes, look at the value returned by the acceptsLines()
method:
- If
acceptsLines()
returnsfalse
, simply remove the three methods from the bulleted list above, along withacceptsLines()
and any calls toparent::__construct()
. - If
acceptsLines()
returnstrue
, change your base class fromAbstractBlock
toAbstractStringContainerBlock
and removeacceptsLines()
.
Additionally, StringContainerInterface
now extends this new StringContainerInterface
interface. Just make sure you’ve implemented the change mentioned above and you should be fine.
Finally, please note that the getStrings()
method does no longer exists on the AbstractBlock
class. If you previously relied on this, consider making these changes to your block element class:
- Extend from
AbstractStringContainerBlock
instead ofAbstractBlock
- Override its
finalize()
method to set the final contents like so:$this->finalStringContents = implode("\n", $this->strings);
- Call the
getStringContent()
method wherever you need to obtain those finalized string contents
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.
RegexHelper::isEscapable()
no longer accepts null
values
In cases where you may have previously passed a null
value in, skip the call to this method. The previous behavior was to return false
for null
values, but null
is never escapable so it’s silly to make this call when we know what the result will be.