2017 © Pedro Peláez
 

library bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 7+

image

chillerlan/bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 7+

  • Friday, March 3, 2017
  • by codemasher
  • Repository
  • 3 Watchers
  • 2 Stars
  • 7 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 1 Forks
  • 4 Open issues
  • 7 Versions
  • 0 % Grown

The README.md

chillerlan/php-bbcode

A recursive regexp BBCode parser for PHP 7+ using preg_replace_callback(), based on an example by MrNiceGuy on developers-guide.net. Handles nested tags as well as matching brackets and doesn't stumble across invalid tags., (*1)

version ![license][license-badge] ![Travis][travis-badge] ![Coverage][coverage-badge] ![Scrunitizer][scrutinizer-badge] ![Packagist downloads][downloads-badge] ![PayPal donate][donate-badge], (*2)

Requirements

Documentation

BBCode docs

A documentation of the included BBCodes is planned and will be available soon™ on the wiki., (*3)

Installation

requires composer, (*4)

composer.json

(note: replace dev-master with a version boundary), (*5)

{
    "require": {
        "php": ">=7.0.3",
        "chillerlan/php-bbcode": "dev-master"
    }
}

Manual installation

Download the desired version of the package from master or release and extract the contents to your project folder. After that: - run composer install to install the required dependencies and generate /vendor/autoload.php. - if you use a custom autoloader, point the namespace chillerlan\Database to the folder src of the package, (*6)

Profit!, (*7)

Usage

First of all, you'll need to import the needed classes of course:, (*8)

namespace MyProject;

use chillerlan\bbcode\Parser;
use chillerlan\bbcode\ParserOptions;

Parser options

In order to create a Parser instance, you'll first want to create an instance of ParserOptions and alter it if needed. However, this step is optional (meta, eh?)., (*9)

$options = new ParserOptions;
$options->languageInterface = MyLanguage::class;
$options->baseModuleInterface = MyAwesomeBaseModule::class;
$options->parserExtensionInterface = MyAwesomeParserExtension::class;
$options->sanitize = true;
$options->nesting_limit = 10;
$options->eol_placeholder = '__MYEOL__';
$options->bbtag_placeholder = '__MYBBTAG__';
$options->allowed_tags = ['mybbcode', 'somebbcode', 'whatever'];
$options->allow_all = false;

Parser

Now we're ready to create the Parser:, (*10)

$bbcode = new Parser($options);

// or...

$bbcode = new Parser;
$bbcode->setOptions($options);

Run the parser and output:, (*11)

echo $bbcode->parse($some_string_containing_bbcode);

In case you need some diagnostics, here you go:, (*12)

$bbcode->getTagmap();  // map of tag -> module FQCN
$bbcode->getAllowed(); // all allowed tags
$bbcode->getNoparse(); // all noparse tags
$bbcode->getSingle();  // all singletags

// get all tags of a module
$module_tags = array_keys($bbcode->getTagmap(), MyAwesomeModule::class);

That's all!, (*13)

Extend the parser

Base module

In order to create your own modules, you'll first need an empty base module which contains all basic settings and methods for each module. To do so, you'll need to extend \chillerlan\bbcode\Modules\BaseModuleAbstract . There's really not much to do, the only and most important thing is to tell the parser which modules to use. Further, you need to specify a sanitize() method and maybe an EOL token - the rest is up to you and may vary between output types., (*14)

namespace Example\MyModules;

use chillerlan\bbcode\Modules\BaseModuleAbstract;
use Example\MyModules\MyAwesomeModule;

class MyAwesomeBaseModule extends BaseModuleAbstract{

    protected $modules = [
        MyAwesomeModule::class,
    ];

    protected $eol_token = '<br />';

    public function sanitize($content){
        return htmlspecialchars($content, ENT_NOQUOTES|ENT_HTML5, 'UTF-8', false);
    }

}

Encoder module

Now that we have our base module, we're able to create the encoder module, where the actual transform happens. Each encoder module extends a base module depending on output type (MyAwesomeBaseModule here) and implements \chillerlan\bbcode\Modules\ModuleInterface. The property $tags and the method __transform() are mandatory. In case your module supports noparse or single tags, you may set the respective properties $noparse_tags and $singletags., (*15)

