The basics

Textpattern plugins are written in PHP. They’re not stored as plain PHP source files; rather, they’re “compiled” into a chunk of base64-encoded text, to allow for easy installation and minimize corruption problems.

A compiled plugin looks something like this:

# ..........................................................
 # This is a plugin for Textpattern - http://textpattern.com/
 # To install: textpattern > admin > plugins
 # Paste the following text into the 'Install plugin' box:
 # ..........................................................
YTo5OntzOjc6InZlcnNpb24iO3M6MzoiMC4xIjtzOjY6ImF1dGhvciIa7
b2xkIFN0YXRlIjtzOjEwOiJhdXRob3JfdXJpIjtzOjI2OiJodHRwOi8vd
dGUuY29tLyI7czoxMToiZGVzY3JpcHRpb24iO3M6MjI6IlNpbXBsZSj3e
ZXMiO3M6NDoidHlwZSI7aToxO3M6NDoibmFtZSI7czoxODoiemVtY8thl
..etc..

As the instructions suggest, users install plugins by pasting the encoded text into a form on their admin > plugins page. The copy-paste method is used to avoid file upload restrictions on some servers. The base64 encoding eliminates errors caused by accidental word-wrapping, line end differences, and so on.

Loading

When a plugin is installed, Textpattern decodes it and stores the unencoded PHP source in a MySQL table. Each time a Textpattern page is loaded, all active plugins are fetched from the table and evaluated before the page rendering begins. (It’s also possible to store plugins in regular files; we’ll get to that later)

This is mostly transparent to the developer and user. Except for some quirks during debugging, you can think of the process as analagous to include().

The Plugin Template

There’s more than one way to create a Textpattern plugin, but I’d suggest you get comfortable with the Plugin Template method right from the start. The template has several advantages over other methods:

• You can use a syntax-highlighting editor to write your PHP code
• Fatal PHP errors will be detected at compile-time
• You can configure Textpattern to load uncompiled plugin source files directly, for quick and easy testing
• Plugin help can use Textile formatting

You can download a copy of the template from threshold state.

The template contains two main files:

zem_tpl.php – this is the “compiler”. You don’t run it directly, but it includes the functions necessary to convert a plugin source file into a base64-encoded install file.

zem_plugin.php – this is template itself. To create a new plugin, you’ll start by making a copy of this file, and adding your PHP source in the appropriate place.

It’s important to realise that the plugin template doesn’t need a copy of Textpattern in order to function. You can use the compiler on any machine with a basic PHP installation – either on your local desktop PC, or on a web server. (If you intend to run the plugin template compiler on the same web server as your Textpattern web site, make sure you install it in a separate directory, away from Textpattern).

If you want to compile plugins on your desktop machine, you’ll need to install PHP. Don’t worry about MySQL or other fancy extensions, they’re not required to compile a plugin. In fact, you don’t even need a web server – you can use the PHP command line interface to run the compiler and produce a plugin.

Installing and configuring PHP is outside the scope of this article. If you need help, start with the PHP installation guide. From this point on I’ll assume you have a working copy of PHP installed. You can test whether the command line interface is working with the following command, which should display the PHP version number and copyright notice:

$ php -v

If you can’t or won’t use the command line, you can compile plugins using a web server. More on that below.