Callback signature

By default, an attribute filter or a tag filter only receives one argument: the attribute's value or the tag, respectively. Additional parameters can be appended with the methods addParameterByName() and addParameterByValue() and the whole list of parameters can be cleared with resetParameters(). Variables set in $configurator->registeredVars are available by name and can be changed at parsing time via $parser->registeredVars. Other special parameters listed below are available by name.

Parameters available for all filters

logger The parser's logger.
registeredVars All of the registered variables in an array.

Parameters available for attribute filters

attrName The attribute's name.
attrValue The attribute's value.

Parameters available for tag filters

innerText3 On a paired tag: the text between the two tags.
On a single tag: an empty string.
openTags An array containing a list of all tags currently open.
outerText3 On a paired tag: full text covered by the tag pair.
On a single tag: same as tagText.
parser1 The parser itself.
tag The current tag.
tagConfig2 The current tag's configuration.
tagText3 The portion of text consumed by this tag.
text The text being parsed.

1 This parameter is skipped in JavaScript filters.
2 This parameter is subject to change and may be removed in a future version.
3 Available since 2.0.0.

Examples

In this example, we create a BBCode that displays the 8 first characters of a given string. The value is static, therefore addParameterByValue() is used.

$configurator = new s9e\TextFormatter\Configurator;

// Create a [X] BBCode to test our filter
$configurator->BBCodes->addCustom('[X string={TEXT}]', '{@string}');

// Add our custom filter to this attribute. It's equivalent to calling
// substr($attrValue, 0, 8)
$filter = $configurator->tags['X']->attributes['string']->filterChain->append('substr');
$filter->addParameterByValue(0);
$filter->addParameterByValue(8);

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = '[X="1234567890"]';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
12345678

Now let's modify this example to make the length variable. We create a variable named myLength in the configurator with a default value of 8 and use it as a by-name parameter. This variable can be changed at parsing time.

$configurator = new s9e\TextFormatter\Configurator;

// Create a myLength variable in the configurator
$configurator->registeredVars['myLength'] = 8;

// Create a [X] BBCode to test our filter
$configurator->BBCodes->addCustom('[X string={TEXT}]', '{@string}');

// Add our custom filter to this attribute. It's equivalent to calling
// substr($attrValue, 0, $myLength)
$filter = $configurator->tags['X']->attributes['string']->filterChain->append('substr');
$filter->addParameterByValue(0);
$filter->addParameterByName('myLength');

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = '[X="1234567890"]';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html, "\n";

// Change the value at parsing time and try again
$parser->registeredVars['myLength'] = 4;

$text = '[X="1234567890"]';
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
12345678
1234