PHPのヒアドキュメントは色々な場面で使えて便利ですよね。
でも不便な点が１つあって、それが直接コメントを書けないということです。
ヒアドキュメントによる出力は１つの文字列として扱われるので、 /** コメント */ とか /// コメント みたいに書くことは当然できません。
ただし少しトリッキーな方法を使えばPHPでの形そのままで書くことも可能です。
そこで僕自身よく使っているヒアドキュメント内でコメントを書く方法をまとめました。
方法１．出力言語に対応したコメントを書く
まず１つめの方法はヒアドキュメントで出力中の言語に応じたコメントを書くという方法
出力中の言語っていうのは HTML とか JavaScript とか CSS のことです。真っ当に考えると真っ先にこの方法がコメント出力のやり方として浮かびます。（トリッキーな方法については次で紹介）
例えば各言語でヒアドキュメント中にコメントアウトする方法は次の通りです。
まず次がHTML出力中でのコメントの書き方
1 2 3 4 5 6 | echo <<<EOM <!-- 名前を入力するテキスト欄 --> <input type="text" name="your-name" /> <!-- 年齢を入力するテキスト欄 --> <input type="text" name="your-age" /> EOM; |
<!-- と --> で囲むことでコメントアウトできます。ちなみにコメントは複数行にわたって記述できるので改行が入っても問題ありません。ただし、初めの <!-- は続けて記述する必要があるので要注意。
そして次がJavaScript出力中のコメントの書き方
1 2 3 4 5 6 7 8 9 10 11 | echo <<<EOM <script> /** 全て読み込み後にjQuery実行 */ $(function(){ $('.btn').on('click', function(){ /// アラート表示 alert('Hello!!'); }); }); </script> EOM; |
これもHTMLと同様、お馴染みですよね。複数行コメントの場合は /* ～ */ という形式が、１行コメントの場合は // ～～ が使えます。
そして次がCSS出力中でのコメントアウトの例
1 2 3 4 5 6 7 8 9 10 11 12 | echo <<<EOM <style> /** フレックスコンテナ */ .flex-container{ position: flex; } /** フレックスアイテム */ .flex-item{ flex-basis: 50%; } </style> EOM; |
CSSの場合はJSと違って /* ～ */ の複数行コメントしか使えません。 ///～～ みたいな１行コメントを使うと解析エラーになることに注意
以上が各言語ごとにコメントアウトする方法です。
ただしこの方法はHTMLとかスクリプト・スタイル出力に限定でしか使えないです。
あと実際にコメント部分まで出力されてしまうので次の欠点もあります。
- 転送量が少しだけ増える
- ページ表示速度にも微影響
まあ転送量とか表示速度に影響を与えるといっても無視できるレベルかもしれません。でも速さを求めるならなるべく無駄な情報はなくしたいですよね。
そこで役立つのが次の変数展開を使った少しトリッキーな方法です。
方法２．変数展開を使ってコメントを書く
お次はヒアドキュメントでの変数展開を利用してコメントを書くという方法
PHPのヒアドキュメントでは変数名を直接書く、あるいは ${変数名} または {$変数名} みたいな書き方をすると変数の値を展開できます。
例えば次がヒアドキュメント内で変数展開しているコード例
1 2 3 4 5 6 | $pyoko_x2 = 'ぴょこぴょこ'; echo <<<EOM かえる{$pyoko_x2}み{$pyoko_x2} あわせて{$pyoko_x2}む{$pyoko_x2} EOM; |
上コードだったら {$pyoko_x2} が出力中に "ぴょこぴょこ" という文字列で展開されます。
そして実はこの変数展開、次記事で紹介したように無名関数を使えば変数以外に関数・式そのものを展開することができます。
なので変数展開を応用すればヒアドキュメント内にPHP形式のコメントを直接書くことも可能です。
例えば無名関数を使ったコメントの書き方例を出すなら次の通りです。
1 2 3 4 5 6 7 | /** 空の無名関数を定義 */ $COMMENT = function(){}; echo <<<EOM {$COMMENT(/** 空の無名関数を使えば・・・ */)} {$COMMENT(/** PHP形式のコメントが書けるよ！ */)} EOM; |
まず $COMMENT = function(){}; で何もしない無名関数を作成。あとはヒアドキュメント内で {$COMMENT(/** コメント */)} みたいに引数内にコメントを書けばいいだけです。
何も出力しない、値も返さない関数なので出力に影響を与えることもありません。
方法３．空配列を使ってコメントを書く
最後は変数展開と空配列をうまい具合に応用してコメントを書くという方法
先ほど書いたようにヒアドキュメント内では ${変数名} または {$変数名} みたいな書き方で変数の値を展開できます。ですが展開できるのは変数だけではありません。
実は配列や文字列などのリテラルも展開することができます。
そのことについてPHP公式リファレンスで書かれているのが次の部分（引用）
どんなスカラー変数、配列の要素あるいはオブジェクトのプロパティの文字列表現であっても この構文で含めることができます。 文字列の外側に置く場合と同様に式を書き、これを { と } の間に含めてください。
つまりスカラー変数（つまり基本型の変数）はもちろん、連想配列やクラスのプロパティなども展開できるということです。
実際に例を出すなら次のコードを書いてもエラーになりません。
1 2 3 4 | echo <<<EOM ${[1, 2, 3, 4, 5]} ${"This is string"} EOM; |
勘のいい人ならこの時点で気づいたかもしれないです。
そうです、これを応用すればヒアドキュメント内でかなりスマートにPHP形式のコメントが書けます。
例えば空の配列を使ってコメントを書くなら次のような感じ
1 2 3 4 | echo <<<EOM {[/** 空の配列を使えば・・・ */]} {[/** PHP形式のコメントが書けるよ！ */]} EOM; |
さっきの無名関数を使うよりさらに簡潔な書き方になりました。もちろん空の配列なので出力に影響を与えることもありません。
追記：この方法はやっぱり駄目だった...
空の配列を使う方法はかなりスマートだし完璧・・・と思ってたんですが、この記事を公開した後で致命的な欠点を発見してしまいました。
それは次のような Notice のエラー表示が出てしまうことです。
1 2 | PHP Notice: Array to string conversion in /workspace/Main.php on line 5 PHP Notice: Undefined variable: Array in /workspace/Main.php on line 5 |
やっぱり空の配列を渡すのは正規の方法ではないみたいですね。出力言語ごとにコメントを書くか、無名関数を使うかのどっちかを使う方が確実で安全だと思います。
ここまでのまとめ
ということで紹介した方法をまとめると次の通り
- 出力言語に応じて書く方法ヒアドキュメント出力の対象が HTML 、 JavaScript 、 CSS などならその言語の形式で書くことができる。ただしコメントも一緒に出力されるのが難点
- 無名関数を使う方法何もしない無名関数を作り、その中で {$COMMENT(/** コメント */)} のように書けばPHP形式でコメントを書くことができる。現時点で最適解
- 空配列を使う方法変数展開にはリテラルも使えるので ${[/** コメント */]} のように書けばもっと簡潔に書くことも可能。Noticeエラーが出るのでやっぱり使わない方が安全・・・
最後の方法はエラーが出なければ完璧でしたね・・・まあ正しい方法ではないので１番目か２番目のどっちかを用途に応じて使い分けるのが最適だと思います。
以上、PHPのヒアドキュメント内でコメントを書く方法についてでした。
