WordPress 的 PHP 编码规范

WordPress 的 PHP 编码标准对整个 WordPress 社区都适用,但是对于 WordPress 核心代码是强制要求的,而对于主题和插件,WordPress 则鼓励使用,因为主题和插件的作者可能会选择遵循别的编码风格。

但这个编码规范不仅关于编码风格,还包括 WordPress 生态中互操作性、可翻译性和安全性等方面的最佳实践,因此即使使用其他的编码风格 ,还是建议开发者在最佳实践方面仍然遵守 WordPress 编码标准。

目前也不是所有的核心代码都完全符合这个规范,但所有新提交和/或更新的代码则都要求完全遵守。

对于开发者来说,如果想根据这个规范去自动检查自己的代码,可以使用基于 PHP_CodeSniffer 开发的官方 WordPress 编码规范工具

引号

正确的使用单引号和双引号,如果字符串中不包含变量的时候,则使用单引号,永远不要在字符串中转移引号,而是通过切换引号类型,比如:

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

HTML 或 XML 属性中的文本应该进行转义,以便单引号或者双引号不会结束属性是的 HTML 标签无效甚,甚至引起安全问题,如何对属性进行转义,我们会在以后的文章中详细讲解。

缩进

首先使用制表符而不是空格进行缩进,并且使用空格把代码对齐,以便更易阅读:

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

对于关联数组,如果数据含有多个元素的时候,每个元素都应该新起一行:

$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 );

特表关注一下数组最后一个元素后面的逗号,推荐都加上,因为这样更容易调整数组的顺序,并且更容易添加新的元素,因为不用关注之前最后一个是否有逗号。

对于 switch 结构, case 语句应该比 switch 语句多缩进一个制表符, case 的内容也要比 case 条件语句缩进一个 tab。

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

经验法则:行首缩进使用制表符,行中对其使用空格。

大括号

大括号的使用样式如下所示:

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

如果代码块非常长,那就要考虑将其分解成更多的较短的代码块,函数或者方法,以便降低复杂度,提高测试的便利性,当然也增加了代码的可读性。

不管是否必需,都要使用大括号:

if ( condition ) {
    action0();
}
 
if ( condition ) {
    action1();
} elseif ( condition2 ) {
    action2a();
    action2b();
}
 
foreach ( $items as $item ) {
    process_item( $item );
}

特别注意,强制使用大括号意味着禁止单语句内联控制结构,但是可以使用控制结构的替代语法(例如 if/endifwhile/endwhile)——尤其是在 HTML 的模板中嵌入 PHP 代码的时候 ,例如:

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

使用 elseif 而不是 else if

因为 else if 和 if|elseif 代码块的冒号语法不兼容,因此条件语句中使用 elseif

数组声明

使用长数组语法 ( array( 1, 2, 3 ) ) 声明数组通常比短数组语法 ( [ 1, 2, 3 ] ) 更具有可读性,对于初学者,也更有描述性。

所以数组声明必须使用长数组语法。

闭包(匿名函数)

在一些的情况下(比如回调函数只需要用一次),可以使用闭包而非重写一个新函数来作为回调函数传递,比如:

$caption = preg_replace_callback(
    '/<[a-zA-Z0-9]+(?: [^<>]+>)*/',
    function ( $matches ) {
        return preg_replace( '/[\r\n\t]+/', ' ', $matches[0] );
    },
    $caption
);

但是不建议 filter 或 action 的回调函数使用闭包,因为通过 remove_action() / remove_filter() 移除的时候,就变得复杂了。

函数多行调用

将一个函数调用拆分为多行时,每个参数必须位于单独的行上, 单行内联注释可以单独一行:

每个参数不得超过一行,如果一个参数需要多行,那么可以先将其赋值给一个变量,然后再将该变量传递给函数调用。

$bar = array(
    'use_this' => true,
    'meta_key' => 'field_name',
);
$baz = sprintf(
    /* translators: %s: Friend's name */
    esc_html__( 'Hello, %s!', 'yourtextdomain' ),
    $friend_name
);
 
$a = foo(
    $bar,
    $baz,
    /* translators: %s: cat */
    sprintf( __( 'The best pet is a %s.' ), 'cat' )
);

正则表达式

正则表达式应该使用 Perl 兼容的正则表达式(PCREpreg_函数),另外永远不要使用 /e 开关,而是使用 preg_replace_callback

在正则表达式中使用单引号字符串是最简便的,因为相比双引号,单引号字符串只有两个元序列需要转移:\' 和 \\

PHP 开始和结束标记

在 HTML 模板中如果要嵌入多行 PHP 代码时,PHP 开始和结束标记都要自己单独一行。

正确(多行):

function foo() {
    ?>
    <div>
        <?php
        echo bar(
            $baz,
            $bat
        );
        ?>
    </div>
    <?php
}

正确(单行):

