Contents

Some 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 become clean and easy to read at a glance.Keep the following points in mind when writing PHP code for WordPress, whether for core programming code, plugins, or themes. The guidelines are similar to Pear standards in many ways, but differ in some key respects.

PHP #

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 quotes in a string, because you can just alternate your quoting style, like so:

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

An exception to this is JavaScript, which sometimes requires double or single quotes. Text that goes into attributes should be run through esc_attr() so that single or double quotes do not end the attribute value and invalidate the HTML and cause a security issue. See Data Validation in the Codex for further details.

Top ↑

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 are aligned, use spaces:

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

For associative arrays, values should start on a new line. Note the comma after the last array item: this is recommended because it makes it easier to change the order of the array, and makes for cleaner diffs too.

$my_array = array(
[tab]'foo'   => 'somevalue',
[tab]'foo2'  => 'somevalue2',
[tab]'foo3'  => 'somevalue3',
[tab]'foo34' => 'somevalue3',
);

Rule of thumb: Tabs should be used at the beginning of the line and spaces should be used mid-line.

Top ↑

Brace Style #

Braces should be used for multiline blocks in the style shown here:

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

Furthermore, if you have a really long block, consider whether it can be broken into two or more shorter blocks or functions. 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 conditions can omit braces for brevity:

 

if ( condition )
	action1();

if ( condition2 ) action2();

Loops should always contain braces as this enhances readability, and allows for fewer line edits for debugging or additional functionality later.

foreach ( $items as $item ) {
	process_item( $item );
}

For switch statements:

switch (condition) {
    case 1:
        action1;
        break;

    case 2:
        action2;
        break;

    default:
        defaultaction;
        break;
}

Top ↑

Regular Expressions #

Perl compatible regular expressions (PCRE, preg_ functions) should be used in preference to their POSIX counterparts. Never use the /e switch, use preg_replace_callback instead.

It’s most convenient to use single-quoted strings for regular expressions since, contrary to double-quoted strings, they have only two metasequences: \' and \\.

Top ↑

No Shorthand PHP tags #

Important: Never use shorthand PHP start tags. Always use full PHP tags.

Correct:

<?php ... ?>
<?php echo $var; ?>

Incorrect:

<? ... ?>
<?=$var ?>

Top ↑

End of File Closing PHP Tag #

Do NOT us a closing PHP tag at the end of the file.  This prevents extra or hidden spaces from being output.

End your PHP files at the beginning of a new line.

<?php

...code...

Not like this:

<?php

...code...

?>

Top ↑

Remove Trailing Spaces #

Important: If you do not omit the closing PHP tag at the end of a file (which is preferred), make sure you remove trailing whitespace.

Also remove trailing spaces at the end of each line of code.

Top ↑

Space Usage #

Always put spaces after commas, and on both sides of logical, comparison, string and assignment operators.

x == 23
foo && bar
! foo
array( 1, 2, 3 )
$baz . '-5'
$term .= 'X'

Put spaces on both sides of the opening and closing parenthesis of if, elseif, foreach, for, and switch blocks.

