I had a job that required creating a custom input filter for Drupal. It turns out to be pretty easy but I had a heck of a time finding documentation on it that made much sense to me so here’s my explanation of how to do it. The magic is all done by the PHP function preg_replace_callback() which takes as its arguments a regular expression (pattern) to search for, a callback function to take the stuff the expression finds and return you altered text to put in its place, and the big honking block of text to search through. So let’s start simple:

[cc lang=’php”]$text = preg_replace_callback(‘/hello/’, ‘_smallWorld’, $text);
function _smallWorld($match){
$world = ‘world’; return $world;
}[/cc]

All this will do is scan through $text and for each instance of hello with world. You can just use preg_replace for that. But it gets a lot more interesting when you start adding options to your regex like the very useful collapsible text module for Drupal:

[cc lang=’php”]function collapse_text_process($text) {
$text = preg_replace_callback(‘/
\[                     # look for an opening bracket collapse # followed by the word `collapse`
(\ collapsed)?         # followed by (optionally) a space and the word `collapsed` (captured)
(?:\ style=([^\] ]*))? # followed by (optionally) a space and a style, consisting of any # characters except a close bracket (captured)
(?:\ title=([^\]]*))?  # followed by (optionally) a space and a title, consisting of any # characters except a close bracket (captured)
\]                     # followed by a closing bracket (.+?)
# then capture as few characters as possible until \[\/collapse\]
# a closing “tag”, which is a slash followed by `collapse` in brackets
#and then after the regex delimiter, we’ll turn on 3 regex options
#s so dot matches all characters, m to match embedded newlines
#x so we can do free spacing and add these wonderful comments
/smx’, “_collapse_text_replace_callback”, $text);
return $text;
}[/cc]

We’ll pause a second to review that regex. What this means is that editors can do all sorts of things from the simple

[cc lang=’php”][collapse] hello world [/collapse][/cc]

to the complete

[cc lang=’php”][collapse collapsed style=yellow title=big news]
Hello World [/collapse][/cc]

The result is passed to your callback function, _collapse_text_replace_callback as an array. Element 0 is the full match. So

[cc lang=’php”]function _collapse_text_replace_callback($matches) {
global $base_url; $collapsed = ($matches[1] == ‘ collapsed’);
$style = trim($matches[2]); $title = trim($matches[3]);
$interior = $matches[4];
//the authors of this module do lots of cool stuff in here, check it out.
return drupal_render($form);
}[/cc]

So in the simple use case, the first element doesn’t contain collapsed so that’s false so do x. In the more complicated use, it does so do y. Likewise, the more complex use strings for $style, and $title.