namespace Example\MyModules;

use chillerlan\bbcode\Modules\ModuleInterface;
use Example\MyModules\MyAwesomeBaseModule;

class MyAwesomeModule extends MyAwesomeBaseModule implements ModuleInterface{

    protected $tags = ['mybbcode', 'somebbcode', 'whatever'];

    public function __transform(){
        if(empty($this->content)){
            return '';
        }

        return '<'.$this->tag.'>'.$this->content.'</'.$this->tag.'>';
    }

}

You can also extend one of the existing modules to alter their behaviour, for example if you want the module to support more bbcodes. In this case, you should be aware that the module already extends a base module, which will be used instead of your own. However, the module information, EOL token and sanitize method of your base module will be used in the parser then and should match the extended module's parent., (*16)

namespace Example\MyModules;

use chillerlan\bbcode\Modules\ModuleInterface;
use chillerlan\bbcode\Modules\Html5\Simpletext;

class MyAwesomeModule extends Simpletext implements ModuleInterface{

    protected $tags = [
        'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'strong', 'sub', 'sup', 'del', 'small', // default tags
        'mybbcode', 'somebbcode', 'whatever', // your own tags
    ];

}

Parser extension

The parser features an extension which allows you to alter the bbcode during the parsing process, namely before and after the main parser unit runs. If you want to create your own parser extension, just implement \chillerlan\bbcode\ParserExtensionInterface, set it in the parser options and you're done., (*17)

namespace Example;

use chillerlan\bbcode\ParserExtensionInterface;

class MyAwesomeParserExtension implements ParserExtensionInterface{

    public function pre($bbcode){

        $search = [
            "\t", // lets convert all tabs into 4 spaces
            '{__BASE_URL__}', // assume we use a special token for our base url
        ];

        $replace = [
            '    ',
            'https://your.base/url/'
        ];

        return str_replace($search, $replace, $bbcode);
    }

    public function post($bbcode){
        return $bbcode;
    }

}

Language

  • @todo

Notes

The parser may cause some high CPU load, depending on the input. You should never consider to use it somewhere in your output subsystem - not even with strong caching. Encode on input - you'll want a preview anyway. ;), (*18)

You may also run into several bugs. In fact, the BBCoder is essentially a tool to squeeze out any PCRE related bug in PHP known to man (and perhaps unknown). Have fun! ;) It is highly recommended to use these php.ini settings, especially to disable the PCRE JIT in PHP7 which is a troublemaker. In case you happen to run into a PCRE related bug, i ask you to open an issue over here along with the bbcode which caused the error and further information., (*19)

Disclaimer!

I don't take responsibility for molten CPUs, smashed keyboards, broken HTML etc.. Use at your own risk!, (*20)

The Versions

03/03 2017

dev-master

9999999-dev https://github.com/codemasher/php-bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 7+

  Sources   Download

MIT

The Requires

 

The Development Requires

parser bbcode

02/03 2016

dev-php5

dev-php5 https://github.com/chillerlan/bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 5.6+, PHP 7

  Sources   Download

MIT

The Requires

 

The Development Requires

parser bbcode

29/02 2016

1.1.0

1.1.0.0 https://github.com/chillerlan/bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 5.6+, PHP 7

  Sources   Download

MIT

The Requires

 

The Development Requires

parser bbcode

28/02 2016

1.0.3

1.0.3.0 https://github.com/chillerlan/bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 5.6+, PHP 7

  Sources   Download

MIT

The Requires

 

The Development Requires

parser bbcode

09/11 2015

1.0.2

1.0.2.0 https://github.com/chillerlan/bbcode

A powerful, extensive recursive regexp BBCode parser. PHP 5.6+, PHP 7

  Sources   Download

MIT

The Requires

 

parser bbcode

03/11 2015

1.0.1

1.0.1.0 https://github.com/chillerlan/bbcode

A regexp BBCode parser.

  Sources   Download

MIT

The Requires

  • php >=5.6.0

 

parser bbcode

03/11 2015

1.0.0

1.0.0.0 https://github.com/chillerlan/bbcode

A regexp BBCode parser.

  Sources   Download

MIT

The Requires

  • php >=5.6.0

 

parser bbcode