Shortcoder

Shortcoder helps you to build your own shortcodes system in your PHP application with ease.

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Requirements

The following versions of PHP are supported by this version.

PHP 5.5
PHP 5.6
PHP 7.0
HHVM

Installation

Via Composer

$ composer require seiler/shortcoder

Usage

Create a new Shortcoder instance:

use Seiler\Shortcoder\Shortcoder;

$shortcoder = new Shortcoder();

Add your shortcodes:

$shortcoder->add('[i]*[/i]', '<em>*</em>');

$shortcoder->add('[b]*[/b]', '<strong>*</strong>');

Parse some text:

echo $shortcoder->parse('I [i]love it[/i] when a plan [b]comes together[/b].');

// I <em>love it</em> when a plan <strong>comes together</strong>.

Documentation

A shortcode is defined by a pattern, a replacement and an optional regex flag. A shortcode pattern usually contains one or more wildcards to represent the content to be preserved between the pattern and the replacement.

Shortcoder allows you to add() shortcodes with the following syntaxes.

Method arguments:

$pattern = '[b]*[/b]';
$replacement = '<strong>*</strong>';

$shortcoder->add($pattern, $replacement);

Key/value array:

$shortcode = [
    '[b]*[/b]' => '<strong>*</strong>'
];

$shortcoder->add($shortcode);

Descriptive array:

$shortcode = [
    'pattern'     => '[b]*[/b]',
    'replacement' => '<strong>*</strong>'
];

$shortcoder->add($shortcode);

Multiple shortcodes at once:

$shortcodes = [
    [
        'pattern'     => '[b]*[/b]',
        'replacement' => '<strong>*</strong>'
    ],
    [
        'pattern'     => '[img *]',
        'replacement' => '<img class="img-responsive" src="*">'
    ],
    [
        '[i]*[/i]' => '<em>*</em>'
    ]
];

$shortcoder->add($shortcodes);

The flush() and set() methods are useful for flushing the current shortcodes stack. The set() method also adds new shortcodes after a flush.

$shortcoder->set('[i]*[/i]', '<em>*</em>');

// is equivalent to:

$shortcoder->flush();
$shortcoder->add('[i]*[/i]', '<em>*</em>');

Because set() is called when you create a new Shortcoder instance, all of the add() syntaxes are available in the constructor as well.

$shortcoder = new Shortcoder($pattern, $replacement);

// is equivalent to:

$shortcoder = new Shortcoder();
$shortcoder->set($pattern, $replacement);

The parse() method takes any string as input and parses it with the stacked shortcodes.

$string = 'Lorem ipsum dolor sit amet';

echo $shortcoder->parse($string);

Method chaining

The add(), set() and flush() methods supports method chaining.

echo $shortcoder->set('foo', 'bar')
                ->add($more)
                ->parse($text);

Multiple wildcards

Wildcards are replaced by regular expression powered catch-alls when adding shortcodes to the stack. It means that when you add multiple wildcards, Shortcoder will match each wildcard in a pattern to its corresponding position in the replacement.

When a wildcard directly follows another wildcard in a pattern, only the first word of the matching expression will be assigned to the first wildcard, the remaining of the expression will be catched as the second wildcard.

$pattern = '[alert * *]';
$replacement = '<div class="alert alert-*">*</div>';

$shortcoder->add($pattern, $replacement);

echo $shortcoder->parse('[alert danger This is important!]');
// <div class="alert alert-danger">This is important!</div>

Regular expressions

When setting the third argument of the add() method (or the regex attribute of the shortcode) to any 'true' value, Shortcoder will handle pattern and replacement as raw regular expressions, which can be useful for more advanced usages.

$pattern = '/(?<=^|\s)@(\w{1,15})/m'; // Twitter @handle
$replacement = '<a href="https://twitter.com/$1">@$1</a>';

// setting the third argument
$shortcoder->set($pattern, $replacement, true);

// or setting the 'regex' attribute
$shortcoder->set([
    'pattern' => $pattern,
    'replacement' => $replacement,
    'regex' => true
]);

echo $shortcoder->parse('Do you follow @php_net ?');
// Do you follow <a href="https://twitter.com/php_net">@php_net</a> ?

Backreferences

When forcing position of some of the backreferences in a shortcode's replacement, Shortcoder will guess what to do with the remaining wildcards.

$pattern = '* then *';
$replacement = '$2 then *';

$shortcoder->add($pattern, $replacement);

echo $shortcoder->parse('first then second');
// second then first

Markdown compatibility

In case you're using Shortcoder to render some HTML blocks, just append markdown=1 in your replacement attributes to support Markdown Extra. Here's an example with Parsedown Extra:

$shortcoder->add('[info *]', '<div class="info" markdown=1>*</div>');

$text = $shortcoder->parse('[info You can use *markdown* in HTML elements.]');

echo $parsedownExtra->text($text);
// <div class="info">
// <p>You can use <em>markdown</em> in HTML elements.</p>
// </div>

With CommonMark, it's a little bit more tricky. Rules are not the same for inline and block level elements. Example of an inline level element with the league/commonmark implementation:

$shortcoder->add('[info *]', '<span class="info">*</span>');

$text = $shortcoder->parse('[info You can use *markdown* in inline HTML elements.]');

echo $commonMark->convertToHtml($text);
// <p><span class="info">You can use <em>markdown</em> in inline HTML elements.</span></p>

And here's the same example, but this time with a block level element:

$shortcoder->add('[info *]', '<div class="info">*</div>');

$text = $shortcoder->parse('[info

You can use *markdown* in block HTML elements.

]');

echo $commonMark->convertToHtml($text);
// <div class="info">
// <p>You can use <em>markdown</em> in block HTML elements.</p>
// </div>

Testing

$ phpunit

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email frederic@seiler.io instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

savasdersimcelik/shortcoder