Exercise—an evil functionless plugin

You may not be used to writing your own functions in your code, especially for trivial tasks. However, when you are writing WordPress plugins, it is virtually impossible to get away with having all your code naked in the main code block. Let's take a closer look at how WordPress works and you will see why you need to shepherd your code into functions.

Normal users will use the Add New button in the Dashboard to search the WordPress repository for published plugins, but we as developers will be creating our own plugins from scratch. To do this, all we need is our trusty text editor (and our FTP client to upload it to the web server, if you're running WordPress remotely).

This exercise will illustrate how not to code a plugin:

You will see the text you printed at the top of every page on your site, including your home page! This obnoxious text appears before the opening HTML and DOCTYPE tags.

What just happened

This is a pretty simple script, so why did everything explode? If you already know the answer, keep quiet for the folks who are still figuring this out. The answer will help keep you out of trouble when writing PHP code.

Before we go any further, if you did not see the PHP errors, then you really need revisit the previous chapter on setting up your environment and debugging. This will be your last reminder.

Now, to answer the question of all those header errors—what's going on? The whole point of using a hook is to have your function executed at a certain time. When you include a file, its code is parsed and any code not inside classes or function-blocks gets executed (whereas the classes and functions are merely loaded). The problem here revolves around PHP's header() function, which WordPress is using to declare the content type of its output—for example, the scripts generating the main pages use the text/HTML content type, whereas the scripts generating the RSS feeds use an RSS/XML content type.

All you really need to understand here is that the header() function must be called before any output is sent. From PHP's documentation:

It also warns that header errors are common when using include() or require() functions. A brief analogy is seen when you mail a letter—you must address the envelope before you drop it into the mailbox.

Consider the following two scripts:

Example 1

<?php
header('Content-type: text/plain');
print "Headers come first.";
/* End of File */

Example 2

<?php
print "This will raise a warning.";
header('Content-type: text/plain');
/* End of File */

The first example works normally—if you uploaded this to the root of your website and named it test.php, then loaded it in your browser (for example, http://yoursite.com/test.php), you would see the printed text. However, the second example generates the now familiar PHP warning: Cannot modify header information. It's as if you are trying to change the address on your letter after you posted it.

Back in our "Bad Example" plugin, this is exactly what was happening. The print statement was executed when the file was included, and this jumped the gun on the header() function, even though the code was otherwise syntactically correct. Our "Bad Example" is, in fact, a good example of what not to do. This should help drive home the point that you must define your own functions in order to write WordPress functions—you cannot simply put naked code into your plugin file.

Omitting the closing "?>" PHP tag

So why do we omit the closing tag in our plugins? PHP will automatically terminate a file with a closing ?> tag if needed, but we're not just being lazy here. The reason is predicated on our discussion about headers—if your plugins have any trailing whitespace after the closing ?>, it gets interpreted in the same way as if you had printed something, and that can cause the same header warnings. Look closely at the following example. Notice the extra lines after the closing PHP tag?

It is exceedingly difficult to spot extra newlines or spaces when debugging a script, so we omit the closing PHP tags whenever possible simply because they may trigger header errors. It is helpful to include a comment at the end of the file, such as /*End of File*/ or simply /*EOF*/ just as a reminder that yes, the omission is intentional and not the result of a corrupted file.

A better example: Adding functions

Now that we know what we can't simply print data directly from our plugin's main block, let's fix our example to make it a bit more like the "Hello Dolly" plugin:

<?php
/*
Plugin Name: Better Example
Plugin URI: http://wordpress.org/#
Description: Undoing the Madness
Author: Everett's sometimes obnoxious Twin
Version: 0.7
Author URI: http://theonion.com/
*/

function safe_print() {
   print " -------- I think I'm getting a clue!";
}

/* End of File */

What's different about this example? This version of our plugin isolates the print statement inside a function block so that it does not execute immediately once the file is loaded. If you change the code in your sample plugin and save it, the warnings caused by the previous version of this plugin should disappear once you refresh the page. This gets us out of trouble, but it doesn't get our statement printing and visible just yet. To do that, we must add a hook to trigger execution of our function.