WordPressの公式ドキュメントであるCode Referenceで、掲載されているコード例をその場で実行できるようになった。9月上旬にMake WordPress Coreで告知されたもので、WordPress 7.1で最初の2件が公開され、7.2でさらに増える予定とされている。

対象になっているのは、たとえば WP_HTML_Processor::class_list() の解説ページだ。コードブロックに付いた実行ボタンを押すと、そのページの中で結果が表示される。ローカル環境を立ち上げたり、どこかにコピーして貼り付けたりする手間がいらない。ドキュメントを読みながら挙動を確かめられる、という形になった。

実行できるコード例は本体のコメントから作られる

興味深いのは、この実行できるコード例が、ドキュメント用に別途手作りされているわけではないところだ。WordPress本体のソースコードにあるDocBlock、つまり関数やメソッドの上に書かれているコメントの中に、そのまま書かれている。

通常のコード例との違いは、コードフェンスの言語指定を php interactive と書くことだけだという。書き方の詳細をまとめたハンドブックのページも、追って公開されるとされている。

ドキュメントとコードが離れた場所で管理されていると、更新のタイミングがずれて片方だけが古くなる。本体のコメントに書いておけば、コードを直した人が同じ場所で例も直せる。地味な話に見えるが、説明を長く正しい状態に保つうえでは効いてくる作りだ。

ブラウザの中でPHPを動かす仕組みが土台にある

実行を支えているのはWordPress Playgroundだ。もともとはブラウザの中でWordPress一式を動かすための仕組みで、WebAssemblyに移植したPHPが土台になっている。

この春に公開されたPlayground側の解説によると、<php-snippet> というカスタム要素が追加され、スクリプトタグをひとつ読み込むだけで、任意のウェブページに実行できるPHPの例を置けるようになったという。読者が実行ボタンを初めて押したときに、隠しiframeの中でPHPが読み込まれて動く仕組みで、ページを開いただけでは重い処理は走らない。

同じページに例が複数あるときは、条件が一致していれば同じ実行環境を使い回す。チュートリアルにサンプルをいくつも並べても、そのたびにPHP環境を立ち上げ直すことにはならないわけだ。既定のPHPバージョンは8.4、WordPressは最新版で、属性で指定すれば例ごとに変えられる。WordPressを読み込まず、PHPの言語機能だけを試す指定も用意されている。

自分たちのドキュメントに埋め込むこともできる

この仕組みはWordPress公式サイト専用の機能ではなく、外部のページでも使える。スクリプトを読み込み、要素の中にPHPを置くだけだ。実行前に想定される出力を先に表示しておく指定や、コードを別ファイルから読み込む指定、実行させずに色付け表示だけにする指定などもある。

Blueprintという設定用のJSONを併用すれば、実行前にmu-pluginを置いたり、オプションを設定したり、サンプルの投稿を用意したりといった下準備もできる。複数の例で同じBlueprintを共有すれば、環境を一度だけ用意して順に実行させられる。

導入時の注意点も挙げられている。Content Security Policyを厳しく設定しているサイトでは、Playground側から配信されるスクリプトと隠しiframe、そこから読み込まれる各種ファイルを許可する必要がある。それが難しい環境では、スクリプトを自前で配信して参照先を切り替える方法も案内されている。うまく動かないときは、開発者ツールで失敗している通信を確認するのが早い。