Shortcode is a framework agnostic PHP library allowing to find, extract and process text fragments called "shortcodes" or "BBCodes". Examples of their usual syntax and usage are shown below:
[user-profile /]
[image width=600]
[link href="http://google.pl" color=red]
[quote="Thunderer"]This is a quote.[/quote]
[text color="red"]This is a text.[/text]
The library is divided into several parts, each of them containing logic responsible for different stages and ways of processing data:
- parsers extract shortcodes from text and transform them to objects,
- handlers transform shortcodes into desired replacements,
- processors use parsers and handlers to extract shortcodes, compute replacements, and apply them in text,
- events alter the way processors work to provide better control over the whole process,
- serializers convert shortcodes from and to different formats like Text, XML, JSON, and YAML.
Each part is described in the dedicated section in this document.
There are no required dependencies and all PHP versions from 5.3 up to latest 7.0 are tested and supported. This library is available on Composer/Packagist as thunderer/shortcode, to install it execute:
composer require thunderer/shortcode ^0.6
or manually update your composer.json with:
(...)
"require": {
"thunderer/shortcode": "^0.6"
}
(...)
and run composer install or composer update afterwards. If you're not using Composer, download sources from GitHub and load them as required. But really, please use Composer.
To ease usage of this library there is a class ShortcodeFacade configured for most common needs. It contains shortcut methods for all features described in the sections below:
addHandler(): adds shortcode handlers,addHandlerAlias(): adds shortcode handler alias,process(): processes text and replaces shortcodes,parse(): parses text into shortcodes,setParser(): changes processor's parser,addEventHandler(): adds event handler,serialize(): serializes shortcode object to given format,unserialize(): creates shortcode object from serialized input.
Shortcodes are processed using Processor which requires a parser and handlers. The example below shows how to implement an example that greets the person with name passed as an argument:
use Thunder\Shortcode\HandlerContainer\HandlerContainer;
use Thunder\Shortcode\Parser\RegularParser;
use Thunder\Shortcode\Processor\Processor;
use Thunder\Shortcode\Shortcode\ShortcodeInterface;
$handlers = new HandlerContainer();
$handlers->add('hello', function(ShortcodeInterface $s) {
return sprintf('Hello, %s!', $s->getParameter('name'));
});
$processor = new Processor(new RegularParser(), $handlers);
$text = '
<div class="user">[hello name="Thomas"]</div>
<p>Your shortcodes are very good, keep it up!</p>
<div class="user">[hello name="Peter"]</div>
';
echo $processor->process($text);Facade example:
use Thunder\Shortcode\ShortcodeFacade;
use Thunder\Shortcode\Shortcode\ShortcodeInterface;
$facade = new ShortcodeFacade();
$facade->addHandler('hello', function(ShortcodeInterface $s) {
return sprintf('Hello, %s!', $s->getParameter('name'));
});
$text = '
<div class="user">[hello name="Thomas"]</div>
<p>Your shortcodes are very good, keep it up!</p>
<div class="user">[hello name="Peter"]</div>
';
echo $facade->process($text);