m6uのエンジニアっぽい日記

PHP利用開発やFuelPHP利用開発、PostgreSQL利用開発、Androidアプリ開発、CentOS7サーバー構築など、テクニカルでエンジニアっぽい内容の日記

プログラミングQ&Aサイトに、PHPの質問を投稿する前に読んでほしいチェック項目

前提

 普段からteratailを利用していて、たまに質問を投稿するものの、大抵は回答する側にいたりします。
 その中で、どんどん質問の質が悪くなっていって、追加の情報を聞き出さないと回答に至らないケースが多くなってきています。
 質問する側も回答する側も時間を上手に使って必要な情報を獲得するために、どういう工夫をしたら回答をもらいやすくできるか、という点について考察してみました。

自分で問題解決できる力を身に着けよう

 Q&Aサイトに質問を投稿する人の多くは、「もうダメだ、わからん、教えてほしい」って気持ちのままQ&Aサイトにたどり着いて、気持ちのままに質問に書いてまとめているのだと察します。
 しかし、それでは回答する側に多大な負担をかけますし、欲しい情報が足りていない質問は放置され、なかなか解決に至りません。

 Q&Aサイトでは、いつ、誰が、回答をつけてくれるか、誰も保証しません。
 回答を得ても、それで本当に解決するとも限りません。
 だから、Q&Aサイトに頼るのもほどほどに、自分で調べて自分で解決できる力を身に着けたいものです。

文法チェックできるコーディング環境を整えていますか?

 例えばPHPにおいて「Notice: Undefined variable」とか「Parse error: syntax error, unexpected end of file, expecting ‘,’ or ‘;’」のようなよく見るエラーメッセージでQ&Aサイトに駆け込むの、こっ恥ずかしいですよ?

 自分のパソコン上に、テスト実行できる環境を整備しつつ、文法チェックくらいいつでもできるようにするべきかと存じます。
 例えば、Eclipseという開発環境ソフトウェアがあります。様々なコンピュータ言語に対応していて、文法チェックやリモートデバッグなどもサポートする強力なもので無償で使えます。これに、Pleiadesプラグインを組み合わせて日本語表示に対応させることが出来、Pleiades All in Oneとしてダウンロードできます。

