StringParser_BBCode class documentation

3. Parser functions

3.1 Task of parser functions

BBCode is used to replace the input of HTML code. But if only the BBCode gets replaced HTML code will not be escaped and sent directly to the browser. For example it would be useless to only replace BBCode in a text like the following: [b]Hello<script type="text/javascript">/* do something very evil with javascript */</script>[/b]. The <script> element should be escaped so that it may not do any harm. This can be achieved with the htmlspecialchars function. One could call htmlspecialchars for the complete content before using this class. In that case the quotes that are used in attributes (e.g. [img alt="alternative text"]) would also be replaced and the class would not accept it anymore. For this reason the class provides the option to call the function only for relevant portions of the txet. Functions that are registered to the class for this goal are called parser functions.

The possibilities of parser functions are not limited to escaping HTML code. Another common application is the replacement of smilies.

3.2 Relevance of content types

The class does not only provide the possibility to call functions for the text that is outside of the BBCodes - it is also possible to register different parser functions for different content types. With the registration of the parser function one also specifies for which content type or content types the parser function should be called. For example, if one has defined a code called [code] that is used to display source code one will not want to have smilies replaced inside this block but nevertheless HTML code should still be escaped. In the rest of the text though smilies should be replaced.

The content types also play a role when it comes to the correct nesting of BBCodes. It was already mentioned that the standard content type (that is used if no BBCode is opened yet) is block. It is possible to change this content type, you may use the method

void setRootContentType (string $content_type);

You can call this method as follows:

$bbcode->setRootContentType ('my_own_type');

3.3 Registration of parser functions

You can register parser functions by calling the method

void addParser (mixed $type, mixed $parser);

The parameter $type specifies for which content type the parser function should be called. The parameter $parser specifies which function should be called. $type my be a string (a single content type) but it may also be an array for the case that you want to register a parser function for several conten ttypes. The following examples show how to register parser functions:

$bbcode->addParser ('block', 'htmlspecialchars');

Here the function htmlspecialchars function would always be called when a text has to be output that is inside an element of the content type block.

$bbcode->addParser (array ('block', 'inline'), 'htmlspecialchars');

This code would be equivalent to:

$bbcode->addParser ('block', 'htmlspecialchars');
$bbcode->addParser ('inline', 'htmlspecialchars');

It is not only possible to register global functions but also object methods:

$bbcode->addParser ('content_type', array (&$my_object, 'dosomething'));

The class would call $my_object->dosomething ($text) in this case. It is also possible to register static methods:

$bbcode->addParser ('content_type', array ('MyClass', 'dosomething'));

Here, MyClass::dosomething ($text) would be called.

Furthermore it is possible to register more than one parser function for a content type. These will be called in the order of registration:

$bbcode->addParser ('block', 'htmlspecialchars');
$bbcode->addParser ('block', 'nl2br');

Here the functions htmlspecialchars and nl2br would be registered for the content type block. If a text inside an element of this content type has to be output it will be processed like this: $text = htmlspecialchars ($text); $text = nl2br ($text);