In Expression Engine Escaping Madness I laid out an issue I was experiencing with a client site. The issue was that there didn’t appear to be a method available to escape Expression Engine markup when it is mixed with php so there is a definite risk of parse errors using that technique (it’s not a security issue or anything; I want to be clear on that). This made me nervous enough that I couldn’t let it go and kept thinking about how to get around the issue. The answer: write an Expression Engine plugin. Of course this meant I had to actually learn how to write an Expression Engine plugin first. Here are my notes 😊

First though credit where it’s due: for this example I used the number_format plugin as a base so a lot of credit goes to Robert Wallis for the nicely written plugin I’m basically leaching from:)

An Expression Engine plugin is essentially a php class with at least one method that translates into an Expression Engine tag and used inside of Expression Engine templates (I don’t think they can be used inside of entries directly though I haven’t confirmed this). They are best left for small tasks though because they can’t have an administrative backend or integration with the Expression Engine l10n stuff or form processing or any manageable settings. No fun stuff for plugins…

Like most platforms there’s a few conventions that have to be followed but, also like most platforms, they aren’t too troublesome to work with. It should be noted that the syntax for the class uses the php4 syntax so dumb yourself down accordingly.

For example our plugin class will look like:

<?php
class Add_Slashes
{
	function Add_Slashes()
	{
 
        }
}

And the plugin will be executed with the below Expression Engine template tag:

{exp:add_slashes}O'Reilly{/exp:add_slashes}

Now, it’s possible to create template tags that aren’t done in pairs but for this example I’m going to stick with pairs. In case it wasn’t obvious, if you wanted to have a plugin that has more than a single method you would call that method like:

{exp:add_slashes:somethingelse}O'Reilly{/exp:add_slashes:somethingelse}

So that’s the basic syntax. The next thing that needs to be done is that a file has to be created inside the “/system/plugin/” folder. Note that I’m using the default name for that folder (system) so if you renamed it during the installation process use that instead. The file name must be lower case the same as the class name and it must have pi. as the prefix, and begin with the second segment of the tag. So, with our example plugin, the plugin name would be: pi.add_slashes.php. Simple enough. Once the file is saved to the location the plugin is installed. That’s how Expression Engine rolls.

Now we have a working plugin in theory but if you go into the plugin manager you’ll see an error about a missing variable as well as a distorted view of the page. We’re missing something; the $plugin_info array.

Every Expression Engine plugin should have a variable outside of the class called $plugin_info. For our example it should look like the below:

<?php
$plugin_info = array(
	'pi_name'        => 'Add Slashes',
	'pi_version'      => '1.0',
	'pi_author'       => 'Eric Lamb',
	'pi_author_url'  => 'http://blog.ericlamb.net/',
	'pi_description' => 'Exposes PHP\'s <a href="http://php.net/manual/en/function.addslashes.php">addslashes()</a> function via EE tags.',
	'pi_usage'        => Add_Slashes::usage()
);
?>

Obviously, the above lists all the details about the plugin for display in the plugin administration module:

You may have noticed the pi_usage key in the array; this method is recommended by the Expression Engine Developer Center for describing the usage of a plugin. Inside the plugin create a method called usage() and just return the instructions. Those instructions will be used on the plugin description page:

Using all of the above the completed plugin is below:

<?php
$plugin_info = array(
	'pi_name'        => 'Add Slashes',
	'pi_version'      => '1.0',
	'pi_author'       => 'Eric Lamb',
	'pi_author_url'  => 'http://blog.ericlamb.net/',
	'pi_description' => 'Exposes PHP\'s <a href="http://php.net/manual/en/function.addslashes.php">addslashes()</a> function via EE tags.',
	'pi_usage'        => Add_Slashes::usage()
);
 
class Add_Slashes
{
	function Add_Slashes()
	{
		global $TMPL;
		$this->return_data = addslashes($TMPL->tagdata);
        } 
 
	function usage()
	{
		return "This is really just a wrapper for PHP's add_slashes function:
http://php.net/manual/en/function.addslashes.php
 
&#123;exp:add_slashes&#125;
O'Reilly
&#123;/exp:add_slashes&#125;
returns: O\'Reilly
 
";
	} 
 
}

Now, this example was used using Expression Engine 1.6.9 so the process might not work for the upcoming 2.0 (I haven’t looked into that version just yet). It also doesn’t look like EllisLabs is accepting any new submissions to their plugin library so if you’re hoping to distribute your plugin prepare to do it solo and without any help from them.

Still, an easy enough process that any custom functionality you may need for an Expression Engine site should be trivial to achieve. 

UPDATE February 21, 2011
I completely forgot to include any info on customization through passing parameters. Note: this is totally cribbed from the ExpressionEngine forums.

{exp:add_slashes return="FALSE"}
O'Reilly
{/exp:add_slashes}

Doing the above will create a variable within the plugin called “return” which can be accessed like:

<?php
global $TMPL;
$return = $TMPL->fetch_param('return');
?>