WordPress PHP コーディング基準 | WordPressのカスタマイズ

WordPress PHP Coding Standard

WordPress のコード体系での PHP 記述の一部の部分において形式に一貫性がありません。WordPress は、ユーザーが一貫した形式を維持することを助ける事によって、この状態を徐々に改善しようと作業しています。これによりコードはきれいに、かつ一目見て読みやすくなります。
WordPress のためにコードを書くときは、以下の点を心に留めておいてください。WordPress コアのプログラミングのみならず、プラグインの作成やWordPress テーマにおいてもです。このガイドラインは、Pear 標準に多くの点で似ていますが、いくつかの事項で異なります。

Table of contents

• Single and Double Quotes シングル & ダブルクォート
• Indentation インデント
• Brace Styleブレース（波かっこ）の形式
• Use elseif, not else if
• Declaring Arrays 配列の宣言
• Closures (Anonymous Functions) 無名関数
• Multiline Function Calls 複数行関数呼び出し
• Regular Expressions 正規表現
• Opening and Closing PHP Tags PHP 開閉タグ
• PSR cording-standards
• No shorthand PHP Tags ショートタグは禁止
• Remove Trailling Spaces 行末に残ったスペースの消去
• Space Usage スペースの使い方
• Formatting SQL statements SQL文の書式
• Database Queries データベースクエリ
• Naming Conventions 命名規則
• Self-Explanatory Flag Values for Funciotn Arguments
  関数の引数のための自明な（説明のいらない）フラグ値
• Interpolation for Naming Dynamic Hooks
  動的フックの命名における文字列補間
• Ternary Operator 三項演算子
• Yoda Conditions ヨーダ条件式
• Clever Code 巧妙なコード
• Error Control Operator @ エラー制御オペレータ
• Don't extract() 関数extract() の使用禁止

Single and Double Quotes シングル & ダブルクォート

シングルクォートとダブルクォートは適切に使い分けてください。文字列で何も評価しない場合は、シングルクォートを使います。文字列で HTML クォートをエスケープする必要はほとんどありません。なぜなら、以下のようにクォート形式を変更すればいいからです:

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

PHP

CopyExpand

注：以下の記述は日本語codex にのみにあったもの。
(訳注: セキュリティ向上のためには、HTML 出力において、シングルクォートを使うのは好ましくありません。多少コードが読みにくくなっても、ダブルクォートを使うべきです)
↑ここまで。
これに対する例外は JavaScript です。ダブルまたはシングルクォートのどちらかを強制されるときがあります。属性値となるテキストは esc_attr() を通さなければなりませんが、こうするとシングルまたはダブルクォートが属性値の終了点を表わせず、XHTML 違反となり、セキュリティ問題が発生します。詳細はData Validationを参照してください。

Indentation インデント

インデントは論理的な構造を反映するようにしてください。スペースではなく、本物のタブを使います。こうすると、多くの閲覧環境で柔軟に扱えます。
例外：何かを整列させて読みやすくしたいコードブロックがあれば、行頭のインデントはタブ[tab]を使い、行の中においてはスペースで整列させることができます。

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

PHP

CopyExpand

連想配列において、それぞれの値は新しい行を使うべきです。配列の最後の要素の後にもカンマを記述します。これは、簡単に配列の順序を変更することができ、新たなアイテムが追加されたときに差分消去のためになるので推奨されています。

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

PHP

CopyExpand

行頭のインデントにタブ[tab]を使っていて、スペースは '=' を一列に揃えるために使っていることに注意してください。

Brace Style ブレース（波かっこ）の形式

ブレースは複数行のブロックを囲むのに使います。

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

PHP

CopyExpand