f:id:m6u:20191013180729p:plain
Pleiades All in Oneの立ち位置
 Windows向けのPleiades All in Oneには、エディタ環境のEclipseだけでなく、テスト実行に使えるサーバーソフトパッケージであるXAMPP x64も含まれており、Apache httpd、PHP、Perl、MySQLに代わってMariaDBを立ち上げられます。
 もちろん、Apache httpdを単体インストールして、PHPも単体インストールしてhttpdで使えるよう設定し、データベース用にMariaDBをインストールしてphpから利用できるようにしてって丁寧にやることも出来ますが、面倒でしょ? やらないでしょ? 予め下味つけて煮込んであるレトルト食品みたいなものがPleiades All in Oneパッケージなのです。

 Eclipseの他、NetBeans IDEってのも似たような感じです。サーバーソフト類XAMPPは含んでいないので別途インストールします。
 他にも、無償で手に入る(プログラミング向け)エディタ類もオススメです。
 最近人気の、Visual Studio Codeというマイクロソフトが無償で提供するプログラミング環境は、PHPにも対応できます。
 導入事例をいくつか紹介します:

 [https://www.elp.co.jp/staffblog/?p=5620:title=Visual Studio Code で快適な PHP コーディングを行う | エレパ スタッフブログ
 VS CodeでPHPの開発をするのに導入した拡張機能 - Qiita

 他にもいろいろあるので、「php エディタ」などでネット検索して、自分にフィットするものを必ず使いましょう。

phpのコードを書いたら、いきなりwebブラウザからアクセスせず、文法チェック(lint)しよう

 ラクなのは、先に紹介したプログラミング環境(開発環境)上でコーディングしながら文法エラーをやっつけることです。
 もしもそれに至らず何らかのプログラミング向けテキストエディタを駆使するような場合、phpの文法チェックのやり方を示します。

 WindowsでXAMPPなどでPHP実行環境を用意してある前提で説明します。
 「コマンド・プロンプト」を立ち上げ、PHP.exeへのフルパスを書きます。
 続いて、「 -l 」と半角空白、マイナス、エル、半角空白を入力し、文法チェックしたいphpファイルへのフルパス名を書きます。

f:id:m6u:20191013175618p:plain
phpに於ける文法チェック(lint)の事例
 文法エラーなど問題があれば行番号を添えて指摘してくれるので、その行の前後1~2行もいっしょにチェックします。

その関数の使い方、把握してから書いていますか、古い情報に基づいていませんか

 例えば「~~って関数を使えば便利らしいぞ」と聞いてすぐ自分の書いているコードに組み込みたくなると思いますが、ちょっと待ってください。
 まず、関数のことを知るためにPHP マニュアルのサイト上で関数名を元に調べ上げます。サンプルコードもあれば、それを自分の開発環境上でも書いてみてテストします。

 次に、ネット上でその関数の使い方を解説しているページを探します。たいていサンプルコードも書いているので、これも実行して試します。
 その際に注意しなければならないのは、phpのバージョン情報と、記事の鮮度です。
 最近phpをはじめた人はPHP8.0やPHP7.4などを動かしていると思いますが、ネット上にはまだまだ古いPHP5.4/5.5/5.6向け情報やそれよりも古いものが存在します。
 ネット上の記事を参考にするときは、自分の開発環境のバージョンよりも古いものは参考にしない、PHP7以降に対応することが明示されていないものは読まないことを心がけたいものです。

 よく見かける話で、データベースMySQLを利用しようとして、古い「mysql_*」系関数を使ってアクセスする事例です。PHP7以降ではそれらの関数は廃止されています。せめて「mysqli_*」系関数にするか、PDO(PHP Data Objects)を使うようにしたいです。
 学習のために古本屋さんで見つけたPHPの本がPHP7以降に対応していないとか、あるいは職場の先輩から譲り渡された本が古くてPHP7以降に対応していないとかあるので、注意したいものです。

特にデータベースへのアクセスは、ミニマルコードで経験を積んでから取り組もう

 よく見かける事例で、bindParambindValueを取り違えて書いて実行しているケースです。
 慣れないうちはbindValueだけ覚えていればいいような気がします。
 これはPHPマニュアルの説明文を読んでも今ひとつ実感できない場面なので、ミニマルなテストコードを書いて体験していただきたいです。

 それと、PDOでのデータベースアクセスで、意図的にtry~catchを書かない事例も見ます。古いmysql_*系の手続き型の流れを汲んだものなのか、データベースへの接続だけユーザー関数にラップして使うような事例です。慣れないうちは、try~catch(PDOExeption e)するのを忘れないようにしましょう。

 この記事:PHPでデータベースに接続するときのまとめ - Qiitaには、データベース接続に関する大事な話が詰まっていて、普段のプログラミングをするときも何度も読み返して参考にしてコードを書いています。初学者に初見で伝わる内容ではないかもしれませんが、何かの折に何度も立ち戻ると良いドキュメントです。

デバッグ実行用に環境を整えていますか

 インストールしただけのphpはエラー表示をほとんどしない設定になっているため、文法エラーのある状態でwebブラウザからphp実行させると真っ白な画面になってしまいます。
 こんな状態でQ&Aサイトに駆け込むのはこっ恥ずかしいですよ?

phpのエラー表示、エラー報告レベルの調整

 デバッグ用にエラー表示をできる設定にします。
 phpインストール先にあるphp.iniというのが設定ファイルですが、ここに「display_errors」で検索して「display_errors = On」となるように書き換えます。
 同様に、「error_reporting」で検索して「error_reporting = E_ALL」になるようにします。php.iniを書き換えたら保存して、httpdがもしも動作中なら再起動します。
 より踏み込んだ話はこちら:PHPのエラー表示設定について - Qiita

ステップ実行などをサポートするXDebugモジュールも組み込みたい

 XDebugというモジュールをPHPに組み込めば、Eclipseなどからステップ実行したり変数の中身をウォッチしたりできるようになります。
https://xdebug.org/wizard.php にアクセスして、phpinfo()の内容もしくはコマンド・プロンプト上で「php -i」したときの出力を貼り付ければ、最適なバージョンのファイルを教えてくれます。
 詳しいやり方、導入事例は「php xdebug インストール」でネット検索すると良いでしょう。

なんだかんだで var_dump() で変数の中身を表示させるのも大事

 変数名を取り違えたり、何度も繰り返し同じ変数名を使ったりして、その時点でその変数にどんなデータが入っているのかわからなくなったりしませんか。
 どの時点でどういうデータが入っているのかも知らずにteratailに質問したりするとこっ恥ずかしいですよ?
 究極的には、ifブロックの条件分岐先を特定したり変数の中身をチェックしたりするのに、var_dumpが一番頼りになる情報だったりします。

Apache httpdのアクセスログとエラーログもチェックしよう

 php.iniでエラー表示してあればほぼほぼ大丈夫とは思いますが、webサーバーhttpdの出力するログも年のためにチェックするのを忘れないでください。
 XAMPPでインストールしていれば例えば「C:\xampp\apache\logs」にaccess.logやerror.logがあります。
 レンタルサーバーにphpファイルなどをおいて実行するときは、デバッグ用の設定が難しいのであればエラー情報がerror.logに出力されるのも忘れないでください。

それでも解決できない、質問しよう、その前に

 自分で解決できなくてQ&Aサイトを頼ろうというとき、事前に整理してほしいことがあります。

あなたの置かれている状況を知りたい

 山登りで言えば、どういう山に登ろうとしているのか、その山に登るのにどういうルートを辿ろうとしているのか、そして何合目まで来ているのかっていう情報がないと救助に向かうとしても向かうべき場所がわかりません。
 プログラミングにおいても同じことが言えます。
 目標として学習の一環としてECサイトを作ろうとしています、今商品一覧ページを作ろうとしています、などという感じでしょうか。
 実務(仕事)として取り組んでいて緊急性が高いのか、それとも学習の一環なのでさほど急がなくてもいいのか、という情報も、回答する側に余計な負担をかけないために欲しい情報です。
 作業をすすめる上で、頼りにしている情報もあれば、それも添えましょう。 情報が間違っている(あるいは情報が古くなって今では通用しない)とも限らないからです。

今どういう状況ですか?

 どういうシステムを作ろうとしているのか丁寧に説明がほしいです。
 「カレンダーを作ろうとしています」と聞いて、あなたが思い浮かべるカレンダーとわたしが考えるカレンダーはおそらく違うものになっているでしょう。 日めくりカレンダーもあるし、月カレンダーもあるでしょうし、世の中には様々なカレンダーがあるので、読む人に誤解を与えない丁寧な説明がほしいのです。
 ひどいのは、TwitterのようなSNSを作ろうとしています、という場合に、Twitterのどういうところを真似て、あるいはどこを省略して作っているのか想像もつかないのです。

問題解決のためにやったことを書き出してください

 「ネットで調べてみて色々試してみましたが、改善できていません」みたいなことを言う人を見かけます。
 調べ方が悪くて確かな情報にたどり着けていないケースもあれば、確かな情報にたどり着いていてもそこから大事な情報を汲み取れず見逃しているケースもありますが、うっかり誤った情報にたどり着いて間違ったことをやっていることもあるのです。
 ネット上の方法であれば、URL(と記事のタイトル)も添えて、やったことを書き出して整理してください。

第三者が状況を再現するのに必要な情報も書き出してほしい

 パソコンで作業しているなら、使っているのはWindowsなのかMacなのか。
 サーバーソフトはapache httpdなのかnginxなのか、そのバージョンはなにか。
 PHPのバージョンはなにか。 phpinfo()をwebブラウザからアクセスしてメモを取ってください。
 フレームワークの名前とバージョンも重要です。 Laravelもバージョンアップでやり方が変わってしまうため、大事な情報です。
 jsライブラリを使っているならバージョン情報も含めて大事です。
 データベースも使っているならmysqlなのかmariadbなのかpostgresqlなのかsqliteなのか、それらのバージョンも大事です。
 テストしている環境をどうやって構築したのかも、普段からメモを取ってください。 composerをどうやってインストールして、どういうコマンドを叩いてどういうライブラリやモジュールを追加したのかなどです。

エラーメッセージが表示されているなら、テキストで質問文に貼り付けてほしい

 なるべく省略せず、サーバーアクセス情報など他人に知られては困ってしまう情報は潰して、あるがままエラーメッセージを記録して、テキストのまま質問文に貼り付けてください。
 画像でも良さそうに思いますが、類似の事例をネットで探す人がエラーメッセージで検索することを想定して、有益な情報として過去のQ&Aにたどり着けるための配慮です。
 また、テキストでエラーメッセージを貼り付けておくと、慣れた回答者はそこから情報を読み解くために上手に検索にかけて助言してくれたりします。 検索のために手入力させる手間を回答者側にかけない工夫です。

もちろん文法エラーや構文エラーはないことを確認してください

 文法エラーが解消できないなら、解決する努力をしましょう。 チェックツールにかければ手がかりが見つかったりします。
 チェックしたときに示される行番号の箇所が直接の原因ではないことも多々ありますので、判断に困ったらそのことも添えて質問文に書きます。

コードの読みやすさに気を配ってください

 質問文には日本語での説明の他にphpのコードも並びます。
 teratailでは読みやすくするためにMarkDownというフォーマットでソースコード部分やログ出力メッセージなどをわかりやすく見せることができる仕組みが備わっています。
 対応しているMarkdownの記法を知りたいをよく読んで、プレビュー画面で結果を見ながら見やすさわかりやすさを工夫してください。

指摘を受けたら、早急に改善しましょう

 回答する側の人も、いつまでも暇じゃありませんし、仕事の合間に面倒を見てくれているありがたい存在なので、負担になるようなことは避けましょう。
 質問内容が拙いために回答者側に意図が伝わらないことが多々あります。 これは確認しましたか、ログファイルはどうでしたか、WindowsですかMacですか、など細かな指摘が寄せられます。
 なるべく質問を投稿したら15分程度は質問ページを再読み込みを行って、指摘事項がないかチェックしましょう。
 指摘を受けたら、一旦「今から調べてみますね」などと読んだこと、対応中であることを表明しましょう。 回答者側として、伝わっているのか伝わっていないのか気をもむことを嫌がりますので、お互いに様子が見えないのだから対応中であることを報告するべきです。
 指摘されたことを対応する方法がわからないこともあります。 わからないからといって放置してはいけません。 やりかたがわからないと正直に報告してください。 追加で助言が得られます。

回答者側に負担をかけないために、質問者側がとにかくがんばるしかない

 根本的な話として、回答者側は回答したり助言したりする行為に対して報酬を得ているわけではありませんので、いつでも離脱したり放棄したりします。
 本業が大事なわけで、本業でトラブルが生じたり、あるいは打ち合わせや商談があったりしたらそちらを当然優先します。
 わずかに割ける時間の中で、質問者のトラブル解決に力を貸してくれるわけですから、回答者側に負担をかけることを避けなければなりません。
 テキスト越しのコミュニケーションなので、リアクションがないかマメにチェックすること、報告するの時間がかかりそうならその旨報告すること、など心がけてください。

大事なのはリスペクトの精神

 親兄弟親戚でもない、赤の他人が力を貸してくれるのですから、ありがたい話ですよね。
 回答する側は仕事の合間に協力してくれるので、簡潔な言葉遣いで要件のみ伝えることが多いです。
 でも、せっかく協力してくれているのですから、質問する側はなるべく丁寧な言葉づかいで、ポイントで感謝の言葉も添えて応対してください。
 お互いに乱暴な言葉づかいで荒れてしまっては、欲しい情報すらもらえないまま退場することになってしまいますし。

PHPのプログラミングで大事なこと:アウトプットがHTMLの文法を乱していないこと

PHPのプログラミングの心得、みたいなものを少しまとめます

おそらく多くのPHPプログラミングを始めたばかりの人は、PHPのプログラミングを始める際にいきなりphpファイルをエディターで開いてコードを書き始めようとするかもしれません。
そういう人に向けて一言お伝えしたいことがあります。

PHPのアウトプットは、最終的にHTMLソースコードになるということ

PHP: PHP タグ - Manualから引用します:

PHP はファイルを解析して開始タグと終了タグ (<?php と ?>) を探します。 
タグが見つかると、PHP はコードの実行を開始したり終了したりします。 
このような仕組みにより、PHP を他のあらゆる形式のドキュメント中に 埋め込むことができるのです。
つまり、開始タグと終了タグで囲まれている 箇所以外のすべての部分は、PHP パーサに無視されます。

PHPからの出力(アウトプット)は、echo文やprint文などを使って行われますが、それらは開始タグ ~ 終了タグで囲った箇所と入れ替わる形で出力されます。
出力されたPHPの結果と、開始タグと終了タグの外側に元からあるHTMLコードとミックスされて、webブラウザに向かってレスポンスを返します。
webブラウザでは、受信できたHTMLソースコードを基にレンダリングして我々が処理結果を目にすることができるわけです。

そのため、PHPに慣れないうちはとくに、HTMLコードを書き始めるところから始める習慣をつけましょう。
作成するファイルの拡張子は「~.php」のままでもいいので、PHPのコードを書かずにHTMLコードを書き始めます。
DOCTYPE宣言、html5としての体裁、head要素とbody要素、など丁寧に書きます。
そして、ネット上にある文法チェックサービスにかけて、正しさを検証しながらイメージを固めていきます。

先にHTMLコードで下書きしてイメージを固めてから、部分的にPHPコードを組み込んでいくのが近道

どこをどうPHPの処理で置き換えて出力するのか、繰り返し箇所はどこか、なども考えながら、
仮のテキストを配置しながら文字装飾やスタイルシートを駆使して、見せ方を最初に固めてから、PHPのコードを書き始めることが大事です。
PHPやHTMLに慣れていないときこそ、この作業がその後の成果の完成度に大きく影響を及ぼします。

とくに、表示項目が多い「表組み」するときは、PHPのコードから書き始めてしまうとテーブルのタグ要素をつい忘れがちで、思ったレイアウトにならないということが発生しやすいです。
ヤバい箇所だけでも、まずはHTMLコードを書いて、どこをPHPコードで置き換えるのかをイメージしてから取り組んでください。