<input name="<?php echo esc_attr( $name ); ?>" />

错误:

if ( $a === $b ) { ?>
<some html>
<?php }

不要使用简写的 PHP 标记

重要:永远不要使用简写的 PHP 标记,是用完整版。

正确:

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

错误:

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

删除行尾的空格

删除每行末尾的空格,最好在文件末尾省略 PHP 结束标记,如果没有省略,那就确保删除 PHP 结束标记后面的空格。

空格的用法

始终在逗号后放置空格,并在逻辑运算符、比较运算符、字符串连接符和赋值运算符的两侧放置空格。

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

在控制语句中的左括号和右括号的两侧防止空格:

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

定义函数时,这样使用空格:

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

调用函数时:

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

当执行逻辑运算时:

if ( ! $foo ) { ...

类型转换必须使用小写的, 并且使用简短形式,(int)  而不是 (integer) ,(bool)  而不是 (boolean),对于浮点类型转换,请使用 (float) 而不是 (real),因为 (real) 在 PHP 7.4 中已被弃用,并在 PHP 8 中被移除。

foreach ( (array) $foo as $bar ) { ...
$foo = (bool) $bar;

当涉及到数组元素的时候,仅当元素的索引是变量的时候,在索引周围包含空格,例如:

$x = $foo['bar']; // 正确
$x = $foo[ 'bar' ]; // 错误
 
$x = $foo[0]; // 正确
$x = $foo[ 0 ]; // 错误
 
$x = $foo[ $bar ]; // 正确
$x = $foo[$bar]; // 错误

在 switch 代码中,  case 提交和冒号之间不要有空格:

switch ( $foo ) {
    case 'bar': // 正确
    case 'ba' : // 错误
}

同样,返回的类型声明的冒号前不应有空格:

function sum( $a, $b ): float {
    return $a + $b;
}

除非另有说明,括号内应有空格。

if ( $foo && ( $bar || $baz ) ) { ...
my_function( ( $x - 1 ) * 5, $y );

格式化 SQL 语句

在格式化 SQL 语句时,如果 SQL 很复杂,可以将 SQL 语句分成几行并缩进。当然大部分 SQL 语句一行就可以了。然后将 SQL 语句中的关键字(比如 UPDATE 或者 WHERE)大写。

需要更新数据库的函数的参数,传递来之前应该没有对数据进行 SQL 斜杠转义,转义应该尽可能接近查询的时候执行,并且最好使用  $wpdb->prepare() 进行。

$wpdb->prepare() 是一种处理 SQL 查询的转义、引用和整数转换的方法。 它使用 sprintf() 格式的子集。 例子 :

$wpdb->prepare() 是用来对 SQL 查询进行转义、引用和整数转换等操作的方法,它 sprintf() 的一部分格式化方法,比如:

$var = "dangerous'"; // 可能未转义的原始数据
$id = some_foo_number(); // 期待是整形的数据,但是不能确定
 
$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );

%s 用于字符串占位符,而 %d 用于整数占位符。注意他们没有被引用,$wpdb->prepare() 会执行转义和引用的工作。

数据库查询

避免直接操作数据库,如果有定义的函数可以获取你需要的数据,则使用它。数据库抽象(使用函数而不是查询)有助于保持代码向前兼容,并且在查询结果被缓存到内存中的时候,它可以快很多倍。

命名约定

在变量名,action/filter 的名称和函数名使用小写,不要使用驼峰式,通过下划线分割单词, 如非必需不要使用缩写,让代码无歧义并能自我说明:

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

类名必须首字母大写,并用下划线分割,首字母缩写词都应全部大写:

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

常量必须全部大写,并用下划线分割:

define( 'DOING_AJAX', true );

文件名应使用小写字母进行描述性命名,使用连字符应分隔:

my-plugin-name.php

类文件名应该基于类名,然后在前面加上 class-,然后类名中的下划线替换为连字符,例如 WP_Error 的文件名:

class-wp-error.php

wp-includes 目录中含有函数模板标签函数的文件,都会在文件名称末尾附加 -template 以便它们显而易见。

general-template.php

每个文件只有一个对象结构(类/接口/特征)

比如,有个名为 class-example-class.php 的文件,它只包含一个类:

// 错误: 文件 class-example-class.php
class Example_Class { [...] }
class Example_Class_Extended { [...] }

第二个类应该在自己的名字为  class-example-class-extended.php 的文件中:

// 正确:文件 class-example-class.php
classExample_Class { [...] }
// 正确:文件 class-example-class-extended.php.
class Example_Class_Extended { [...] }

函数参数的自解释标志值

调用函数时使用字符串值而不是 true 和 false

// 错误
function eat( $what, $slowly = true ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // true 是什么意思呢?
eat( 'dogfood', false ); // false 又是什么意思呢?false 的反面?

PHP 直到 8.0 起,才支持命名参数,但是,由于 WordPress 目前仍支持较旧的 PHP 版本,我们还不能使用这些版本。

没有命名参数,标志的值是没有意义的,每次遇到像上面例子这样的函数调用时,我们都必须搜索函数定义才明白什么意思。通过使用描述性字符串值而不是布尔值,可以使代码更具可读性。

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

当需要使用更多词汇来描述函数参数时,$args 数组参数可能是更好的模式:

// 更好
function eat( $what, $args ) {
...
}
eat ( 'noodles', array( 'speed' => 'moderate' ) );

动态 Hook 的插值命名

出于可读性和可发现性的目的,应使用插值而不是串联来命名动态 Hook。

动态 Hook 是在其标签名中包含动态值的 Hook,例如 {$new_status}_{$post->post_type}(publish_post)。

HooK 标签中使用的变量应该用大括号 { 和 } 括起来,完整的外部标签名称用双引号括起来。这是为了确保 PHP 可以正确解析内插字符串中给定的变量。

do_action( "{$new_status}_{$post->post_type}", $post->ID, $post );

可能的话,标签名称中的动态值也应尽可能简洁明了,比如 $user_id 就比 $this->id 更加清晰明了。

三元运算符

使用三元运算符很好,但是尽量让他们先测试为真,而不是假,否则容易混淆(一个例外是使用 ! empty(), 因为这里为假反而更直观)。

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

尤达表达式

if ( true === $the_force ) {
    $victorious = you_will( $be );
}

在涉及变量的逻辑比较时,始终将变量放在右侧,将常量、文字或函数调用放在左侧。如果双方都不是变量,则顺序并不重要。 (在计算机科学术语中,在比较中总是尝试将 l 值放在右侧,将 r 值放在左侧。)

在上面的例子中,如果省略了一个等号(承认吧,即使是我们当中最有经验的人也会犯这种错误),你会得到一个解析错误,因为你不能赋值给一个像 true 这样的常量,如果该语句是相反的( $the_force = true ),则赋值将完全有效,返回 1,导致 if 语句结果为 true,这种错误可能让你花费很长时间去 Debug。

尤达表达式适用于  ==!====, 和 !==。而 <><= 或者 >=  情况不会出现赋值的可能,并且不易阅读,不建议使用。

“聪明”的代码

一般来说,代码的可读性比聪明和简洁更重要:

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

虽然上面的代码很巧妙,但如果你不熟悉它,需要一段时间才能理解。 所以还是这样写吧:

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

除非绝对的必要,否则不应使用松散的比较,因为可能会产生误导。

正确:

if ( 0 === strpos( 'WordPress', 'foo' ) ) {
    echo __( 'Yay WordPress!' );
}

错误:

if ( 0 == strpos( 'WordPress', 'foo' ) ) {
    echo __( 'Yay WordPress!' );
}

赋值最好不要在条件表达式中:

正确:

$data = $wpdb->get_var( '...' );
if ( $data ) {
    // Use $data
}

错误:

if ( $data = $wpdb->get_var( '...' ) ) {
    // Use $data
}

在 switch 语句中,可以将多个空的 case 放到一起。 但是,如果一个 case 包含代码,然后直接进入下一个代码块,则必须明确注释。

switch ( $foo ) {
    case 'bar':       // 正确,空的 case 无需注释
    case 'baz':
        echo $foo;    // 错误, 含有代码的 case 必须 break,return 或者含有主食
    case 'cat':
        echo 'mouse';
        break;        // 正确,有 break 的 case 无需注释
    case 'dog':
        echo 'horse';
        // no break   // 正确,含有注释的 case 可以不要 break。
    case 'fish':
        echo 'bird';
        break;
}

goto 语句绝对不能用。

eval() 是非常危险并且无法确保安全。 create_function() 函数,相当于内部执行了内部执行 eval(),PHP 7.2 起已弃用,并已在 PHP 8.0 中删除,所以都不能使用。

错误控制符 @

引用 PHP 文档

PHP 支持一种错误控制运算符:at 符号 (@)。 当附加到 PHP 中的表达式时,该表达式可能生成的任何诊断错误都将被抑制。

虽然在 WordPress 核心代码中确实存在此运算符,但它经常被懒惰地使用,而不是进行适当的错误检查。 强烈建议不要使用它,甚至 PHP 文档也指出:

警告:在 PHP 8.0.0 之前,@ 运算符可以禁用将终止脚本执行的严重错误。 例如,将 @ 附加到不存在的函数调用之前,由于不可用或输入错误,将导致脚本终止而没有说明原因。

不要使用 extract()

extract() 是一个非常糟糕的函数,它使代码更难调试和更难理解,我们应该不应该使用它,并删除现有代码中的所有使用。


©我爱水煮鱼,本站推荐使用的主机:阿里云,国外主机建议使用BlueHost

本站长期承接 WordPress 优化建站业务,请联系微信:「chenduopapa」。