PHP マニュアルを書いた話

はじめに

この記事は PHP Advent Calendar 2021 、最終日の記事です。

https://qiita.com/advent-calendar/2021/php

最近、PHPマニュアル 英語版の中身をいくつか書く機会に恵まれました。誰かの得になる知見とは思えないなーと思いつつも、ここに言語化して記録しておきたいと思います。

多くの PHPer が目にするはずの PHPマニュアルそのものや、それを支える中の人、裏事情などについて、少しだけ目を向けられるような読み物になればと思います。

自己紹介

PHPマニュアル 日本語版 のメンテナンスを github でやりつつ、英語版についても編集の落ち穂拾いをちょくちょくやっています。

後述しますが、 PHPコア言語 (php-src) の開発者では ありません。

そんな人が PHP のマニュアルなんて書けるの？ という疑問を持たれるかもしれません。その点については、以下で明らかにしていきます。

実際に書いたPHPマニュアル

主なものを挙げると、下記のものを英語で追加しました。

• PHP 7.3 以降、ヒアドキュメント/Nowdoc のインデントが可能になった件
• PHP 8.1 の新機能や非互換に関するドキュメント
  • 配列のアンパック
  • 読み取り専用プロパティ
  • クラス定数に final が指定できるようになった件
  • 第一級callableを生成する記法
  • CURLStringFile
  • その他、非互換になった変更をいくつか
    • $GLOBALS 配列全体が書き込み禁止になった件

何年もドキュメント化されていなかった機能や、PHP 8.1 の新機能に関するものが主です。

リリースされてから3年もの間、ドキュメント化されていなかったものもあります。
以下がそうなのですが、皆さん使ってなかったのでしょうか... そんなことないですよね！

// ヒアドキュメントをスペース4つ分インデントする
// PHP 7.3 より前のバージョンではインデントできず、エラーになっていました。
echo <<<END
      a
     b
    c
    END;

どうして書いたの？

「書く人が少ないから」ということと、「公式ドキュメントであること」によって 多くの人に見られていること が大きいです^[1]。

後述しますが、PHP という言語本体に加えられる変更は様々なプロセスを経て決まります。ですが、実際に変更をする人がマニュアルを書ける人かというと、必ずしもそうとは限りません^[2]。また、コア言語の開発と、整合性が取れたマニュアルを記述することの間にはそれなりのギャップがあることも事実です。

言語の実装とユーザー向けの文書の間の橋渡しを行う人間が、ドキュメントを書く人間ということになります。ただ、コードを書いている皆様ならわかると思いますが、ドキュメントを書くのは非常に面倒です。長期に渡って整合性を取るように維持する必要があるのなら、なおさらです。

一方で、アプリケーションの開発者が、一番参照するドキュメントが PHPマニュアル であることもまた事実です。「公式ドキュメント」として見られるという変な緊張感がありつつも、無理のない範囲で（重要！）それを楽しんでいることも、貢献できるひとつの理由であると思っています。

PHPマニュアルを書くのに必要なこと

ユーザー視点からPHPの動作を把握して記述することが、PHPマニュアル については一番重要であるというのが自分の感想です。

PHPコア言語の開発者である必要はある？

PHPマニュアル を書くのに、コア言語の開発者である必要は必ずしもありません。

マニュアルのメンテナンスやバグ修正をしている人の多くが、コア言語の開発者であることは事実ですが、私のようにそうでない人もいます。

ただ、コア言語に関する知識が深いほうが、マニュアルへの変更を短い時間で、確実に行うことが出来る確率が高いとは言えます。私のように知識が少ないと、マニュアルに書くことが嘘でないと確信を得るために、もろもろ調べるコストがどうしてもかかるからです^[3]。

実際に必要なスキル

では、実際に必要とされるスキルは何でしょうか？
重要な順に、上から下に並べると下記のようになります。

1. マニュアルに書くべき情報を取捨選択できる能力
2. PHP のソースコード を grep すれば、どこに書いてあるかアタリを付けられる
3. 少しの英語力
4. PHP のドキュメントに関するエコシステムの知識

「PHPコア言語を変更する能力」とは全く書いていない ことからも、コア言語の開発者である必要はないことがわかります。

以下、詳細を見ていきましょう。

マニュアルに書くべき情報を取捨選択できる能力

この能力が最も重要です。

PHP に加えられる変更を決める場としては、RFC をベースにした議論/投票, PHP internals ML, Pull Request などがあります。特に、コア言語に加える変更を提案し、オープンなコミュニティで議論/投票するための文書 「RFC」 は、マニュアルのベースとなることが多いという意味でも非常に重要です。

しかし 「RFC」は、コア言語の開発者を説得するための文書 であり、PHP を使ってアプリケーションを書く開発者向けではありません。よって、アプリケーションの開発者からして見ればノイズになる情報がとても多くあります^[4]。

