I’m just wrapping up a relatively large project centering around a Wordpress plugin. I’ve gotten a chance to explore the API in depth, and have discovered a lot of nice things and a lot of not-so-nice things. One of the not-so-nice things was the way plugin activation is handled…it is assumed that, assuming no fatal errors occur, that a plugin was activated properly every time. There’s no feedback mechanism, no way to pass back a message saying “woa, something’s wrong here”. So I wrote my own.

It’s a pretty simple concept with some neat implications. Here’s what normally happens when you activate a plugin:

1. Wordpress sends you to the current with action=activate to activate the plugin
2. On that page, wordpress sets a redirect header to the current page with error=true
3. Wordpress includes your plugin file. If your plugin has a fatal error here, the script dies after sending the redirect header, so it redirects back to the current page with error=true. Since the plugin hasn’t actually been activated yet, Wordpress doesn’t try loading the plugin anymore, but instead shows an error message and includes an iframe for the current page with action=error_scrape. On this loading of the page the script will include the plugin again, this time actually outputting the errors it gives.
4. Assuming the plugin doesn’t cause a fatal error, the system (in this order) activates the plugin, calls the plugin’s activation hook, and overrides the previous redirect to a happy “Plugin activated” page.

Knowing this, it’s pretty easy to use it to our advantage. All we have to do is set an option to record our error and throw an E_USER_ERROR, which is the same thing as an E_ERROR, only we’re allowed to throw it mid-script. Then, when the script is loaded again to display this “fatal” error, we can display our error. Since we threw the error after the plugin was activated, it’s important (in most cases) that we deactivate ourselves.

The end result? A customizable plugin error message. Pretty neat IMHO.