foreach ( $foo as $bar ) { ...

When defining a function, do it like so:

function my_function( $param1 = 'foo', $param2 = 'bar' ) { ...

When calling a function, do it like so:

my_function( $param1, func_param( $param2 ) );

When performing logical comparisons, do it like so:

if ( ! $foo ) { ...

When type casting, do it like so:

foreach ( (array) $foo as $bar ) { ...

$foo = (boolean) $bar;

When referring to array items, only include a space around the index if it is a variable, for example:

$x = $foo['bar']; // correct

$x = $foo[ 'bar' ]; // incorrect

$x = $foo[0]; // correct

$x = $foo[ 0 ]; // incorrect

$x = $foo[ $bar ]; // correct

$x = $foo[$bar]; // incorrect

Top ↑

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 esc_sql(), 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.

See Data Validation in the Codex for more information.

 

Top ↑

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.

 

Top ↑

Naming Conventions #

Use lowercase letters in variable, action, and function names (never camelCase). Separate words via underscores. Don’t abbreviate variable names un-necessarily; let the code be unambiguous and self-documenting.

function some_name( $some_variable ) { [...] }

Class names should use capitalized words separated by underscores. Any acronyms should be all upper case.

class Walker_Category extends Walker { [...] }
class WP_HTTP { [...] }

Files should be named descriptively using lowercase letters. Hyphens should separate words.

my-plugin-name.php

Class file names should be based on the class name with class- prepended and the underscores in the class name replaced with hyphens, for example WP_Error becomes:

class-wp-error.php

This file-naming standard is for all current and new files with classes. There is one exception for three files that contain code that got ported into BackPress: class.wp-dependencies.php, class.wp-scripts.php, class.wp-styles.php. Those files are prepended with class., a dot after the word class instead of a hyphen.

Files containing template tags in wp-includes should have -template appended to the end of the name so that they are obvious.

general-template.php

Top ↑

Self-Explanatory Flag Values for Function Arguments #

Prefer string values to just true and false when calling functions.

// Incorrect
function eat( $what, $slowly = true ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // what does true mean?
eat( 'dogfood', false ); // what does false mean? The opposite of true?

Since PHP doesn’t support named arguments, the values of the flags are meaningless, and each time we come across a function call like the examples above, we have to search for the function definition. The code can be made more readable by using descriptive string values, instead of booleans.

// Correct
function eat( $what, $speed = 'slowly' ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', 'slowly' );
eat( 'dogfood', 'quickly' );

Top ↑

Ternary Operator #

We do not use the Ternary Operator as this confuses many people.

Ternary operators are fine, but always have them test if the statement is true, not false. Otherwise, it just gets confusing. (An exception would be using ! empty(), as testing for false here is generally more intuitive.)

For example:

// (if statement is true) ? (do this) : (else, do this);
$musictype = ( 'jazz' == $music ) ? 'cool' : 'blah';
// (if field is not empty ) ? (do this) : (else, do this);

Top ↑

Yoda Conditions #

if ( 'with you' == $the_force ) {
	$victorious = you_will( $be );
}

When doing logical comparisons, always put the variable on the right side, constants or literals on the left.

In the above example, if you omit an equals sign (admit it, it happens even to the most seasoned of us), you’ll get a parse error, because you can’t assign to a literals like ‘with you’. If the statement were the other way around ( $the_force = ‘with you’ ), the assignment would be perfectly valid, returning 1, causing the if statement to evaluate to true, and you could be chasing that bug for a while.

A little bizarre, it is, to read. Get used to it, you will.

Note:  Some may call this “clever code” (perhaps due to the clever name!), however, actually there is a very logical reason for doing this, not cleverness and not brevity.

Top ↑

Clever Code #

In general, readability is more important than cleverness or brevity.  Readability will save you countless hours in debugging.

isset( $var ) || $var = some_function();

Although the above line is clever, it takes a while to grok if you’re not familiar with it. So, just write it like this:

if ( ! isset( $var ) )
	$var = some_function();

Top ↑

Credits #


    • MK Safi
      3:05 pm on May 24, 2013
      Permalink
      | Log in to Reply

      You need to explain your “Space Usage”. It seems arbitrary to me and I have a hard time remembering the specifics because I don’t know why I’m doing it…


        • Aaron D. Campbell
          3:56 pm on May 29, 2013
          Permalink
          | Log in to Reply

          All the spacing is for readability. In our experience, this spacing produces the easiest to read code, and prevents accidental missteps. For example, spacing the ! away from the variable or function in an if statement makes it stand out so it’s easy to see at a glance what’s going on.


    • lwoods
      8:34 pm on June 23, 2013
      Permalink
      | Log in to Reply

      I recommend discouraging the use of the PHP increment and decrement operators except where necessary, such as in the ‘for’ comment:

      If you are not familiar with this operator:

      $i = 5;

      echo ++$i; // display 6

      echo $i–; // display 6 again

      echo $i; // display 5

      In debugging code it is very easy to miss the effect of these operators.

      On the other hand, it is common and encouraged to use these operators in the ‘for’ loop:

      for ( $j=0; $j<5; $j++ ){

      .

      .

      .

      }


    • lwoods
      8:38 pm on June 23, 2013
      Permalink
      | Log in to Reply

      I disagree with the following under “Brace Style”:

      Single line blocks can omit braces for brevity:

      if ( condition )

      action1();

      elseif ( condition2 )

      action2();

      else

      action3();

      ALL IF statements should be braced! Although they are not needed in the above example the absence of braces can be very confusing if you start nesting IF statements. I have seen multiple single line blocks in nested IF statements that were near to impossible to debug.


    • Dayjo
      2:00 pm on July 10, 2013
      Permalink
      | Log in to Reply

      I agree with @lwoods.

      I find that the “Clever Code” part of this document contradicts “Yoda Conditions”.

      I find reading Yoda Conditions much slower than normal conditions. It seems that Yoda Conditions are just there to prevent you from writing broken code, which you should just not do. Learn to use the correct numbe of = instead.

      This also applies to the example in the Ternary Operator section which uses a Yoda Condition.

      To me, ( ‘jazz’ == $music ) … would return true.. because jazz is music. Whereas ( $music == ‘jazz’ ), or even ( $music_genre == ‘jazz’ ) makes so much more sense.


        • Andrew Nacin
          2:49 pm on July 11, 2013
          Permalink
          | Log in to Reply

          Yoda conditions are a programming best practice, and not overly clever. They’re going to remain part of the standard. Thanks for your input.


            • markparolisi
              12:14 pm on July 21, 2013
              Permalink
              | Log in to Reply

              I wouldn’t call them a programming best practice since many languages wouldn’t even let you declare variables inside a condition. The best way to avoid this problem is to avoid declaring variables in that way. It serves no purpose but to save yourself one line of code.


    • Jon Brown
      6:41 am on July 11, 2013
      Permalink
      | Log in to Reply

      Regarding braces and php tags, I run into this where php tags get thier own line often:

      function do_stuff() {
      	if ( condition ) {
      		?> 
      		<ul>
      			<li>something1</li>
      			<li>something2</li>
      		<ul>
      		<?php 
      	}
      }

      personally, I prefer this:

      function do_stuff() {
      	if ( condition ) { ?> 
      		<ul>
      			<li>something1</li>
      			<li>something2</li>
      		<ul>
      	<?php }
      }

      I’m really not sure which is right/wrong in the WordPress universe. Reviewing core, I think I’m right? Which is the WP way?


        • Andrew Nacin
          2:52 pm on July 11, 2013
          Permalink
          | Log in to Reply

          I don’t think WordPress is particularly consistent either way. At the moment, it depends on what is most readable for that situation. (Also, in general, we use if/endif when we are forced to break into HTML.)


    • Jon Brown
      6:00 am on July 16, 2013
      Permalink
      | Log in to Reply

      Thanks Nacin. Personally I hate if/endif. I find my later example much more readable, but that’s probably more familiarity with that style than an objective opinion.


    • lesterbuck
      4:57 pm on July 17, 2013
      Permalink
      | Log in to Reply

      I am new to PHP and WordPress, so I looked for tools that do the formatting and checking for me. I have exactly zero interest or opinion in what the format should be. I just want to match the standard, and I want a tool to check/fix that automatically as I check in to my source repository. (Computers are good at that, and I have better places to apply my mental energy.)

      I am not using a commercial IDE, such as Coda, which has reformatting built in. After some searching, I found wp-phptidy for reformatting, and PHP Codesniffer with the WordPress standard addon. Great, huh? Well, not exactly. wp-phptidy wants to indent the switch and case statements so they are at the same indent, while PHP Codesniffer with the WordPress standard complains if the case statements are not indented further than the switch statement.

      Note: I couldn’t care less which it is, I just want an automated tool to reformat it automatically if I indent something incorrectly, and check for valid format as I am committing the file to my repository.

      Ok, one of these tools is “wrong”, right? I consult the WordPress PHP coding standard and find … nothing about indenting switch statements. Well, I’ll just look at WordPress core and see what they use, right? Well, that doesn’t work either. Just look at wp-includes/functions.php and note that in one file there are multiple uses of both indent styles.

      Lots of tools exist to indent code to a given standard, automatically, and there is a document entitled “WordPress Coding Standards”, but the existing code base can’t be bothered to actually follow a consistent style, any style?


        • J.D. Grimes
          9:24 pm on August 17, 2013
          Permalink
          | Log in to Reply

          My preference is to indent case within the switch, and then to put a break at the end of the case on the same level as the case:

          switch ( $var ) {
                 case 'a':
                         echo 'Apple';
                 break;
          
                 case 'b':
                 // ...
          }

          Are there anything like this within the standards?


    • J.D. Grimes
      9:17 pm on August 17, 2013
      Permalink
      | Log in to Reply

      I noticed this type of spacing today (in wp-db.php):

      case 'string' : // note space before colon

      Is this part of the spacing standards, or just a random act of code?


    • hjchin
      5:03 pm on August 25, 2013
      Permalink
      | Log in to Reply

      I might be being silly. In the Yoda Conditions, why would I want to compare a variable to a boolean at the first? Isn’t it simpler and straightforward to write it as following? Please correct me if i’m wrong.

      if ( $the_force ) {

      $victorious = you_will( $be );

      }

Reply