PHP Coding Standards Draft Proposal

Some parts of the WordPress code structure for PHP markup are inconsistent in their style. WordPress continues to gradually improve this by helping users maintain a consistent style so the code can become cleaner and easier 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. Similarly, the guidelines adhere in part to the proposed PSR-12 spec.

See also: PHP Documentation Standards.

PHP PHP

Single and Double Quotes 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!"&gt;Link name</a&gt;';
echo "<a href='$link' title='$linktitle'&gt;$linkname</a&gt;";

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 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, each item should start on a new line when the array contains more than one item:

$query = new WP_Query( array( 'ID' => 123 ) );

$args = array(
[tab]'post_type'   => 'page',
[tab]'post_author' => 123,
[tab]'post_status' => 'publish',
);

$query = new WP_Query( $args );

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 when new items are added.

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

For switch structures case should indent one tab from the switch statement and break one tab from the case statement.

switch ( $type ) {
[tab]case 'foo':
[tab][tab]some_function();
[tab][tab]break;
[tab]case 'bar':
[tab][tab]some_function();
[tab][tab]break;
}

Rule of thumb: Tabs should be used at the beginning of the line for indentation, while spaces can be used mid-line for alignment.

Top ↑

Brace Style Brace Style

Braces shall be used for all blocks in the style shown here:

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

If you have a really long block, consider whether it can be broken into two or more shorter blocks, functions, or methods, to reduce complexity, improve ease of testing, and increase readability.

Braces should always be used, even when they are not required:

if ( condition ) {
	action0();
}

if ( condition ) {
	action1();
} elseif ( condition2 ) {
	action2a();
	action2b();
}

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

Note that requiring the use of braces just means that single-statement inline control structures are prohibited. You are free to use the alternative syntax for control structures (e.g. if/endif, while/endwhile)—especially in your templates where PHP code is embedded within HTML, for instance:

<?php if ( have_posts() ) : ?&gt;
	<div class="hfeed"&gt;
		<?php while ( have_posts() ) : the_post(); ?&gt;
			<article id="post-<?php the_ID() ?&gt;" class="<?php post_class() ?&gt;"&gt;
				<!-- ... --&gt;
			</article&gt;
		<?php endwhile; ?&gt;
	</div&gt;
<?php endif; ?&gt;

Top ↑

Use elseif, not else if Use elseif, not else if

else if is not compatible with the colon syntax for if|elseif blocks. For this reason, use elseif for conditionals.

Top ↑

Multiline Function Calls Multiline Function Calls

When splitting a function call over multiple lines, each parameter must be on a seperate line. Single line inline comments can take up their own line.

Each parameter must take up no more than a single line. Multi-line parameter values must be assigned to a variable and then that variable should be passed to the function call.

[preserved_text 56661da5ba2238ef9115f5f2d26cb743 /]

The goto statement must never be used.

The eval() construct is very dangerous, and is impossible to secure. Additionally, the create_function() function, which internally performs an eval(), is deprecated in PHP 7.2. Both of these must not be used.

Top ↑

Error Control Operator @ Error Control Operator @

As noted in the PHP docs:

PHP supports one error control operator: the at sign (@). When prepended to an expression in PHP, any error messages that might be generated by that expression will be ignored.

While this operator does exist in Core, it is often used lazily instead of doing proper error checking. Its use is highly discouraged, as even the PHP docs also state:

Warning: Currently the “@” error-control operator prefix will even disable error reporting for critical errors that will terminate script execution. Among other things, this means that if you use “@” to suppress errors from a certain function and either it isn’t available or has been mistyped, the script will die right there with no indication as to why.

Top ↑

Don’t extract() Don’t extract()

Per #22400:

extract() is a terrible function that makes code harder to debug and harder to understand. We should discourage it’s [sic] use and remove all of our uses of it.

Joseph Scott has a good write-up of why it’s bad.

Top ↑

Credits Credits

Top ↑

Major Changes Major Changes