Languages: English • العربية • বাংলা • Español • Italiano • a Plugin 日本語 한국어 • Português do Brasil • Русский • ไทย • 中文(简体) • (Add your language)
WordPress Plugins allows you to easily modify, customize, and enhance a WordPress site. Instead of changing the core program code of WordPress, you can add functionality with WordPress Plugins. Here is a basic definition.
A WordPress Plugin is a program or a set of one or more functions written in the PHP scripting language, that adds a specific set of features or services to the WordPress site. You can seamlessly integrate a plugin with the site using access points and methods provided by the WordPress Plugin Application Program Interface (API).
Wish that WordPress had some new or modified functionality? The first thing to do is to search various WordPress Plugin repositories and sources to see if someone has already created a WordPress Plugin that suits your needs. If not, this article will guide you through the process of creating your own WordPress Plugin.
This article assumes you are already familiar with the basic functionality of WordPress and with PHP programming.
Resources
This section of the article goes through the steps you need to follow – and some things you need to consider – when creating a well-structured WordPress Plugin.
The first task in creating a WordPress Plugin is to think about what the Plugin will do, then choose a (preferably unique) name for your Plugin. Check out the Plugins page (and the other repositories linked there) to verify that your name is unique. You could also do a Google search on your proposed name. Most Plugin developers choose to use names that describe what the Plugin does: for instance, a weather-related Plugin would probably have the word "weather" in the name. The name can be made up of multiple words.
The next step is to create a PHP file with a name derived from your chosen Plugin name. For instance, if your Plugin is going to be called "Fabulous Functionality", you might call your PHP file fabulous-functionality.php. People who install your Plugin will be putting this PHP file into the WordPress Plugins directory in their installation – usually wp-content/plugins/ – so no two Plugins in that directory can have the same PHP file name.
Your Plugin filename should also be unique so that your Plugin will not conflict with another in the Plugin Repository. A good solution is to use your name or the name of your company as a prefix, without spaces or special characters –for example, mycompanyname-fabulous-functionality.php.
Your WordPress Plugin must have at least one PHP file; it could also contain JavaScript files, CSS files, image files and language files. If there are multiple files, pick a unique name for a directory and a name of your choice for the main PHP file. (This file name is often, but not essentially, the same as the directory name.) Example directory and file names could be mycompanyname-fabulous-functionality and mycompanyname-fabulous-functionality.php respectively. Put all your Plugin's files into the directory you've created and tell your Plugin users to upload the whole directory to wp-content/plugins/.
If you use a directory to contain your Plugin files, then the directory name will be used by WordPress when checking the WordPress Plugin Repository for updates. If your plugin only consists of a single PHP file, then the file name will be used. If WordPress tells you that a newer version of your Plugin is available, but you know nothing about a newer version, beware. It's possible that another Plugin with the same directory name or file name is in the Plugin Repository, and it's this one which WordPress is seeing.
A WordPress installation can be configured so that the standard Plugin directory is changed from wp-content/plugins/, so you must use plugin_dir_path() and plugins_url() for absolute paths and URLs within your PHP code. For more details see Determining Plugin and Content Directories.
In the rest of this article, "the Plugin PHP file" refers to the main Plugin PHP file: whether it's directly in the wp-content/plugins/ directory, or in a sub-directory.
Security Note: Consider blocking direct access to your plugin PHP files by adding the following line at the top of each of them. Also, be sure to refrain from executing sensitive standalone PHP code before calling any WordPress functions.
This can be achieved in a few ways. You can either check to see if the ABSPATH
constant is defined, or check if a function such as add_action
exists. Either method can be used to ensure PHP execution is only allowed when it is included as part of the core system.
defined( 'ABSPATH' ) or die( 'No script kiddies please!' );
If you want to host your Plugin on https://wordpress.org/plugins/, you need to create a readme.txt file within your plugin directory in a standardized format. You can use the automatic plugin 'readme.txt' generator.
The WordPress plugin repository uses the "Requires" and "Tested up to" versions from the readme.txt in the stable tag.
It is very useful for users of the Plugin if you create a web page to act as a source of information for your WordPress Plugin. This page should describe how to install the Plugin, what it does, what versions of WordPress it is compatible with, what has changed from version to version of your Plugin, and how to use the Plugin.
Now it's time to put some information into your main Plugin PHP file.
Read about this in the plugin developer handbook.
Read about this in the plugin developer handbook.
Next, it's time to make your Plugin actually do something. This section contains some general ideas about Plugin development and describes how to allow your Plugin to accomplish several tasks.
Many WordPress Plugins accomplish their goals by connecting to one or more WordPress Plugin "hooks". The way Plugin hooks work is that at various times while WordPress is running, WordPress checks to see whether any Plugins have registered functions to run at that time. If so, then these functions are run. These functions modify the default behavior of WordPress.
For instance, before WordPress adds the title of a post to browser output, it first checks to see if any Plugin has registered a function for the "filter" hook called "the_title". If so, the title text is passed in turn through each registered function and the final output is the end result of any and all of these registered functions. If your Plugin needs to add some information to the printed title, it can register a special function which is called when the "the_title" filter is called.
Another example is the "action" hook "wp_footer". Just before the end of the HTML page generated by WordPress, this hook checks to see whether any Plugins have registered functions against it. If so, it runs them in turn.
You can learn more about how to register functions for both filter and action hooks – and what Plugin hooks are available in WordPress – in the Plugin API. If you find a spot in the WordPress code where you'd like to have an action or filter, but WordPress doesn't have one, you can also suggest new hooks. (Suggestions will generally be taken; see Reporting Bugs to find out how you can submit a suggestion.)
Another way for a WordPress Plugin to add functionality to WordPress is by creating custom Template Tags. Someone who wants to use your Plugin can add these "tags" to their theme, in the sidebar, post content section, or wherever it is appropriate. For instance, a Plugin that adds geographical tags to posts might define a template tag function called geotag_list_states() for the sidebar, which lists all the states posts are tagged with, with links to the state-based archive pages the Plugin enables.
To define a custom template tag, simply write a PHP function and document it for Plugin users on your Plugin's home page and/or in the Plugin's main PHP file. It's a good idea when documenting the function to give an example of exactly what needs to be added to the theme file to use the function, including the <?php and ?>.
Most WordPress Plugins will need to get some input from the site owner or blog users and save it between sessions, for use in its filter functions, action functions, and template functions. This information has to be saved in the WordPress database, in order to be persistent between sessions. There are four (4) methods for saving Plugin data in the database:
See Creating Options Pages for info on how to create a page that will automatically save your options for you.
WordPress has a mechanism for saving, updating, and retrieving individual, named pieces of data ("options") in the WordPress database. Option values can be strings, arrays, or PHP objects (they will be "serialized", or converted to a string, before storage, and unserialized when retrieved). Option names are strings, and they must be unique so that they do not conflict with either WordPress or other Plugins.
It's also generally considered a good idea to minimize the number of options you use for your plugin. For example, instead of storing 10 different named options consider storing a serialized array of 10 elements as a single named option.
Here are the main functions your Plugin can use to access WordPress options.
add_option($name, $value, $deprecated, $autoload);
get_option($option);
update_option($option_name, $newvalue);
Assuming that your Plugin has some options stored in the WordPress database (see section above), you will probably want it to have an administration panel that will enable your Plugin users to view and edit option values. The methods for doing this are described in Adding Administration Menus.
Once you have the programming for your Plugin done, another consideration (assuming you are planning on distributing your Plugin) is internationalization. Internationalization is the process of setting up software so that it can be localized; localization is the process of translating text displayed by the software into different languages. WordPress is used all around the world, so it has internationalization and localization built into its structure, including localization of Plugins.
Please note that language files for Plugins ARE NOT automatically loaded. Add this to the Plugin code to make sure the language file(s) are loaded:
load_plugin_textdomain('your-unique-name', false, basename( dirname( __FILE__ ) ) . '/languages' );
To fetch a string simply use __('String name','your-unique-name'); to return the translation or _e('String name','your-unique-name'); to echo the translation. Translations will then go into your plugin's /languages directory.
It is highly recommended that you internationalize your Plugin so that users from different countries can localize it. There is a comprehensive reference on internationalization, including a section describing how to internationalize your plugin, at I18n for WordPress Developers.
This section describes the necessary steps to update your Plugin when you host it on https://wordpress.org/plugins/, including details about using Subversion (SVN) with wordpress.org.
Assuming you have already submitted your Plugin to the WordPress Plugin Repository, over time you will probably find the need, and hopefully, the time to add features to your Plugin or fix bugs. Work on these changes and commit the changes to the trunk of your plugin as often as you want. The changes will be publicly visible, but only to the technically-minded people checking out your Plugin via SVN. What other users download through the website or their WordPress Plugin administration will not change.
When you're ready to release a new version of the Plugin:
Give the system a couple of minutes to work, and then check the wordpress.org Plugin page and a WordPress installation with your Plugin to see if everything updated correctly and the WordPress installation shows an update for your Plugin (the update checks might be cached, so this could take some time -- try visiting the 'available updates' page in your WordPress installation).
Troubleshooting:
This last section contains various suggestions regarding Plugin development.