Understanding Plugin Structure

All that is required for WordPress to see a plugin is a PHP file in the wp-content/plugins directory of the site with some special information at the top of the file. This information at the top of a plugin file, typically referred to as a plugins header, is what WordPress looks for when determining which plugins are installed on the site. A freshly installed WordPress site makes a good starting point to understand how this works in practice.

Inspecting WordPress's default plugins

WordPress installs with two plugins by default: Akismet and Hello Dolly. Looking at the files for each of these plugins will help you understand how you can structure your own plugins.

Inside a fresh WordPress site's wp-content/plugins directory, you find a directory named /akismet and two files named hello.php and index.php. The hello.php file is for the Hello Dolly plugin and has the following text at the top of the file.

<?php
/**
 * @package Hello_Dolly
 * @version 1.5.1
 */
/*
Plugin Name: Hello Dolly
Plugin URI: http://wordpress.org/#
Description: This is not just a plugin, it symbolizes the hope and
    enthusiasm of an entire generation summed up in two words sung most
    famously by Louis Armstrong: Hello, Dolly. When activated you will
    randomly see a lyric from <cite>Hello, Dolly</cite> in the upper
    right of your admin screen on every page.
Author: Matt Mullenweg
Version: 1.5.1
Author URI: http://ma.tt/
*/

The section in bold is the plugin header, which tells WordPress about the plugin. If this section is removed, the Hello Dolly plugin will no longer be available because WordPress no longer recognizes it as a plugin. The Plugin Name, Plugin URI, and Description sections of the plugin header are referred to as fields. We discuss the fields and their use in Chapter 6 of this minibook.

Open the index.php file in the /wp-content/plugins/ folder and you see the following few lines of code:

<?php
// Silence is golden.
?>

Because this file doesn't have a plugin header, it isn't a plugin. It's in the plugins directory to prevent people from going to domain.com/wp-content/plugins (where domain.com is your site's domain name) to get a full listing of all the plugins on your site. Because the index.php file doesn't output anything, people trying to get a listing of your plugins will simply see a blank screen.

All that remains now in the /wp-content/plugins directory is the /akismet directory. Inside this directory are three PHP files: admin.php, akismet.php, and legacy.php. If you open up each file, you will see that only the akismet.php file contains the plugin header.

/*
Plugin Name: Akismet
Plugin URI: http://akismet.com/
Description: Akismet checks your comments against the Akismet Web service
    to see if they look like spam or not. You need an <a href=”http://
    akismet.com/get/”>API key</a> to use it. You can review the spam it
    catches under “Comments.” To show off your Akismet stats just put
    <code>&lt;?php akismet_counter(); ?&gt;</code> in your template. See also: <a href=”http://wordpress.org/extend/plugins/stats/”>WP Stats
    plugin</a>.
Version: 2.4.0
Author: Automattic
Author URI: http://automattic.com/wordpress-plugins/
License: GPLv2
*/

Because the akismet.php file has the plugin header, the /akismet directory is recognized by WordPress as a plugin. If the akismet.php file is removed, the Akismet plugin disappears from the listing of available plugins in your WordPress installation (DashboardPlugins).

Looking at the setup of these two default plugins tells you two very important things about the way that a plugin is structured.

• The file that has the plugin header can be in the plugins directory by itself or contained in a directory inside the plugins directory.
• The plugin header follows a standard format.

Knowing the requirements

Looking at the way the default plugins are set up gives you an idea of how to set up your plugins, but knowing all the requirements would be nice so you don't make mistakes. The reality is that there are very few requirements on how you must set up your plugin.

Requirement 1: Plugin header

The plugin header is what allows WordPress to recognize your plugin. Without this key piece of information, your plugin will not show up as an available plugin and you will be unable to activate it.

While there are many fields in the plugin header, only Plugin Name is required. For example, the following is a valid plugin header.

/*
Plugin Name: Example Plugin
*/

Of course, providing additional information can be very helpful, but if you're quickly making a plugin for yourself, the plugin name is all that is required.

Requirement 2: Correct placement of main plugin file

The main plugin file (the one with the plugin header) must be either in the /wp-content/plugins directory or inside a directory immediately inside the /wp-content/plugins directory.

Examples of valid locations for the main plugin PHP file:

• wp-content/plugins/example.php
• wp-content/plugins/example/example.php

Examples of invalid locations for the main plugin PHP file:

• wp-content/example.php
• wp-content/plugins/example/lib/example.php

You cannot place the main plugin file too deep. WordPress will only look in the /wp-content/plugins directory and inside the first level of the directories contained in /wp-content/plugins, but no deeper.

Following best practices

The requirements are very lax and allow you to set up your plugin any way you want. You can name the main plugin file and plugin directory anything you like. You can even put multiple main plugin files inside a single directory. However, just because you can, doesn't mean that you should. The following are some best practices to help keep some consistency.

Best Practice 1: Always use a plugin directory

Hello Dolly doesn't reside in a directory because it's simple enough to need only one file. However, all plugins should reside in their own directory, even if they need only one file.

When creating a plugin, a single file may be enough to do what you need, but further development may require adding more files. It is better to start with the plugin in a directory instead of restructuring it later.

Do yourself and any users of your plugin a favor and always place your plugins inside a directory.

Best Practice 2: Use meaningful, unique names

When doing any WordPress development (whether for a plugin or theme), you must always keep in mind that your code shares space with code from other people (other plugin developers, WordPress core developers, theme developers, and so on). This means that you should never use simple names for anything; the name of your plugin should be unique.

You might think that naming your plugin “Plugin” allows you to move past the boring stuff and onto development, but it just makes things difficult to keep track of. If your plugin produces a widget that displays a listing of recent movie reviews, “Michael Torbert's Movie Reviews Widget” is much more meaningful than “Widget Plugin.”

Best Practice 3: Match the plugin and plugin directory names

Make sure that your plugin's directory name makes it easy to find the plugin in the /wp-content/plugins directory.

Going with the preceding example, having Michael Torbert's Movie Reviews Widget in a widget directory will make finding the widget difficult. The directory name doesn't have to match exactly, but it should make sense. Some good directory names for this example are /movie-reviews-widget, /mt-movie-reviews-widget, or /movie-reviews.

Best Practice 4: Don't use spaces in directory or filenames

Although modern desktop operating systems can handle directories and files that have spaces in the name, some Web servers can't. A good practice is to use a hyphen (-) in place of a space when naming files and directories. In other words, use movie-reviews-widget rather than movie reviews widget.

Avoiding spaces in file and directory names will save you many headaches.

Best Practice 5: Consistent main plugin filenames

Although you can name the plugin main file anything, coming up with a consistent naming scheme that you use throughout your plugins can be a good idea.

The most popular naming scheme is to match the main plugin PHP filename to the plugin directory name. For example, the main plugin file for a plugin directory called /movie-reviews is movie-reviews.php. The problem with this naming scheme is that it doesn't mean anything. Plugin filenames should always indicate the plugin's purpose. The purpose of the movie-reviews.php file is clearer when you know that many developers name the main plugin file the same as the plugin directory.

Another naming scheme is to use a consistent filename across all plugins. For example, naming the main plugin file init.php indicates that the file is used to initialize the plugin (init is the abbreviation for initialize). The name init.php makes the purpose of the file clear regardless of the plugin name or purpose.