|
|
| 1行目: |
1行目: |
| − | <p class="important">注意: この記事は「[https://make.wordpress.org/core/handbook/ Core Contributor Handbook]」の「[https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/ PHP Coding Standards]」(2016年12月25日時点)の訳です。<br />最新版については[https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/ 英語版]を参照してください。</p>
| + | このページは https://ja.wordpress.org/team/handbook/coding-standards/wordpress-coding-standards/php/ へ移動しました。 |
| − | | + | |
| − | WordPress の一部の PHP コードには一貫性に欠ける部分があります。WordPress ではユーザーの支援も得ながら徐々にこれらを改善し、コードをクリーンで読みやすいものにするよう努めています。
| + | |
| − | | + | |
| − | WordPress において PHP のコードを書く場合はこの規約に従ってください。これは WordPress コアのプログラミングだけではなく、[[プラグインの作成|プラグイン]]や[[テーマの作成]]でも同様です。規約は多くの点で「[http://pear.php.net/manual/en/standards.php Pear standards]」に似ていますが、一部異なる部分もあります。
| + | |
| − | | + | |
| − | 参照: [[WordPress コーディング規約]]
| + | |
| − | | + | |
| − | == PHP ==
| + | |
| − | | + | |
| − | === シングルクォートとダブルクォート ===
| + | |
| − | | + | |
| − | シングルクォートとダブルクォートは適切に使い分けてください。文字列で何も評価しない場合は、シングルクォートを使用してください。クォートの種類を入れ替えれば済むため、文字列の中でエスケープを使用する必要はほとんどないはずです。
| + | |
| − | | + | |
| − | <pre><nowiki>echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';
| + | |
| − | echo "<a href='$link' title='$linktitle'>$linkname</a>";</nowiki></pre>
| + | |
| − | | + | |
| − | 属性値の途中にシングルクォートやダブルクォートがあると属性値が途中で終了し、HTML は不正になり、セキュリティ問題を引き起こします。属性値は <tt>esc_attr()</tt> を通してください。詳細については「[[データ検証]]」を参照してください。
| + | |
| − | | + | |
| − | === インデント ===
| + | |
| − | インデントは常に論理的な構造を反映してください。インデントには'''本物のタブ'''を使用します。'''スペースは使わないでください'''。大部分のクライアント環境で最大の柔軟性を得られます。
| + | |
| − | | + | |
| − | 例外: コードブロックの可読性のために必要であれば、スペースを使用してください。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | [tab]$foo = 'somevalue';
| + | |
| − | [tab]$foo2 = 'somevalue2';
| + | |
| − | [tab]$foo34 = 'somevalue3';
| + | |
| − | [tab]$foo5 = 'somevalue4';
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 連想配列の場合、値は新しい行から始めてください。注意: 配列の最後の要素に続くコンマは推奨です。配列の要素を簡単に並べ替えることができ、新しい項目が追加されても diff の結果が明確です。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | $my_array = array(
| + | |
| − | [tab]'foo' => 'somevalue',
| + | |
| − | [tab]'foo2' => 'somevalue2',
| + | |
| − | [tab]'foo3' => 'somevalue3',
| + | |
| − | [tab]'foo34' => 'somevalue3',
| + | |
| − | );
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | '''ルール''': 行の先頭はタブでインデントし、途中を揃える場合にスペースを使用してください。
| + | |
| − | | + | |
| − | ===ブレース (波かっこ) の形式===
| + | |
| − | すべてのブロックに対して以下の形式でブレースを使用してください。
| + | |
| − | <pre><nowiki>
| + | |
| − | if ( condition ) {
| + | |
| − | action1();
| + | |
| − | action2();
| + | |
| − | } elseif ( condition2 && condition3 ) {
| + | |
| − | action3();
| + | |
| − | action4();
| + | |
| − | } else {
| + | |
| − | defaultaction();
| + | |
| − | }
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | その上で非常に長いブロックがあれば、複数の短いブロックまたは関数に分割できないかを検討してください。どうしても長いブロックが必要であれば、ブロックの最後に短いコメントを書き、ブレースが何を終了するのか明示してください。目安としては35行を超える論理ブロックですが、直感的にわかりづらいコードであればコメントを追加してください。
| + | |
| − | | + | |
| − | ブレースは必ず使用してください。省略可能な場合でも使用してください。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | if ( condition ) {
| + | |
| − | action0();
| + | |
| − | }
| + | |
| − |
| + | |
| − | if ( condition ) {
| + | |
| − | action1();
| + | |
| − | } elseif ( condition2 ) {
| + | |
| − | action2a();
| + | |
| − | action2b();
| + | |
| − | }
| + | |
| − |
| + | |
| − | foreach ( $items as $item ) {
| + | |
| − | process_item( $item );
| + | |
| − | }
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 注意: 「単一文のインライン制御構造」でのブレースは使用できません。「[http://php.net/manual/ja/control-structures.alternative-syntax.php 制御構造に関する別の構文]」は使用しても構いません (例: 「<tt>if</tt>」と「<tt>endif</tt>」、「<tt>while</tt>」と「<tt>endwhile</tt>」)。これらは特に、テンプレート内で HTML に PHPコードを埋め込む際に使用されます。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | <?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; ?>
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | === 「elseif」を使うこと。「else if」は使わない ===
| + | |
| − | | + | |
| − | 「<tt>else if</tt>」は「<tt>if|elseif</tt>」ブロックのコロン構文と互換性がありません。条件式では「<tt>elseif</tt>」を使用してください。
| + | |
| − | | + | |
| − | === 正規表現 ===
| + | |
| − | | + | |
| − | POSIX 互換関数 ではなく、Perl 互換の正規表現 ([http://php.net/pcre PCRE] <tt>preg_</tt> 関数) を使用してください。「<tt>/e</tt>」修飾子は使わず、代わりに「<tt>preg_replace_callback</tt>」を使用してください。
| + | |
| − | | + | |
| − | === PHP ショートタグは禁止 ===
| + | |
| − | '''重要''' 絶対に PHP のショートタグは使わないでください。
| + | |
| − | | + | |
| − | 正しい:
| + | |
| − | <pre><nowiki>
| + | |
| − | <?php ... ?>
| + | |
| − | <?php echo $var; ?>
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 間違い:
| + | |
| − | <pre><nowiki>
| + | |
| − | <? ... ?>
| + | |
| − | <?= $var ?>
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | === 文末の空白の除去 ===
| + | |
| − | | + | |
| − | コードの各行末尾のスペースは削除してください。ファイル末尾の PHP 終了タグの除去は推奨です。終了タグを使用する場合には、その後にスペースがないことを確認してください。
| + | |
| − | | + | |
| − | === スペースの使い方 ===
| + | |
| − | | + | |
| − | コンマの後ろや、論理演算子、比較演算子、文字列演算子、代入演算子の両側には、常にスペースを入れてください。
| + | |
| − | <pre><nowiki>
| + | |
| − | x == 23
| + | |
| − | foo && bar
| + | |
| − | ! foo
| + | |
| − | array( 1, 2, 3 )
| + | |
| − | $baz . '-5'
| + | |
| − | $term .= 'X'
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 「<tt>if</tt>」「<tt>elseif</tt>」「<tt>foreach</tt>」「<tt>for</tt>」「<tt>switch</tt>」ブロックの開きかっこ、閉じかっこの両側にも入れてください。
| + | |
| − | <pre><nowiki>
| + | |
| − | foreach ( $foo as $bar ) { ...
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 関数を定義する場合は、次の形式に従ってください。
| + | |
| − | <pre><nowiki>
| + | |
| − | function my_function( $param1 = 'foo', $param2 = 'bar' ) { ...
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 関数を呼び出す場合
| + | |
| − | <pre>
| + | |
| − | my_function( $param1, func_param( $param2 ) );
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | 論理比較の場合
| + | |
| − | <pre>
| + | |
| − | if ( ! $foo ) { ...
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | 型のキャストの場合
| + | |
| − | <pre>
| + | |
| − | foreach ( (array) $foo as $bar ) { ...
| + | |
| − |
| + | |
| − | $foo = (boolean) $bar;
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | 配列要素を参照する場合には、添字が変数の場合のみ前後にスペースを入れてください。
| + | |
| − | <pre>
| + | |
| − | $x = $foo['bar']; // 正しい
| + | |
| − | $x = $foo[ 'bar' ]; // 間違い
| + | |
| − |
| + | |
| − | $x = $foo[0]; // 正しい
| + | |
| − | $x = $foo[ 0 ]; // 間違い
| + | |
| − |
| + | |
| − | $x = $foo[ $bar ]; // 正しい
| + | |
| − | $x = $foo[$bar]; // 間違い
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | | + | |
| − | ===SQL 文の書式===
| + | |
| − | | + | |
| − | SQL 文が非常に複雑な場合は、複数行に分割しインデントしても構いません。大部分の SQL 文は1行の場合と同様に動作するはずです。文の SQL の部分は「<tt>UPDATE</tt>」や「<tt>WHERE</tt>」のように常に大文字にしてください。
| + | |
| − | | + | |
| − | データベースを更新する関数は、渡されたパラメータが SQL 用にエスケープされていないと仮定して処理してください。エスケープはできるだけクエリの直前に、可能であれば「<tt>$wpdb->prepare()</tt>」を使用して実行してください。
| + | |
| − | | + | |
| − | 「<tt>$wpdb->prepare()</tt>」は SQL クエリのエスケープ、クォート、整数へのキ ャストを処理するメソッドです。<tt>sprintf()</tt> 書式のサブセットを使用します。
| + | |
| − | 例:
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | $var = "dangerous'"; // 生データ。エスケープしてもしなくても良い
| + | |
| − | $id = some_foo_number(); // integer を期待するデータ。ただし確証はない
| + | |
| − |
| + | |
| − | $wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | <tt>%s</tt> は文字列のプレースホルダーとして、<tt>%d</tt> は整数のプレースホルダーとして使用されます。注意: これらに「クォート」はありません。
| + | |
| − | 「<tt>$wpdb->prepare()</tt>」がエスケープやクォートを実行します。この結果、毎回 <tt>esc_sql()</tt> を使用する必要はありません。クエリを呼び出しさえすればエスケープは正しく処理されるため、各要素がエスケープされているかどうかを一々確認する必要もありません。
| + | |
| − | | + | |
| − | 詳細については「[[データ検証]]」を参照してください。
| + | |
| − | | + | |
| − | ===データベースクエリ===
| + | |
| − | | + | |
| − | データベースには直接触らないでください。必要なデータを取得する関数があれば、それを使用してください。クエリの代わりに関数を使用したデータベースの抽象化を利用すると、コードは前方互換性を保ち、結果がメモリー内にキャッシュされる場合は何倍も速くなります。
| + | |
| − | | + | |
| − | データベースに触る必要があると考える場合は [https://codex.wordpress.org/Mailing_Lists#Hackers wp-hackers メーリングリスト]にメッセージを投稿し、開発者と連携してください。必要な機能を備えた関数の作成が次の WordPress バージョンで検討されるかもしれません。
| + | |
| − | | + | |
| − | === 命名規則 ===
| + | |
| − | | + | |
| − | 変数、アクション、関数の名前にはアルファベット小文字を使います。<tt>camelCase</tt> は使いません。単語はアンダースコアで区切ります。不必要に変数名を省略しないでください。コードは明確に、理解可能なものにしてください。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | function some_name( $some_variable ) { [...] }
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | クラス名は大文字で始まる単語をアンダースコアで区切ります。省略語はすべて大文字にします。
| + | |
| − |
| + | |
| − | <pre><nowiki>
| + | |
| − | class Walker_Category extends Walker { [...] }
| + | |
| − | class WP_HTTP { [...] }
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 定数はすべて大文字で、アンダースコアで区切ります。
| + | |
| − |
| + | |
| − | <pre><nowiki>
| + | |
| − | define( 'DOING_AJAX', true );
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | ファイル名はアルファベットの小文字を使用して、内容を説明する名前にしてください。単語はハイフンで区切ります。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | my-plugin-name.php
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | クラスファイルの名前はクラス名を基にして、前に「<tt>class-</tt>」を付け、クラス名内部のアンダースコアはハイフンで置き換えます。
| + | |
| − | たとえば「<tt>WP_Error</tt>」の場合
| + | |
| − |
| + | |
| − | <pre><nowiki>
| + | |
| − | class-wp-error.php
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | このファイル命名規則は、すべての現行のクラスファイル、将来のクラスファイルに適用されます。例外は BackPress に移植されたコードを含む3つのファイル「class.wp-dependencies.php」「class.wp-scripts.php」「class.wp-styles.php」で、これらは接頭辞が<tt>class.</tt> のように、ハイフンの代わりにドットで始まります。
| + | |
| − | | + | |
| − | <tt>wp-includes</tt> 内のテンプレートタグを含むファイルには、分かりやすさのため名前の末尾に <tt>-template</tt> を付けてくだださい。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | general-template.php
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | === 関数の引数には意味のあるフラグ値を使用する ===
| + | |
| − | | + | |
| − | 関数を呼び出す場合は、単に <tt>true</tt> や <tt>false</tt> を使用するのではなく、文字列値を使用してください。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | // 間違い
| + | |
| − | function eat( $what, $slowly = true ) {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | eat( 'mushrooms' );
| + | |
| − | eat( 'mushrooms', true ); // true って、どういうこと?
| + | |
| − | eat( 'dogfood', false ); // false って、どういうこと? true の反対ってこと?
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | PHP は名前付き引数をサポートしないためフラグの値には意味がありません。この結果、上のような例に出会うたびに関数定義を探す必要が出てきます。ブール値の代わりに説明的な文字列値を使用することで、コードは読みやすくなります。
| + | |
| − | | + | |
| − | <pre><nowiki>
| + | |
| − | // 正しい
| + | |
| − | function eat( $what, $speed = 'slowly' ) {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | eat( 'mushrooms' );
| + | |
| − | eat( 'mushrooms', 'slowly' );
| + | |
| − | eat( 'dogfood', 'quickly' );
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 関数パラメータに説明を加えたければ、配列 $args が良いパターンです。
| + | |
| − |
| + | |
| − | <pre><nowiki>
| + | |
| − | // もっと良い
| + | |
| − | function eat( $what, $args ) {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | eat ( 'noodles', array( 'speed' => 'moderate' ) );
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | === ダイナミックフック名での変数展開の利用<span id="Interpolation_for_Naming_Dynamic_Hooks"></span> ===
| + | |
| − | | + | |
| − | ダイナミックフックの名前では読みやすさ、検索のしやすさのため、変数の連結でなく、展開を使用してください。
| + | |
| − | | + | |
| − | ダイナミックフックはタグ名に動的な値を含むフックです。例: <tt>{$new_status}_{$post->post_type}</tt> (publish_post)
| + | |
| − | | + | |
| − | フックタグで使用される変数は中括弧(「<tt>{</tt>」と「<tt>}</tt>」)で囲み、完全なタグ名全体をダブルクオートで囲んでください。こうすると PHP は、挿入された文字列内で指定された変数の型を正しくパースできます。
| + | |
| − | | + | |
| − | <pre>
| + | |
| − | do_action( "{$new_status}_{$post->post_type}", $post->ID, $post );
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | このときタグ名内の動的な値はできるだけ簡潔で分かりやすいものにしてください。<tt>$user_id</tt> の方がたとえば <tt>$this->id</tt> などよりも明確です。
| + | |
| − | | + | |
| − | === 三項演算子 ===
| + | |
| − | | + | |
| − | [[Wikipedia:ja:三項演算子|三項演算子]]は使用しても構いませんが、常に文が true かどうかをテストしてください。false のテストは混ぜないでください、混乱するだけです。ただし「<tt>! empty()</tt>」の場合は例外です。この場合は false のテストのほうが直感的でしょう。
| + | |
| − | | + | |
| − | 例:
| + | |
| − | | + | |
| − | <pre><nowiki>// (if statement is true) ? (do this) : (else, do this);
| + | |
| − | $musictype = ( 'jazz' == $music ) ? 'cool' : 'blah';
| + | |
| − | // (if field is not empty ) ? (do this) : (else, do this);
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | === ヨーダ記法 ===
| + | |
| − |
| + | |
| − | <pre><nowiki>if ( true == $the_force ) {
| + | |
| − | $victorious = you_will( $be );
| + | |
| − | }
| + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | 論理比較を行う場合、常に変数を右側に、定数や文字列を左側に置いてください。上の例で1つ等号を忘れると (白状すると、熟練のコアメンバーでもやらかします)、定数 <tt>true</tt> に代入できないためパースエラーが発生します。もし条件式が <tt>( $the_force = true )</tt> であれば、代入は構文として正しく <tt>1</tt> を返し、結果 if 文は <tt>true</tt> と評価し、そして、しばらくバグと闘うことになるでしょう。
| + | |
| − | | + | |
| − | ヨーダ記法は最初、奇妙に見えるかもしれませんが、そのうち慣れるはずです。
| + | |
| − | | + | |
| − | なおヨーダ記法は「==」「!=」「===」「!==」で使用してください。「<」「>」「<=」「>=」では読みづらいため避けてください。
| + | |
| − | | + | |
| − | === 賢いコード ===
| + | |
| − | | + | |
| − | 一般にコードの読みやすさは賢さや短さよりも重要です。
| + | |
| − | | + | |
| − | <pre>
| + | |
| − | isset( $var ) || $var = some_function();
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | 上のコードは賢いかもしれませんが、構文に慣れていなければ完全に理解するまで時間がかかります。それよりも次のように書くべきです。
| + | |
| − | | + | |
| − | <pre>
| + | |
| − | if ( ! isset( $var ) ) {
| + | |
| − | $var = some_function();
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | === エラー制御演算子 @ ===
| + | |
| − | | + | |
| − | [http://www.php.net//manual/ja/language.operators.errorcontrol.php PHP ドキュメント] によると
| + | |
| − | | + | |
| − | <blockquote>
| + | |
| − | PHP はエラー制御演算子(@)をサポートしています。PHP の式の前に付けた場合、その式により生成されたエラーメッセージは無視されます。
| + | |
| − | </blockquote>
| + | |
| − | | + | |
| − | この演算子がコア内に存在すると、適切なエラーチェックが行われずしばしば遅れて適用されます。決して使用しないでください。ちなみに PHP のドキュメントにさえ次のような箇所があります。
| + | |
| − | | + | |
| − | <blockquote>
| + | |
| − | 現在、エラー制御演算子プレフィックス"@"は、スクリプトの実行を 終了するような致命的なエラーの出力さえ抑圧します。このため、ある関数の エラー出力を抑制するために "@" を使用した場合、その関数が 利用できなかったり、ミスタイプがあった場合でも、原因を示すことなく その場所でスクリプトは終了してしまいます。
| + | |
| − | </blockquote>
| + | |
| − | | + | |
| − | === extract() は使わない ===
| + | |
| − | | + | |
| − | [https://core.trac.wordpress.org/ticket/22400 #22400] によれば、
| + | |
| − | | + | |
| − | <blockquote>
| + | |
| − | extract() はデバッグしにくいし、コードも読みにくい、ひどい関数。使うのは禁止、中で使ってるのも全部削除しよう。<br />
| + | |
| − | Joseph Scott が [http://josephscott.org/archives/2009/02/i-dont-like-phps-extract-function/ 何がそんなにひどいか書いてる]。
| + | |
| − | </blockquote>
| + | |
| − | | + | |
| − | == Credits ==
| + | |
| − | * PHP 規約: [http://pear.php.net/manual/en/standards.php Pear standards]
| + | |
| − | | + | |
| − | === 主な変更 ===
| + | |
| − | | + | |
| − | * 2013/11/13: [https://make.wordpress.org/core/2013/11/13/proposed-coding-standards-change-always-require-braces/ ブレースは常に使う。オプションの場合でも使う。]
| + | |
| − | * 2014/6/20: 「エラー制御演算子 @」の説明を追加。[http://www.php.net//manual/en/language.operators.errorcontrol.php エラー制御演算子 (@)] の使用は禁止。参照 [https://irclogs.wordpress.org/chanlog.php?channel=wordpress-dev&day=2014-06-20&sort=asc#m873356 #wordpress-dev].
| + | |
| − | * 2014/10/20: ブレースの更新 - 「制御構造に関する別の構文」の使用の許可、というか推奨。禁じられた「単一行のインライン制御構造」。
| + | |
| − | * 2014/1/21: extract() 禁止を追加
| + | |
| − | | + | |
| − | 最新英語版: [https://make.wordpress.org/core/handbook/ Core Contributor Handbook] > [https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/ PHP Coding Standards]
| + | |
| − | | + | |
| − | [[Category:WordPress の開発]]
| + | |
