Wordpress - coding standards for plugins

Inspired by writing plugins for Wordpress'a made the rules of good tone ...

Naming convention

Where does the plugin begin - with the name :), therefore let's work out the rules for naming plugins:

• We do not use stupid prefixes like wp_ or wp- - we already know that the files in the http://wordpress.org/extend/plugins/ directory are intended for wordpress
• If you want to highlight your plugin - add the original prefix / postfix (I use the prefix (a) - I really don’t know how informative this is)
• All names of classes and functions must contain the name of your plugin - in order to avoid conflicts

')
Always create a directory with a plugin, even if it consists of a single file, you may want to expand the functionality in the future, and now you can’t do with one file, and create a directory - and this can introduce users into a stupor ...

readme.txt

Each plug-in is required to have a readme.txt file , see the syntax description http://daringfireball.net/projects/markdown/syntax . You can check your creation using a validator .

If for some reason you don’t upload your plugin to the wordpress repository, then in any case create this file - many will say thank you.

Headline

This is a mandatory element of the plugin, do not pervert much in it:

<? php
/ *
Plugin Name: Name Of The Plugin
Plugin URI: http: // URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, eg: 1.0
Author: Name Of The Plugin Author
Author URI: http: // URI_Of_The_Plugin_Author
* /
?>

Coding Standards

I did not see full standards from developers - for this reason I use Zend Framework standards , which I advise you to do. (in the examples I will not use comments for PHP Documentator - in order to shorten the listing of sorts).

And yet - our plugin should not cause errors (even the level of Notice ), so that during the development turn on the error display:
error_reporting(E_ALL);

Dynamic file uploading

Load the whole plugin at once, then hang all the atsuk hooks and do nothing - this behavior of plug-ins is common, let's be smarter, for a start it is desirable to remove all the functionality of classes and files, and already in the functions load the necessary files:

// add content filter
add_filter ( 'the_content' , array ( '% PluginName%' , 'the_content' ) , 1000 ) ;

class % PluginName % {

var $ some_variable ;

/ **
* filter fo the_content
*
* @return void
* /
function the_content ( $ content )
{
include_once 'class / Content.php' ;
$ Content = new % PluginName % _Content ( ) ;
return $ Content -> parseContent ( $ content ) ;
}
}

It is also desirable to hang the hooks separately for each state - see the list :

if ( is_admin ( ) ) {
// hooks for admin
} else {
// hooks for front end
}
// and so on ...

You can even like this:

if ( is_admin ( ) ) {
include_once '% PluginName% _admin.php' ;
} else {
include_once '% PluginName% _front.php' ;
}
// and so on ...

Variables and Namespaces

Since the namespace in PHP has not yet been implemented (meaning stable versions), a static class that combines all functions for hooks will help us with this task:

add_action ( '% hook_name%' , array ( '% pluginName%' , '% hook_name%' ) ) ;

class % PluginName % {

var $ some_variable ;

/ **
* some function description
*
* @return void
* /
function % hook_name % ( )
{
// ...
}
}

Or the usual class:

// create the essence of our class
$ PluginName = new % PluginName % ( ) ;

add_action ( '% hook_name%' , array ( $ PluginName , '% hook_name%' ) ) ;

class % PluginName % {

var $ some_variable ;

/ **
* some function description
*
* @return void
* /
function % hook_name % ( )
{
// ...
}
}
// delete the variable as unnecessary
unset ( $ PluginName ) ;

When using the options table (these are the add_option , update_option , delete_option functions ), you should also use the prefix from the plugin name, so we will emulate the namespace of our options (for some reason the developers did not know this before) I don’t know)

Following these tips we will avoid conflicts with other plugins ...

Plug-in installation

To initialize the system, there is the register_activation_hook hook, using it you can make the necessary changes to the database (create tables, make changes to options, etc.). Believe me - the user does not always read the readme.txt where it will be written that it is necessary after initialization, it is necessary to save the plugin settings so that the default values ​​are saved in the database ...

Plugin settings

Let's not break the beautiful Wordpress admin panel - the plugin settings should be located in the appropriate menu - Settings » % Plugin Name% .

I also advise you to put the settings page into a separate file with an informative name (for example, % PluginName% _options.php or % PluginName% _settings.php ):

if ( is_admin ( ) ) {
add_action ( 'admin_menu' , array ( '% PluginName%' , 'adminMenu' ) ) ;
}

class % PluginName % {
function adminMenu ( )
{
if ( function_exists ( 'add_options_page' ) ) {
add_options_page ( '% PluginName%' , '% PluginName%' , 'manage_options' , '% PluginName% /% PluginName% _options.php' ) ;
}
}
}

For everything to be beautiful - use the styles specified in wp-admin / wp-admin.css - they will thank you for this approach ...

Deactivating the plugin

If you make any changes to the database or on the file system when installing the plug-in, then it is advisable to clean this up after the plug-in is turned off, the register_deactivation_hook hook will help you with this.

Customization

Add CSS and JavaScript using the following construction:

