jBBCode - a fast, flexible BBCode parser

Documentation

  1. Introduction
    1. Getting started
    2. Defining new codes
    3. Defining custom CodeDefinitions
  2. Classes
    1. Parser
    2. CodeDefinition
    3. CodeDefinitionSet
    4. CodeDefinitionBuilder
    5. DefaultCodeDefinitionSet
    6. ElementNode
    7. Node
    8. TextNode
    9. DocumentElement
    10. InputValidator
    11. NodeVisitor

Introduction

Getting started

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.2.0/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 codes

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.

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.

Classes

Parser

The Parser class is the main jBBCode class and the one you should include in your file. This class constructs the parse tree and references all the other classes. Most users will only need to directly use this class.

__construct

Constructs a new jBBCode parser.

addBBCode

(deprecated)

adds a simple text-replacement bbcode to the parser's list of bbcode definitions.

Arguments:
  • $tagName (string)
  • $replace (string)
  • $useOption = false (boolean)
  • $parseContent = true (boolean)
  • $nestLimit = -1 (integer)
  • $optionValidator = null (InputValidator)
  • $bodyValidator = null (InputValidator)
Return value: void

addCodeDefinition

adds a code definition (see CodeDefinition class) to the parser's list of bbcode definitions. This method is often used with custom definitions that extend the CodeDefinition class.

Arguments:
  • $definition (CodeDefinition)
Return value: void

addCodeDefinitionSet

adds a set of CodeDefinitions to the parser's list of bbcode definitions.

Arguments:
  • $set (CodeDefinitionSet)
Return value: void

getAsText

returns the parse tree as text only (without any markup at all).

Return value: string (a plain text representation of the parse tree)

getAsBBCode

returns the parse tree as bbcode. This method will close any tags that were not explicitly closed.

Return value: string (a bbcode representation of the parse tree)

getAsHTML

returns the parse tree as html.

Return value: string (a html representation of the parse tree)

accept

Passes the given NodeVisitor into the accept method of the DocumentElement, effectively traversing the parse tree with the visitor.

Arguments:
  • $visitor (NodeVisitor)
Return value: void

parse

Constructs the parse tree from a string of bbcode markup.

Arguments:
  • $str (string)
Return value: void

removeOverNestedElements

(deprecated)

Removes any elements from the parse tree that are nested beyond the limit set by the element's CodeDefinition.

Return value: void

codeExists

determines whether a bbcode is defined for the given tag name and option setting.

Arguments:
  • $tagName (string)
  • $usesOption = false (boolean)
Return value: boolean (true if the code exists. false otherwise.)

getCode

gets the bbcode by the tag name and option setting.

Arguments:
  • $tagName (string)
  • $usesOption = false (boolean)
Return value: CodeDefinition (the CodeDefinition matching the arguments if it exists, null otherwise)

loadDefaultCodes

(deprecated)

adds a set of basic text-replacement bbcodes. The following are included: b, i, u, url, url (option), img, img (option), color (option)

Return value: void

CodeDefinition

A CodeDefinition object defines a specific bbcode. The parser maintains a list of CodeDefinition objects which represents all the possible bbcodes the parser will recognize. A CodeDefinition object may be created through Parser's addBBCode method, or by extending CodeDefinition class and manually instantiating an instance of the subclass. CodeDefinitions are used during the translation from the parse tree to html.

::construct

a static method to construct a new CodeDefinition instance.

Arguments:
  • $tagName (string)
  • $replacementText (string)
  • $useOption = false (boolean)
  • $parseContent = true (boolean)
  • $nestLimit = -1 (integer)
  • $optionValidator = null (InputValidator)
  • $bodyValidator = null (InputValidator)

__construct

(deprecated)

Constructs a new CodeDefinition and set properties to their defaults. This method is deprecated and in a future release will be made private.

asHtml

Returns the HTML representation of the element provided as an argument. This method is commonly overriden by custom CodeDefinitions.

Arguments:
  • $el (ElementNode)
Return value: string (the html of the argument $el)

