WordPress:WordPress Coding Standards

Some legacy parts of the WordPress code structure for PHP markup are inconsistent in their style. WordPress is working to gradually improve this by helping users maintain a consistent style so the code can remain clean and easy to read at a glance.

Keep the following points in mind when writing code for WordPress, whether for core programming code, Plugins, or WordPress Themes. The guidelines are similar to Pear standards in many ways, but differ in some key respects.

Also see this post on the wp-hackers list.

There is also a page on proposed WordPress:Inline Documentation standards.

Single and double quotes

Use single and double quotes when appropriate. If you're not evaluating anything in the string, use single quotes. You should almost never have to escape HTML quotes in a string, because you can just alternate your quoting style, like so:

echo "<a href='$link' title='$linktitle'>$linkname</a>";
echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';

The only exception to this is JavaScript, which sometimes requires double or single quotes. Text that goes into attributes should be run through attribute_escape() so that single or double quotes do not end the attribute value and invalidate the XHTML and cause a security issue.

Indentation

Your indentation should always reflect logical structure. Use real tabs and not spaces, as this allows the most flexibility across clients.

Exception: if you have a block of code that would be more readable if things aligned, you can do initial indentation with tabs and then make up the difference with spaces:

[tab]$foo   = 'somevalue';
[tab]$foo2  = 'somevalue2';
[tab]$foo34 = 'somevalue3';
[tab]$foo5  = 'somevalue4';

Note how tabs are used for the initial indentation, and spaces are just used to make sure the equals signs line up.

Brace Style

Braces should be used for multiline blocks:

if ( condition ) {
    action1();
    action2();
} elseif ( condition2 && condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
}

Furthermore if you have a really long block, consider if it can be broken into two or more shorter blocks or function. If you consider such a long block unavoidable, please put a short comment at the end so people can tell at glance what that ending brace ends -- typically this is appropriate for a logic block, longer than about 35 rows, but any code that's not intuitively obvious can be commented.

single line blocks can omit braces for brevity:

if ( condition )
    action1();
elseif ( condition2 )
    action2();
else
    action3();

include_once vs. require_once

Learn the difference between include_once and require_once, and use each as appropriate. To quote the php manual page on include(): "The two constructs are identical in every way except how they handle failure. include() produces a Warning while require() results in a Fatal Error." Fatal errors stop script execution.

Regular expressions

Perl compatible regular expressions (PCRE, preg_ functions) should be used in preference to their POSIX counterparts.

No Shorthand PHP

Never use shorthand PHP start tags (<? ... ?> or <?=$var?>). Always use full PHP tags (<?php ... ?>). Make sure to remove trailing whitespace after closing PHP tag.

Space Usage

Always put spaces after commas and on both sides of logical and assignment operators like "x == 23", "foo && bar", "array( 1, 2, 3 )", , as well as on both sides of the opening and closing parenthesis of if, elseif, foreach, for and switch blocks (e.g. foreach ( $foo as $bar ) { ...). When defining a function, do it like so: function myfunction( $param1 = 'foo', $param2 = 'bar' ) { and when calling a function, do it like so: myfunction( $param1, funcparam( $param2 ) );

Formatting SQL statements

When formatting SQL statements you may break it into several lines and indent if it is sufficiently complex to warrant it. Most statements work well as one line though. Always capitalize the SQL parts of the statement like UPDATE or WHERE.

Functions that update the database should expect their parameters to lack SQL slash escaping when passed. Escaping should be done as close to the time of the query as possible, preferably by using $wpdb->prepare()

$wpdb->prepare() is a method that handles escaping, quoting, and int-casting for SQL queries. It uses a subset of the sprintf() style of formatting. Example :

$var = "dangerous'"; // raw data that may or may not need to be escaped
$id  = some_foo_number(); // data we expect to be an integer, but we're not certain

$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );

%s is used for string placeholders and %d is used for integer placeholders. Note that they are not 'quoted'! $wpdb->prepare() will take care of escaping and quoting for us. The benefit of this is that we don't have to remember to manually use $wpdb->escape(), and also that it is easy to see at a glance whether something has been escaped or not, because it happens right when the query happens.

Database Queries

Avoid touching the database directly. If there is a defined function that can get the data you need, use it. Database abstraction (using functions instead of queries) helps keep your code forward-compatible and, in cases where results are cached in memory, it can be many times faster. If you must touch the database, get in touch with some developers by posting a message to the wp-hackers mailing list. They may want to consider creating a function for the next WordPress version to cover the functionality you wanted.

Variables, functions, and operators

If you don't use a variable more than once, don't create it. This includes queries. Always use the wpdb Class of functions when interacting with the database.

Ternary operators are fine, but always have them test if the statement is true, not false. Otherwise it just gets confusing.

// GOOD example:
// (if statement is true) ? (do this) : (if false, do this);
$musictype = ('jazz' == $music) ? 'cool' : 'blah';

Another important point in the above example, when doing logical comparisons always put the variable on the right side, like above. If you forget an equal sign it'll throw a parse error instead of just evaluating true and executing the statement. It really takes no extra time to do, so if this saves one bug it's worth it.