WordPressのデバッグログは記録と画面表示を分けて設定する

WordPressのPHPエラーを調べるときは、WP_DEBUGでデバッグを有効にし、WP_DEBUG_LOGでログへの記録を有効にし、WP_DEBUG_DISPLAYをfalseにして公開画面への表示を止めます。三つの定数は一組で使いますが、役割は別です。

ログを有効にしただけでは、原因は直りません。症状が出た時刻と操作を記録し、一度だけ再現して、debug.logの該当箇所を確認します。必要な情報を保存したら設定を戻し、ログを公開領域へ残し続けないところまでが一回の調査です。

三つの定数は主スイッチ、記録、表示を担当する

WordPress 3.5.1のdefault-constants.phpでは、未定義の場合、WP_DEBUGとWP_DEBUG_LOGはfalse、WP_DEBUG_DISPLAYはtrueです。公開画面へ出さずにログを取る場合は、wp-config.phpで三つを明示します。

wp_debug_mode()の公式ソースでは、WP_DEBUGがtrueの場合にだけ、WP_DEBUG_DISPLAYとWP_DEBUG_LOGの設定を処理します。WP_DEBUG_LOGだけをtrueにしても、WP_DEBUGがfalseなら、この処理はログを有効にしません。

公開画面へ出さずdebug.logへ記録する

変更前にwp-config.phpの控えを取り、同じ定数がすでに定義されていないか確認します。既存の定義があれば、下へ同じ行を追加せず、その値と位置を記録してから変更します。

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

WordPress Codexのデバッグ設定も、ログをwp-content/debug.logへ保存し、画面への表示を止める組み合わせとして、この三定数を案内しています。

標準構成では、ログはwp-content/debug.logに作られます。WP_CONTENT_DIRを変更しているサイトでは、その設定先のdebug.logを確認します。ログの場所を推測して別のディレクトリを探す前に、WP_CONTENT_DIRの定義を確認してください。

ログが作られないときは定数の依存関係から確認する

設定後にdebug.logが見つからない場合は、書き込み権限を一律に広げる前に、三つの定数を読み直します。

最初に、WP_DEBUGが真偽値のtrueかを確認します。'false'のように引用符で囲んだ文字列は、PHPでは真偽値のfalseではありません。値の型まで確認します。

次に、WP_DEBUG_LOGがtrueで、WP_DEBUG_DISPLAYがfalseかを確認します。wp-config.phpの別の場所で同じ定数を定義していないか、WP_CONTENT_DIRを変更していないかも調べます。そのうえで、ログの保存先へPHPが書き込めるかをサーバーの設定とエラーログで確認します。wp-content全体を無条件に書き込み可能へ変える方法は採りません。

エラーが発生していなければ、ログが増えないこともあります。ログを作るために公開サイトへ故意のエラーを入れず、問題が起きる既知の操作を一度だけ再現します。

発生時刻と操作をログの行へ対応させる

調査前に、問題が出るURL、操作、発生時刻を記録します。設定を変えた時刻も残します。既存のdebug.logがある場合は、調査開始前の末尾を控えます。過去の警告と、いま再現した症状を混ぜないためです。

設定後は、問題が出る操作を一度行い、ログ末尾の時刻、メッセージ、ファイル名、行番号を読みます。同じ操作で同じ行が増えるかを確認してから、対象のプラグイン、テーマ、またはPHPファイルを絞ります。

一つの警告が見つかっただけで、原因と断定しません。発生時刻が合うか、症状を起こす操作と対応するかを見ます。複数のファイルを同時に直すと、どの変更で症状が変わったか分からなくなります。修正候補は一つずつ試し、ログと画面を同じ条件で確認します。

debug.logを公開領域へ残し続けない

標準のwp-contentは、公開ファイルと同じ領域にあります。debug.logがURLから読めないことを確認し、必要な箇所を管理側へ保存したら、サーバー上のログを削除するか公開領域の外へ移します。エラー文を外部へ渡す場合は、ファイルの絶対パス、利用者の入力値、接続情報などが含まれていないかを確認します。

調査が終わったら、変更前に記録した値へ戻します。調査のために定義を追加した場合は、その追加行を取り除きます。WP_DEBUGをfalseへ戻しただけで終わらず、公開画面に警告が出ないこと、debug.logが増え続けていないこと、調査対象の機能が動くことを確認します。

ログを常時残す必要があるサイトでは、保存場所、閲覧できる担当者、保管期間、削除方法を先に決めます。設定作業を制作会社へ依頼しても、ログの保管責任と閲覧権限まで自動で委託されるわけではありません。

デバッグ設定と原因の修正を分ける

WP_DEBUG、WP_DEBUG_LOG、WP_DEBUG_DISPLAYは、原因を観察するための設定です。プラグインを停止する、テーマを切り替える、PHPファイルを修正するという作業とは分けます。

まず、三定数で公開画面への表示とログへの記録を分けます。次に、問題が出る一つの操作とログの時刻を対応させます。最後に、原因候補を一つだけ変更し、同じ操作で結果を確認します。設定を戻し、ログを片付けるまでを作業記録に残せば、次の担当者も同じ条件で再確認できます。