asText

Returns the text representation of the element provided as an argument. You may want to override this method in your custom CodeDefinitions.

Arguments:
  • $el (ElementNode)
Return value: string (the text representation of the argument $el)

getTagName

Returns the CodeDefinition's tag name

Return value: string (the tag name of this code definition)

getReplacementText

Returns the the replacement text of the CodeDefinition. For default CodeDefinitions, this contains the HTML markup with {param}.

Return value: string (the CodeDefinition's replacement text)

usesOption

Returns whether or not its CodeDefinition expects (and needs) to have an option passed to it within its opening tag.

Return value: boolean (true if the code needs an option, false otherwise)

parseContent

Returns whether or not this CodeDefinition will parse its children.

Return value: boolean (true if the code translates its children)

getNestLimit

Returns the maximum number of elements defined by this CodeDefinition that can be embedded within each other.

Return value: integer (-1 if no limit is set, a positive integer otherwise)

setTagName

(deprecated)

Sets this CodeDefinition's tag name

Arguments:
  • $tagName (string)
Return value: void

setReplacementText

(deprecated)

Sets the replacement text of this CodeDefinition

Arguments:
  • $txt (string)
Return value: void

setUseOption

(deprecated)

Sets whether or not this CodeDefinition requires an option to be passed in its opening tag.

Arguments:
  • $bool (boolean)
Return value: void

setParseContent

(deprecated)

Sets whether this CodeDefinition will parse its children.

Arguments:
  • $bool (boolean)
Return value: void

setNestLimit

(deprecated)

Sets the maximum number of elements of this CodeDefinition that can be nested within each other.

Arguments:
  • $limit = -1 (integer)
Return value: void

CodeDefinitionSet

An interface for defining sets of CodeDefinitions.

getCodeDefinitions

Retrieves an array of the CodeDefinition instances in this set.

Return value: array (an array of CodeDefinition objects in the set)

CodeDefinitionBuilder

The recommended way to create text replacement CodeDefinitions is through this CodeDefinitionBuilder class. It implements the Builder pattern for CodeDefinitions. Create a builder, set the appropriate values through function calls and then call its build method to construct the builder.

__construct

Constructs a new builder

Arguments:
  • $tagName (string)
  • $replacementText (string)

setTagName

Sets the tag name the CodeDefinition should be built with

Arguments:
  • $tagName (string)

setReplacementText

Sets the replacement text that should be used for the CodeDefinition.

Arguments:
  • $replacementText (string)

setUseOption

Sets whether or not the built CodeDefinition should use the {option} bbcode argument.

Arguments:
  • $option (boolean)

setParseContent

Sets whether or not the built CodeDefinition should allow its content to be parsed and evaluted as bbcode.

Arguments:
  • $parseContent (boolean)

setNestLimit

Sets the nest limit for the CodeDefinition. A nest limit of -1 signifies no limit.

Arguments:
  • $limit (integer)

setOptionValidator

Sets the InputValidator that should be used to validate the option argument to this bbcode.

Arguments:
  • $validator (InputValidator)

setBodyValidator

Sets the InputValidator that should be used to validate the body ({param}) of the bbcode. Setting a body InputValidator only makes sense if parseContent is false.

Arguments:
  • $validator (InputValidator)

removeOptionValidator

Removes the attached option validator if one is attached.

removeBodyValidator

Removes the attached body validator if one is attached.

build

Builds a CodeDefinition instance with the current state of the builder.

Return value: CodeDefinition (a CodeDefinition with the builder's settings)

DefaultCodeDefinitionSet

Implements the CodeDefinitionSet interface and provides a default set of common BBCode definitions.

__construct

Constructs a new set of default bbcodes.

getCodeDefinitions

Returns an array of the default code definitions

Return value: array (the default CodeDefinitions in an array)

ElementNode extends Node

An ElementNode is a node within the parse tree that is defined by a CodeDefinition. It contains children, a subtree of the parse tree, and a reference to the CodeDefinition that defined it. It optionally may contain an attribute as well.

__construct

Constructs a new ElementNode

getCodeDefinition

Returns the CodeDefinition that defines the type of this element

Return value: CodeDefinition (the definition that defines this element)

setCodeDefinition

Set the CodeDefinition that defines the type of this element

Arguments:
  • $codeDef (CodeDefinition)
Return value: void

getTagName

Returns the tag name of this element

Return value: string (the tag name of this element)

getAttribute

Returns the attribute (value for the {option}) of this element

Return value: string (the attribute passed to this bbcode)

getChildren

Returns all of the child nodes of this node

Return value: array of Node objects (the children of this node)

getAsText

Returns the element as text (without any markup)

Return value: string (a string representation of this element and its children)

getAsBBCode

Returns the element as BBCode

Return value: string (a bbcode representation of this element and its children)

getAsHTML

Returns the element as HTML

Return value: string (a html representation of this element and its children)

addChild

Appends an element to this element's children (and updates the child's parent)

Arguments:
  • $child (Node)
Return value: void

removeChild

Removes a child element if the element is really a child of the target

Arguments:
  • $child (Node)
Return value: void

setTagName

Sets this element's tag name

Arguments:
  • $tagName (string)
Return value: void

setAttribute

Sets this element's attribute (value for the option)

Arguments:
  • $attribute (string)
Return value: void

closestParentOfType

Vertically traverses the tree searching for an ancestor of the current element that has the tag name provided as an argument.

Arguments:
  • $str (string)
Return value: ElementNode (null if no such ancestor exists, otherwise the closest ancestor that has the provided tag name)

Node

An abstract class for a node in the parse tree.

getNodeId

Returns the node's node id

Return value: integer (the node's id)

getParent

Returns this node's parent

Return value: Node (this node's parent, or null if the node has no parent)

hasParent

Returns true if this node has a parent, false if it does not

Return value: boolean (true if this node has a parent, false otherwise)

isTextNode

Returns true if this node is a text node (returns false by default, and is overridden by TextNode to return true)

Return value: boolean (true if this node is a text node)

accept

allows the given NodeVisitor instance to visit this node

Arguments:
  • $visitor (NodeVisitor)
Return value: void

getAsText

Returns this node as text, without any markup

Return value: string (representation of this node and its children without any markup)

getAsBBCode

Returns this node (and its children) as bbcode

Return value: string (a bbcode string)

getAsHTML

Returns this node (and its children) as html

Return value: string (a html string)

setParent

Sets this node's parent to the argument

Arguments:
  • $parent (Node)
Return value: void

setNodeId

Sets the node id of this node

Arguments:
  • $nodeid (integer)
Return value: void

TextNode extends Node

Represents a node that only contains text

__construct

Constructs a new TextNode

Arguments:
  • $val (string)

isTextNode

Overrides Node's default implementation and returns true

Return value: boolean (true)

getValue

Returns the text string of this text node

Return value: string (this node's string value)

getAsBBCode

Returns the text string of this text node

Return value: string (this node's string value)

getAsHTML

Returns the text string of this text node

Return value: string (this node's string value)

DocumentElement extends ElementNode

DocumentElement is used as the root of every parse tree

__construct

Constructs a new DocumentElement

getAsBBCode

Returns the concatenated bbcode representations of all of its children

Return value: string (the bbcode representation of the parse tree)

getAsHTML

Returns the concatenated HTML representations of all of its children

Return value: string (the html representation of the parse tree)

InputValidator

An interface for validators of input. These can be attached to CodeDefintiions to either validate {option} arguments or the bodies of elements {param}.

validate

Arguments:
  • $input (string)
Return value: boolean (true if $input is valid)

NodeVisitor

An interface for traversing the parse tree through the Visitor Pattern.

visitDocumentElement

Arguments:
  • $documentElement (DocumentElement)
Return value: void

visitTextNode

Arguments:
  • $textNode (TextNode)
Return value: void

visitElementNode

Arguments:
  • $elementNode (ElementNode)
Return value: void