その上で、非常に長いブロックがあれば、複数の短かいブロックまたは関数に分割できないか考慮してください。このような長いブロックが避けられないと考慮した場合、終了点に短かいコメントを置いてください。そうすると、一目見て終了ブレースが何の終わりであるか分かります。たいてい、約35行を越える論理ブロックに適用するのが適切です。そうでなくても、明らかには直感的でないコードならばコメントを付けて構いません。
ブレースは、それらが必要とされない場合でも、常に使用されるべきです。
（注：2015年7月10日現在の日本語codex においてはブロック内が単一行であれば、ブレースは省略できるとなっています。この部分は変更となったようです。）

if ( condition ) {
	action0();
}

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

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

PHP

CopyExpand

ブレースを使用する必要があるということは、単一行の文の行内での制御構造が禁止されているということをまさに意味している事に注目してください。
alternative syntax for control structures　(e.g. if / endif、 while /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; ?>

PHP

CopyExpand‹›

Use elseif, not else if

else if は if|elseif ブロックのコロン構文と互換性がありません。このため、条件式には elseif を使用してください。

Declaring Arrays 配列の宣言

配列の宣言に長い配列構文 ( array( 1, 2, 3 ) ) を使用することは、一般的に短い配列構文 ( [ 1, 2, 3 ] ) よりも、特に視覚に障害のある人にとっては読みやすくなります。さらに、初心者にとっては、この方がはるかに説明的です。
配列は長い配列構文を使って宣言しなければなりません。

※この配列の宣言において私はちょっと思い込み違いをしていました。
というのは、同じくここのWordPress Javascript coding-standards において、配列の宣言では new Array() ではなく、[] の使用をすすめています。以前、自分が coding-standards のページを訳したときの php のページにはこの配列の宣言に関しての記述は存在せず、それゆえに php においても同様に配列の宣言においては [] を使用したほうがいいのだろう、と思い込んでしまっていたのです。Javascript における new Array() と [] は、その挙動に若干の違いがあり、それゆえのことなのかもしれないけれど、php と Javascript において、そしてJavascript における new Array() と [] など、これらの使い分けはちょっと間違いやすい部分ではあると思う。

Closures (Anonymous Functions) 無名関数

必要に応じて、コールバックとして渡す新しい関数を作成する代わりにクロージャを使用することができます。例えば、以下のようになります。

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

PHP

CopyExpand

クロージャは、remove_action() / remove_filter() で削除できないため、フィルタまたはアクションコールバックとして渡してはなりません。

Multiline Function Calls 複数行関数呼び出し

関数呼び出しを複数行に分割する場合、各パラメーターは別々の行になければなりません。1 行のインライン コメントは、独自の行を取ることができます。
各パラメータは、1 行以下にする必要があります。複数行のパラメーター値を変数に代入し、その変数を関数呼び出しに渡す必要があります。

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

PHP

CopyExpand

Regular Expressions 正規表現

Perl 互換の正規表現 (PCRE, preg_ 関数) が、POSIX の対応するものよりも優先して使用されるべきです。
” preg_replace_callback ” を使用するかわりとして、絶対に " /e " switch を使用してはいけません。
正規表現では、二重引用符に対して、単一引用符で囲まれた文字列を使用することが最も便利です。\' と \\ の二つだけのメタシーケンスしか持っていません。

Opening and Closing PHP Tags 開閉タグ

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

CopyExpand

PSR cording-standards

ここでちょっと WP coding-standards から脱線して PSR ( PHP Standards Recommendations ) から気になったところを引っ張り出してみます。

• インデント（字下げ）はタブ文字ではなく半角スペース4文字を使う。
• PHPファイルは（CRLFやCRではなく）LFの改行コードを使う。
• PHPファイルの最終行は空行１行とする。
• HTMLなどが混在しないPHPプログラムのみのファイルでは、終了タグ「?>」は省略しなければならない。
• 行末にスペース文字があってはならない。
• コードのまとまりをわかりやすくするために空行はあってもいい。
• １行に複数の命令文があってはならない。

「PHP本格入門 上 大家正登著 技術評論社」　からの引用

とりあえずもっとも基本的なところだけだけど、インデントは WP とは違い、あと括弧内側のスペースの使い方とか、関数の開始波括弧は改行してそれだけで一行にするとか、若干の違いがある。HTMLが混在しないPHPプログラムのみのファイルでは終了タグを省略しなければならないというのは知らなかった。
と、いうところでもとい。

No shorthand PHP Tags ショートタグは禁止

重要：絶対に PHP ショートタグを使用してはいけない。常に 完全な PHP タグを使用する。

// 正しい
<?php ... ?>
<?php echo $var; ?>

// これはだめ
<? ... ?>
<?= $var ?>

PHP

CopyExpand

Remove Trailling Spaces 行末に残ったスペースの消去

コードの各行の末尾の空白を削除します。ファイルの最後にある PHP タグを省略することが望ましいです。タグを使用する場合は、必ず末尾の空白を削除してください。（注：ホワイトスペースとは、スペース、タブ、改行など）

Space Usage スペースの使い方

カンマの後、論理演算子、比較演算子、文字列そして代入演算子の両側には常にスペースを入れます。

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

//しかしオブジェクトのクラスメンバにアクセスするための->演算子の両側にはスペースは入れない
// これは最新版（2021/01/21）では削除されている。
$this->current

PHP

CopyExpand‹›

同様に、if, elseif, foreach, for and switch ブロックの開きかっこ、閉じかっこの両側にも入れてください。
関数に関してや論理比較、型キャスト、配列など以下のよう。

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 ) { ...

// 型キャストは小文字である必要があります。
// 型キャストの短い形式を常に選び、(integer) ではなく(int)、(boolean) ではなく(bool)、そして(float)。
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': // correct
    case 'ba' : // incorrect
}

