Here is a
link to
example.com
") );
@]
* The first argument is a unique name for the markup ("example").
* The second argument says to perform this markup along with other directives.
* The third argument is the pattern to look for "(:example:)".
* The fourth argument is the HTML that "(:example:)" is to be replaced with. We use the Keep() function here to prevent the output from being further processed by PmWiki's markup rule -- in the above example, we don't want the http://www.example.com url to be again converted to a link.
[[#random]]
!!! Define a markup to call a custom function that returns content
An 'e' option on the [@$pattern@] parameter will cause the [@$replace@] parameter to be treated as a PHP expression to be evaluated instead of replacement text. Thus, a markup to produce a random number between 1 and 100 might look like:
->[@
Markup('random', 'directives',
'/\\(:random:\\)/e',
"rand(1, 100)");
@]
This calls the PHP built-in rand() function and substitutes the directive with the result. Any function can be called, including functions defined in a [[local customization(s)]] file.
Arguments can also be passed by using regular expression capturing parentheses, thus
->[@
Markup('randomargs', 'directives',
'/\\(:random (\\d+) (\\d+):\\)/e',
"rand('$1', '$2')");
@]
will cause the markup [@(:random 50 100:)@] to generate a random number between 50 and 100.
->%note% Note: Be very careful with the /e modifier in regular expressions; malicious authors may be able to pass strings that cause arbitrary and undesirable PHP functions to be executed.
For a PmWiki function to help with parsing arbitrary sequences of arguments and key=value pairs, see Cookbook:ParseArgs.
[[#php55]]
!! Migration to PHP 5.5 and Markup_e()
Since PHP version 5.5, the /e evaluation modifier is deprecated and some hosting providers don't allow its use.
Recent versions of the PmWiki core (2.2.58 and newer) allow new ways to define markup rules without being dependent on the /e eval modifier. The historical ways to define markup rules are not removed and work, but may be incompatible with PHP 5.5 installations.
''Note: if your replacement pattern doesn't need evaluation, you must use Markup() like before and not Markup_e().''
The following is acceptable for PHP 5.5+ (compatible with PmWiki 2.2.58+, will also work in PHP 5.4 and older)
* Markup($name, $when, $pattern, $replace);
** $pattern can no longer have an "/e" modifier
** $replace can be a string with matches as $1, $2 etc.
** $replace can be a function name (callback) which will be called with the array of matches as argument.
** for PHP 5.4 or earlier, $pattern can have an /e modifier. The existing ways still work, but under PHP 5.5, they trigger warnings for deprecated feature.
* Markup_e($name, $when, $pattern, $replace);
** $pattern cannot have an "/e" modifier
** $replace can be a string with program code to be evaluated; note that the matches can be accessed with $m[1], $m[2] instead of '$1', '$2'
** $replace can be a function name (callback) which will be called with the array of matches as argument (PmWiki 2.2.59+).
Examples:
* For PHP 5.4 and older, this is acceptable:[@
Markup('randomargs', 'directives',
'/\\(:random (\\d+) (\\d+):\\)/e',
"rand('$1', '$2')"
);@]
* For PHP 5.5 and newer, $replace is code, we call Markup_e():[@
Markup_e('randomargs', 'directives',
'/\\(:random (\\d+) (\\d+):\\)/',
"rand(\$m[1], \$m[2])"
);@]
The array $m contains the matches in parentheses from the $pattern. The matches \$m[1] have a backslash before the $ sign to not be evaluated in the double-quoted string. %note% This will also work in PHP 5.4 and older%% but requires PmWiki 2.2.58 or newer.
* For PHP 5.5 and newer, $replace is callback, we call Markup():[@
Markup('randomargs', 'directives',
'/\\(:random (\\d+) (\\d+):\\)/',
"MyRandom"
);
function MyRandom($matches) {
return rand($matches[1], $matches[2]);
}
@]
%note% This will also work in PHP 5.4 and older%% but requires PmWiki 2.2.58 or newer.
Other example:
* PHP 5.4 or older: [@
Markup('Maxi:','