jBBCode - a fast, flexible BBCode parser

Welcome. Installation of jBBCode is quick and simple. First, download and unarchive the latest version of jBBCode. Upload the directory to your server. Remember that jBBCode requires PHP 5.3+. To include jBBCode in your project, you can either manually include Parser.php or use a PSR-0 autoloader. To manually include jBBCode, wherever you use jBBCode, require_once the Parser.php file:

require_once "./path/to/jBBCode/Parser.php";

Parser.php will handle including the rest of the relevant files. Once you've included Parser.php, jBBCode is installed and ready to go.

To begin parsing BBCode, you'll need to define a few bbcodes. The DefaultCodeDefinitionSet class can provide some basic common bbcodes for you, or you can define your own.

Because jBBCode uses namespaces, you'll need to use the namespace syntax when using jBBCode. For example:

<?php

require_once "jbbcode-1.0.1/Parser.php";

$parser = new JBBCode\Parser();
$parser->addCodeDefinitionSet(new JBBCode\DefaultCodeDefinitionSet());

$parser->parse(htmlentities($_GET['input']));

print $parser->getAsHtml();

See example 1 for more help.

Defining new bbcodes is simple with jBBCode. New text-replacement bbcodes are added to the parser through creating instances of the CodeDefinition class and adding them to the parser through its addCodeDefinition method. The easiest way to create new CodeDefinitions is through the CodeDefinitionBuilder class. The builder's constructor requires the tag name for the bbcode and a replacement string. The replacement string should be html containing {param} and possibly {option}. When the BBCode is translated to html, the contents between the tags will take the place of {param}. Your bbcode's can also take an argument (referred to as an option) in an opening tag. If you enable the option on a bbcode, the {option} string in the replacement text will be replaced with the argument provided to the bbcode. Here's a couple examples defining very simple text-replacement bbcodes and adding them to a parser.

$builder = new JBBCode\CodeDefinitionBuilder('i', '{param}');
$parser->addCodeDefinition($builder->build());

$builder = new JBBCode\CodeDefinitionBuilder('u', '{param}');
$parser->addCodeDefinition($builder->build());

To make use of the {option}, you must enable it on your CodeDefinition. The builder provides the setUseOption method for this purpose. Creating a bbcode with an option is illustrated below.

$builder = new JBBCode\CodeDefinitionBuilder('url', '{param}');
$builder->setUseOption(true)->setOptionValidator(new \JBBCode\validators\UrlValidator());
$parser->addCodeDefinition($builder->build());

The above example makes use of an InputValidator. Often your bbcodes will take values that are inserted into html. It's important to validate these values to prevent security risks. When constructing a definition through the CodeDefinitionBuilder you can apply validators to the definition through the setOptionValidator and setBodyValidator methods to validate the {option} and {param} respectively. Note that it only makes sense to set a body validator if you additionally setParseContent(false), otherwise the body of the bbcode is treated as bbcode itself.

For defining bbcodes that do more than just text replacement, see the next section, Defining custom CodeDefinitions.

With jBBCode, bbcodes are not limited to simple text replacement. Through extending the CodeDefinition class, you can override default text replacement and use all the power of PHP in evaluating the BBCode. Because the parse tree has already been constructed, accessing an element's content and attribute is simple. Generally, when creating your own custom CodeDefinition, the only methods you really need to override are the constructor (to define the tag name and option parameters) and asHtml which takes an ElementNode that is defined by your CodeDefinition and returns the html representation of that ElementNode.

Here is an example that extends CodeDefinition in order to use regular expressions on the code's content. The result is a YouTube embed bbcode that only requires the url of the YouTube video.

<?php

class YoutubeEmbed extends JBBCode\CodeDefinition {

    public function __construct()
    {
        parent::__construct();
        $this->setTagName("youtubeEmbed");
    }

    public function asHtml(JBBCode\ElementNode $el)
    {
        $content = "";
		foreach($el->getChildren() as $child)
			$content .= $child->getAsBBCode();
			
		$foundMatch = preg_match('/v=([A-z0-9=\-]+?)(&.*)?$/i', $content, $matches);
		if(!$foundMatch)
		    return $el->getAsBBCode();
		else
		    return "<iframe width=\"640\" height=\"390\" src=\"http://www.youtube.com/embed/".$matches[1]."\" frameborder=\"0\" allowfullscreen></iframe>";
    }


}
	

The custom CodeDefinition is then loaded into the parser through the addCodeDefintion:

	$youtubeEmbed = new YoutubeEmbed();
	$parser->addCodeDefinition($youtubeEmbed);

The youtubeEmbed bbcode defined here is currently in use at http://xboxamerica.com.