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

Short syntax

In addition to the verbose API, the callback signature can be specified within parentheses using a syntax similar to a subset of PHP. The supported parameter types are:

  • Named parameters, using the variable notation: $attrValue
  • Literals: 123, 'string' or "double\nstring"
  • Booleans and null: true, false or null
  • Short-syntax arrays that do not contain named parameters: ['foo' => 1, 'bar' => 2]
  • Regexp objects: /^foo$/i

The regexp notation exists for compatibility with JavaScript. They are automatically cast as strings in PHP or as RegExp literals in JavaScript. If you don't use JavaScript, you can simply use strings.

$configurator = new s9e\TextFormatter\Configurator;
$configurator->BBCodes->addCustom('[X string={TEXT}]', '{@string}');

$configurator->tags['X']->attributes['string']->filterChain
    ->append('str_replace("foo", "bar", $attrValue)');

// This is the the same the following:
//
//$configurator->tags['X']->attributes['string']->filterChain
//  ->append('str_replace')
//  ->resetParameters()
//  ->addParameterByValue('foo')
//  ->addParameterByValue('bar')
//  ->addParameterByName('attrValue');

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

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

echo $html;
bar bar baz