例を挙げましょう。

PHP 8.1 から $GLOBALS 変数へのアクセスについて、多くの制限が適用されました。この変更を説得するためのRFC には、$GLOBALS 変数の現状の動作、および内部動作、変更すると起こる内部的なインパクトなどが多数説明されています。

ですが、アプリケーションの開発者視点からは、以下の情報のみを記述すれば必要にして十分です。

• $GLOBALS 配列全体への write 操作はエラーになる。
• $GLOBALS のコピーを通じて、グローバル変数を直接書き換えることができなくなった。

そのことだけを反映したマニュアルの変更をスクショで示すと、下記2点のみになります。

コア言語の開発者向けの情報を削ぎ落とし、アプリケーションの開発者向けに必要な情報だけを拾い出し、最低限の文章とサンプルコードだけで過不足なく説明することが求められます。

PHP のソースコードを grep すれば、どこに書いてあるかアタリを付けられる

マニュアルの内容が正しいかどうかの議論の材料が、 ソースコード(php-src) やテストコードになることがままあります。よって、いざとなればそれらをざっくりとで良いので調べることができるのが望ましいです。

アタリをつける例として、PHPの緩やかな比較の実態 という記事には、== 演算子の実装に辿り着く方法が説明されています。

少しの英語力 / PHP のドキュメントに関するエコシステムの知識

これらについては、ぶっちゃけ周囲が補ってくれます。

私は英語が得意ではありません。また、たとえマニュアルの構造やマークアップ、そして内容的に望ましくないコミットがなされたとしても、バージョン管理システムの威力で、いつでもやり直せるからです :)

PHPのドキュメントに関するエコシステムについて、興味がある方は 「PHPマニュアル 日本語版について」 をお読み下さい。

ドキュメントを書くということ

ところで、ドキュメントを書いたり翻訳したりすることは、とても地味なタスクに見えます。コードを書くことに比べると、目立たない、つまらない仕事と見なされがちです。

私はそうではないと思っています。

なぜなら、PHPマニュアル について言うと、なにせ公式マニュアルには嘘が書けないので、もろもろ周辺情報を調べる必要があるからです。本当にこの動作なのか。php-src のコード的にはどうなのか。他の部分との整合性は取れているか... などなど。

ブログを書いたり技術カンファレンスで発表をしたり、雑誌に執筆する時など、何かしらのアウトプットをすることを想像してみて下さい。嘘は言えないので似たようなことをする気がしませんか？

そんな感じで、私は PHPマニュアル を書いたりメンテナンスしたりすることを、自分のための インプット/アウトプット のひとつの形 だとみなしています。その結果として、多くの人に役立つことがあれば... と思っています。

おわりに

最後までお読み頂き、ありがとうございます。PHPマニュアルそのものは今年から github で管理されるようになった ^[5] ことで、ML 経由で報告するしかなかった以前と比べて格段に貢献のハードルが下がりました。

ただ、実際に手を動かしている人はとても少ない^[6]ため、PHP マニュアルの間違いを報告したり、翻訳を追加するなどの作業は常に歓迎されます。興味を持たれた方は、CONTRIBUTING.md を是非読んでみて下さい。

特に、PHPマニュアルに間違いを見つけた際は、Pull Request を宜しくお願いします！

脚注

1. このエントリに書いてあることは総じて綺麗事に見えるかもしれませんが、言ってしまえば「ドキュメントは見られてナンボ」をモチベーションにしているということです。

2. たとえば最近 JetBrains を退社したコア開発者 Nikita Popov (nikic) は、PHP 8.1 に対する多くの新機能を手掛けましたが、自分では 8.1 関連のマニュアルを全く書いていません。

3. 私のような人が PHPマニュアル を書いている現状は「誰が書いたものであれ、良いものを書けばマージされる」という状態でもあるわけですが、これがあるべき姿なのかはまた別の話です。

4. RFCは「コア言語の開発者を説得し切った優れた文書である」という見方もできます。その目的のためには、必要十分な情報が過不足なく記述されており、無駄な贅肉は一切ない文書とも言えるでしょう。こうした性質から、サンプルコードや説明の一部が PHPマニュアル にそのまま引き写されることもしばしばです。

5. git.php.net で悪意のあるコミットが行われた事案 が発生したために移行が行われました。現在は bugs.php.net も含めた issue の管理も github に移すことが検討されています。

6. このエントリを書いている時点で、日本語版について手を動かしているのは私一人です！(汗
   また、マニュアルのメンテナと直接話すことが出来る PHPユーザーズ Slack も開設されています。興味がある方は Slackin から join するか、日本語で PHP の話をする Slack のグループを作ったよ を参照して下さい。