Upgrading from 0.18 to 0.19
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.
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
getName() method has been removed from several classes:
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 notthing 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
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.
We have extracted two interfaces from the
EnvironmentInterface- contains all the getters; use this in your parsers, renderers, etc.
ConfigurableEnvironmentInterface- contains all the
addmethods, as well as
As a result,
EnvironmentAwareInterface now requires an
EnvironmentInterface instead of an
Environment, so update your parsers/processors/renderers accordingly.
A few methods from
AbstractBlock have been extracted into a new
AbstractStringContainerBlock class and corresponding
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
false, simply remove the three methods from the bulleted list above, along with
acceptsLines()and any calls to
true, change your base class from
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
- 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 work much differently now. In the past, you’d have functions returning an array of things that the
Environment would register for you.
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.
Environment will still automatically inject the
Configuration for any parsers, processors, and renderers implementing the
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
In cases where you may have previously passed a
null value in, skip the call to this method. The previous behavior was to return
null values, but
null is never escapable so it’s silly to make this call when we know what the result will be.