2026年5月10日(日)

PHPとJavaScriptで「名前が任意か所定か」を切り分ける

PHP
JavaScript
WordPress

背景

PHP や JavaScript で関数や変数を書くとき、自分が付ける名前が「自由なラベル」なのか、それとも環境側が決めた「決まった名前」かが頭のどこかでぶつかって、読み進めやすさやデバッグのしやすさに影響することがあります。その切り分けをメモとして残した記事です。**学習中に混同しがちな「関数へ渡す値を束ねる変数名」と「配列・オブジェクト側のキー名」**も、同じ線上に並べられます。

目的

名前が任意のケースと、所定・外側の仕様に沿うケースをできるだけ早く見分けるための、「最初に自分へ投げる問い」を持つことを目的にしています。「暗記パターンの列挙」より、読みどころを共有する構成にしました。

任意の場合の具体例

ここでの「任意」は、言語として妥当な名前（PHP の変数規則、JavaScript の識別子規則など）に沿う範囲での話です。意味は変わらず、自分の読みやすさで選んでよいという意味です。

ローカル変数につけている名前

同じ値を渡すだけなら、ラベルを変えても挙動は変わらないことが多いです。

const opening = '<h2 class="ttl">';
document.querySelector('main').insertAdjacentHTML('beforeend', opening);

を

const x = '<h2 class="ttl">';
document.querySelector('main').insertAdjacentHTML('beforeend', x);

にしても、この断片だけでは結果は同じです（名前は「参照のための自分用ラベル」）。

「位置」の引数に渡しているだけの値

関数呼び出しで 何番目の引数に何が入っているかだけが規約で、自分が束ねる側の変数名は書き手側の都合、というタイプです（テンプレートタグなどで、$before 相当を $opening とかで組み立ててから渡す、その変数名）。

（WordPress）`the_title` と位置引数の直前の変数名

the_title() の第1引数・第2引数は「タイトルの前後に付けるマークアップ」、第3引数は表示するか戻り値にするかの切り替えです。Code Reference のシグネチャどおり、順番と意味が決まっている一方で、値を変数に入れるときの名前は自分の読みやすさで選べます。

$opening = '<h2 class="ttl">';
$closing = '</h2>';
the_title( $opening, $closing, false );

$x = '<h2 class="ttl">';
$y = '</h2>';
the_title( $x, $y, false );

この2つは同じ呼び出しになります（the_title という関数名と引数の並びは所定です）。

所定の場合の具体例

「所定」とはここでは、API・仕様書・オブジェクト形状・イベント名など、外側の仕様として文字列やキーが固定されている／揃える必要があることを指しています。

オブジェクトの「仕様済み」のキー

ライブラリやフレームワークが「このキーを読む」と文書している場合、そのキー文字列・プロパティ名は自分の好みでは置き換えられません。

new ResizeObserver(() => {}).observe(document.body, { box: 'border-box' });

observe に渡す第2引数のオブジェクトは Resize Observer の記述どおりでなければなりません。

REST レスポンスなど「形が決まったデータ」のプロパティ名

例として、トークンのキーが access_token であるかのような、転送側の JSON の形がある場合があります。自分のコード側で読むときも、その名前に合わせて参照します。

（PHP・WordPress）`WP_Query` の引数配列のキー

WP_Query に渡す配列では、クエリ変数ごとにキー名が仕様化されています。キーを自分の好みの単語に置き換えると解釈されず、意図と違う結果になりがちです。

$args = [
    'post_type'      => 'post',
    'posts_per_page' => 5,
];
$query = new WP_Query( $args );

'post_type' や 'posts_per_page' は WordPress 側が解釈する所定の名前です（例として 'posts_per_page' を 'limit' に変えても、ループの件数指定としては読まれません）。
同じ話は register_post_type() の第2引数 $args のキー名などでも繰り返されます。

（PHP 8+）名前付き引数のパラメータ名

関数定義にある仮引数名そのものに合わせる必要があり、自分の都合で別語に差し替えてはなりません。

DOM イベント名・フック文字列など

addEventListener('click', handler) の 'click' や、アプリ側のフック 'init' のような識別子は、ドキュメント上の名前と一致させることが前提です。**変数名ではなく「仕様どおりの文字列」**に近い階です。

区別の仕方

迷ったときには、順にこう自分へ問えると見通しがよくなった、という自分用チェックリストです。

いま名前を付けているのは、「自分だけが読む記号」（ローカル変数など）ですか。 それなら多くは「任意」（ただし可読性は別問題）。
その名前は、関数のパラメータ位置・リテラルのキー・イベント名など「外側の仕様」の一部になっていますか。 はいなら「所定」寄り。公式リファレンスや型定義の該当行をひとこと開く癖と相性がよいです（PHP では wordpress.org の Code Reference、ブラウザ API では MDN を例にできます）。
「自分の名前」か「環境の仕様で決まる名前」かだけ切り離して考える。位置引数に渡しているのは値であり、自分で付けた $opening と $x の差は関数からは見えないことが多い、という視点があります。

断言が難しい場面（プラグインの「オプション配列」を薄くしか文書していない等）は、その場で console.log(obj)／error_log(print_r(..., true)); で実形状を確認してから名前を当てはめる、という逃げも実務向きです。

まとめ

任意は、「自分が束ねているローカルのラベル」や「順番だけが意味を持ち、変数名自体は関数に伝わらない」パターンに出やすい。
所定は、「オブジェクトのキー」「名前付き引数」「イベント名・フック名」「HTTP の JSON」のように、外部仕様の表面にある名前に出やすい。
区別には 自分の名前か・仕様側の名前かと、リファレンスを一度開けるかどうかという二つのレバーを使うとよかった、という整理でした。