// 同様に、戻り値の型宣言のコロンの前にスペースを入れないでください。
function sum( $a, $b ): float {
    return $a + $b;
}

// 特に指定しない限り、括弧の中にはスペースを入れてください。
if ( $foo && ( $bar || $baz ) ) { ...
 
my_function( ( $x - 1 ) * 5, $y );

PHP

CopyExpand‹›

Formatting SQL statements SQL文の書式

SQL 文を書くときは、それを読みこなすのが複雑すぎる場合、複数の行に分割してインデントすることが可能です。多くの文は1行で書いた場合と同様に動きます。
SQL の構文は、例えば UPDATE や WHERE のように、常に大文字で書いてください。

データベースを更新する関数は、パラメータが渡されれたとき、SQL のスラッシュエスケープが欠けていると考えてください。できるだけクエリが実行される直近でエスケープを行なってください。このとき、$wpdb->prepare() を使うことが好ましいです。

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

PHP

CopyExpand‹›

%s は、文字列のプレースホルダー (入れ物) として、%d は整数のプレースホルダーとして使います。これらは 「クォート」しないことに注意してください。
$wpdb->prepare() が、エスケープやクォートを行なってくれます。こうすることで、わたしたちが、わざわざ $wpdb->escape() を使うことに気を付ける必要がなくなります。また、何がエスケープされ、されないのかを一目で見分けることができます。なぜなら、クエリを行うときに正しくエスケープが行なわれるからです。
詳しくはデータベースのデータ検証をご覧ください。

Database Queries データベースクエリ

データベースを直接触ることは避けてください。必要とするデータを得る関数がすでに定義されている場合、それを使ってください。データベースの抽象化 (クエリの変わりに関数を使うこと) によって、コードの前方互換性を保つことができ、多くの場合、結果がメモリーにキャッシュされるため何倍も速く実行できます。もし、データベースを触る必要があるなら、wp-hackers メーリングリスト/en にメッセージを投稿して、開発者に連絡を取ってみてください。この人たちは、次の WordPress バージョンにおいて、あなたが望む機能を含む関数を作ることを検討するかもしれません (訳注: 英語で投稿する必要があります)。

Naming Conventions 命名規則

変数名、アクション/フィルター、関数名はアルファベット小文字を使い、単語の先頭を大文字にして繋げる形式 (キャメルケース; camelCase のような形式) は不可です(訳注: 日本語文字列も使わないでください)。単語の区切りはアンダースコア '_' を使ってください。不必要に変数名を短縮しないでください。コードを明確で自己文章としましょう。

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

PHP

CopyExpand‹›

このファイル命名規格は、クラスにおいての全ての現在のファイルと新しいファイルのためのものです。
例外が一つあり、BackPressに移植されてしまったコードを含む3つのファイル 'class.wp-dependencies.php'、 'class.wp-scripts.php'、 'class.wp-styles.php' で、ハイフンの代わりに単語の後にドットが付加する 'class.' が前に付いています。

'wp-includes' の中のテンプレートタグに含まれるファイルは、それらが明白なようにファイル名の最後に '-template' が付加されている。

general-template.php

PHP

CopyExpand

注：以下の記述は以前の日本語codex にのみあったもの。
もし変数を1回しか使わないのなら、その変数を作ってはいけません。データベースクエリも同様です。データベースと交信するときは、必ず wpdb Class/en の関数を用いてください。

'else if' と 'elseif' は、双方とも波かっこと一緒に使用します。どちらを選ぶかは規則にありませんが、'elseif' にすると面倒を避けられることが有るかもしれません。
include_once 対 require_once
include_once と require_once との違いを学び、適切に使い分けてください。include() の PHP マニュアルを引用します:
「これら2つの構文は、 エラーの扱い方を除けば全く同様に振舞います。エラーが発生するとどちらも Warning を出力しますが、 require() を使用している場合は Fatal Error となります」Fatal Error はスクリプトの実行を中止します。
↑ここまで。

Self-Explanatory Flag Values for Funciotn Arguments

『関数の引数のための自明な（説明のいらない）フラグ値』　ということです。
関数を呼び出すとき、まさに 'true' や 'false' といった文字列値を好む。

// 不適当
function eat( $what, $slowly = true ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // true は何を意味している？
eat( 'dogfood', false ); // false は何を意味している？ true の反対？

PHP

CopyExpand

PHP は名前付き引数をサポートしません。フラグの値は意味を持たないので、上記のような方法で関数を呼び出すと、関数定義を探す必要があります。真偽値ではなく、意味のある値にすると、コードの可読性が向上します。

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

PHP

CopyExpand

より多くの単語が関数の引数の説明として必要とされる時、'$arg' の配列はより良い形である。

// より良き
function eat( $what, $args ) {
...
}
eat ( 'noodles', array( 'speed' => 'moderate' ) );

PHP

CopyExpand

Interpolation for Naming Dynamic Hooks
動的フックの命名における文字列補間

ダイナミックフックの名前では読みやすさ、検索のしやすさのため、変数の連結でなく、展開を使用してください。
ダイナミックフックはタグ名に動的な値を含むフックです。例:

{$new_status}_{$post->post_type} (publish_post)

PHP

CopyExpand

フックタグで使用される変数は中括弧(「{」と「}」)で囲み、完全なタグ名全体をダブルクオートで囲んでください。こうすると PHP は、挿入された文字列内で指定された変数の型を正しくパースできます。

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

PHP

CopyExpand

このときタグ名内の動的な値はできるだけ簡潔で分かりやすいものにしてください。$user_id の方がたとえば $this->id などよりも明確です。

※注：この項目は以前のページにはなかったと思う。ダイナミックフックの命名に関してのことなのだけれど、今ひとつ何をしろと言っているのかよくわからん。ダイナミックフックは実際に自サイトで使っていたりするものではあるけれど・・・。
ちなみにこの訳は全て日本語ページからのコピーであり、「展開」は interpolation、「連結」は concatenation という単語。
"interpolation" はプログラミングにおける文字列補間のことであるとすればその意味は、「文字列リテラル（英語版）内に埋め込まれたプレースホルダーを実行時に評価し、そのプレースホルダーを対応する値に置き換える処理である。」とのこと。
一方の"concatenation" は文字列連結であれば、「ある文字列の後ろに別の文字列をつなげて1つの文字列にする処理のことである。」とのことである。

Ternary Operator 三項演算子

三項演算子は良いが、文が常に'false' では無く 'true' となるようなテストでなければなりません。さもなければ混乱を招きます。
（例外として '! empty()' を使う事、ここでの 'false' のテストは一概により直観的ではあります）
例えば：

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

PHP

CopyExpand

Yoda Conditions ヨーダ条件式

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

PHP

CopyExpand

変数を含む論理比較を行う場合は、常に変数を右側に置き、定数、リテラル、または関数呼び出しを左側に置きます。どちらの側も変数でない場合、順序は重要ではありません。(コンピュータサイエンスの用語では、比較では、常に l-value を右に、r-value を左に置きます。
上記の例で、もしもあなたが '=' を省略してしまったとしたら（認めます、私たちの内でも最もベテランな人にもおこります）、あなたは parse error を受け取ります。なぜならばあなたは 'true' のような定数には代入することが出来ないからです。仮に条件文が（ '$the_force = true' ）のように違う方法であったとしたら、代入は完全に正当なものとなり、'1' が返ります。条件文の評価が 'true' となる理由を、あなたはしばらくの間、そのバグを追いかけることになるでしょう。
「読むには少し奇妙、そのうち慣れる」
これは、"=="、"!＝"、"==="、と"!==" に適用します。ヨーダコレクションは、" < "、" > "、" <= " もしくは " >= " においては、より著しく読みづらくなり、避けた方が良いです。

Clever Code 巧妙なコード

一概に、理解しやすさは利口さや簡潔さよりも、より重要です。

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

PHP

CopyExpand

上記は利口ではあるけれど、あなたが上の書き方に慣れていない場合には理解するのに時間がかかります。なら、こう書けばいいのです。

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

PHP

CopyExpand

絶対に必要でない限り、緩い比較は、その行動が誤解を招く可能性がありますので、使用すべきではありません。

// 絶対に必要でない限り、緩い比較は、その行動が誤解を招く可能性がありますので、使用すべきではありません。
// 正しい
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
}

PHP

CopyExpand‹›

switch ステートメントでは、複数の空のケースが共通のブロックに渡っても問題ありません。しかし、あるケースにブロックが含まれていて、次のブロックに落ちる場合は、明示的にコメントしなければなりません。

switch ( $foo ) {
    case 'bar':       // Correct, an empty case can fall through without comment.
    case 'baz':
        echo $foo;    // Incorrect, a case with a block must break, return, or have a comment.
    case 'cat':
        echo 'mouse';
        break;        // Correct, a case with a break does not require a comment.
    case 'dog':
        echo 'horse';
        // no break   // Correct, a case can have a comment to explicitly mention the fall through.
    case 'fish':
        echo 'bird';
        break;
}

PHP

CopyExpand‹›

goto 文は決して使用してはいけません。
eval() は非常に危険であり、安全性を確保することは不可能です。さらに、内部的に eval() を実行する create_function() 関数は PHP 7.2 では非推奨となっています。これらはどちらも使用してはいけません。

Error Control Operator @ エラー制御オペレータ

PHP docs で述べられているように。
PHP はエラー制御演算子 アットマーク（ @ ）をサポートしています。PHP の中で式の前に付けた時、その式によって生みだされるかもしれない、いかなるエラーメッセージも無視されます。
コアの中にこの演算子が存在する間は、適切なエラーチェックをする代わりの怠けることの為に使用されます。the PHP docs もまた述べているように、それの使用は強く反対します。
要注意：一般にエラー制御演算子 "@" 接頭辞は、スクリプトの実行を終わらせる重大なエラーのリポートさえも無効にします。とりわけ、このことは、もしあなたが特定の関数や使用不可のものやタイプミスのエラーを抑えるために"@" を使用しているなら、スクリプトは理由を示すことなくすぐに死んでしまうことを意味しています。