// register our CSS file
wp_register_style ( '% PluginName%' , get_option ( 'siteurl' ) . '/wp-content/plugins/%PluginName%/%PluginName%.css' ) ;
// either
wp_enqueue_style ( '% PluginName%' , get_option ( 'siteurl' ) . '/wp-content/plugins/%PluginName%/%PluginName%.css' ) ;

// register our JS file (with dependencies)
wp_register_script ( '% PluginName%' , get_option ( 'siteurl' ) . '/wp-content/plugins/%PluginName%/%PluginName%.js' , array ( 'jquery' ) ) ;
// either
wp_enqueue_script ( '% PluginName%' , get_option ( 'siteurl' ) . '/wp-content/plugins/%PluginName%/%PluginName%.js' , array ( 'jquery' ) ) ;

This method will work fine if these methods are located in a hook on wp_head or admin_head , otherwise you will have to call the wp_print_styles or wp_print_scripts method yourself and pass the script name for output to them ...

Also, do not forget about conflicts, how to get around them in the article How to load JavaScript in WordPress plugins

If your plugin has some kind of graphic design - and it usually changes for a specific theme - then it is advisable to check for the presence of a CSS file for our plugin in the current theme directory:

if ( file_exists ( TEMPLATEPATH . '/%PluginName%.css' ) ) {
wp_register_style ( '% PluginName%' , get_bloginfo ( 'template_directory' ) . '/%PluginName%.css' ) ;
} else {
wp_register_style ( '% PluginName%' , get_option ( 'siteurl' ) . '/wp-content/plugins/%PluginName%/%PluginName%.css' ) ;
}

When creating the CSS, be very careful, your CSS file should not break the current design, so again - use either prefixes or a hard link:

.% PluginName% -sidebar { /*...*/ }
#% PluginName% { /*...*/ }
#% PluginName% > div { /*...*/ }

You shouldn't forget that the CSS theme file of the current theme can influence the appearance of your plugin - so I advise you to clean up the margins, paddings and borders ...

With such simple tricks we make life easier for ourselves and designers ...

Multilingual

You do not plan to do multilingualism, but then let others help you, prepare the plugin for translation, it will be enough to create a localization file containing only your language, and use the following functions to display the text:

__ ( 'String' , '% PluginName%' ) ;
_e ( 'String' , '% PluginName%' ) ;
_c ( 'String' , '% PluginName%' ) ;
__ngettext ( 'String' , 'Strings' , $ c , '% PluginName%' )

Translation files should also be placed in a separate language directory - so as not to clutter up the root directory of the plugin ...

For more information, see the I18n for WordPress Developers page .

Documentation

If the user is required to make changes to the current theme - then it is desirable to describe this process in great detail - and not as usual: “This code will output what you want.”

By the way, “this code here” should not cause errors if your plugin is disabled, so do not forget to frame function calls with the following construction:

<? php
if ( function_exists ( '% FunctionName%' ) ) {
% FunctionName % ( ) ;
}
?>

Remember - the end user is often not a programmer, and he needs to chew everything and put it in his mouth ...

Compatibility

Unfortunately, Wordpress positions itself as a system with PHP4 support, so if you use PHP5, it is better to inform the user in advance at the stage of enabling the plugin, or create a file to ensure compatibility (if you use only specific functions):

// connect in the plugin file
if ( version_compare ( phpversion ( ) , '5.1.0' , '<' ) ) {
requery_once '% PluginName% _compatibility.php'
}

// what could be in the file
if ( ! function_exists ( 'array_diff_key' ) ) {
function array_diff_key ( )
{
$ args = func_get_args ( ) ;
return array_flip ( call_user_func_array ( 'array_diff' ,
array_map ( 'array_flip' , $ args ) ) ) ;
}
}

In order not to reinvent the bicycle - I advise you to look at the package PEAR PHP_Compat .

It is likely that you may also need support for old Wordpress versions:

// connect in the plugin file
if ( version_compare ( get_bloginfo ( 'version' ) , '2.6.0' , '<' ) ) {
requery_once '% PluginName% _compatibility.php'
}

findings

Let you down total.

The plugin directory might look like this:

\plugin-name
|--\languages
|--\library
|--\javascript
|--\css
|-- plugin-name.php
|-- plugin-name_admin.php
|-- plugin-name_front.php
|-- plugin-name_settings.php
|-- plugin-name_compatibility.php
|-- readme.txt


• % PluginName% prefix is ​​optional, and with a large number of files it is even redundant
• languages ​​- all translations will be here
• library - directory for third-party libraries
• javascript and css - contain javascript and css files for your plugin
• readme.txt - required
• the functionality is divided into several files (admin.php, front.php, single.php, etc.)
• version compatibility is provided (compatibility.php)

PS If you have something to add, or there is a link to useful resources on the topic - you are welcome in the comments ...

In preparing the material were used the following resources:

• Wordpress Developer Documentation
• Suggestions For Plugin Standards
• WordPress Developer's Toolbox

For highlight syntax code used resource highlight.hohli.com