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
ornull
- 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