開発用ログを記録する関数 dd()

本日は Drupal (ドルーパル) が提供する便利なユーティリティ関数群の中から開発 / デバッグに有用な dd() 関数をご紹介できればと思います。

dd() 関数とは

dd() 関数は、デバッグ用ログファイルに変数の中身を書き込んでくれる関数です。 実は Drupal コアには含まれておらずコントリビュートモジュール Devel が提供している関数なので、利用するには Devel モジュールのインストールと有効化が必要です。

ちなみに関数名の dd は「 Drupal Debug 」の省略形です。 その中身も別の関数 drupal_debug() にすべて処理を任せているので、 dd() は実質 drupal_debug() 関数のエイリアス関数、といった位置づけになります。

では、ここからは実際に使い方を見ていきましょう。

dd() 関数の使い方

準備

上述のように dd() 関数は Devel モジュールの中で定義されているものなので Devel モジュールの有効化が必要です。 Drush が導入済みの場合には次のコマンドを実行すれば OK です。

$ drush -y en devel

Drupal のコントリビュートモジュールは Drush を使わなくてもさまざまな方法でインストールすることができます。 インストール方法がわからない方は次の記事などをご参考にしてみてください。

• Drupal のモジュールのインストール方法

Drush のインストール方法は次の記事などでご紹介していますので Drush に興味がある方はこちらもよろしければ。

• Drupalの開発効率を劇的に向上させるDrushのインストール方法8通り
• Composer で Drush をインストールする方法

使い方

Devel モジュールをインストールしたら、後は任意の場所で dd() 関数を呼び出すだけです。 dd() の出力結果は Drupal のテンポラリディレクトリの直下の drupal_debug.txt というログファイルに書き込まれます。

まずは dd() 関数の使い方から。

デバッグ用に変数を出力したい場所で dd() 関数を呼び出します。 「関数シグネチャ」と呼んだらよいでしょうか、関数の宣言部は次のようになっているので最小限ひとつの引数 ($data) を渡せば OK です。

function dd($data, $label = NULL)

第 2 引数の $label はオプションで、出力する変数名の前に ラベル名: という形でラベルを追加したい場合に使用します。 ごくシンプルな変数の確認の場合にはこの第 2 引数は使用しなくてもよいでしょう。

つづいてログファイルのありかについて。

上述の drupal_debug.txt が置かれるテンポラリディレクトリは Drupal の管理画面のファイルシステム ( /admin/config/media/file-system ) のところで設定されているものです。 Mac 環境の場合だとデフォルトで /tmp が設定されています。

サンプル

今回は試しに、コンテンツ（ノード）の本文のフォーマットを「 PHP コード」にして、ここに dd() 関数を書き込んでみましょう。

コンテンツの本文のフォーマットに「 PHP コード」を選べるようにするためには Drupal コア内の PHP Filter モジュールを有効化する必要があります。 PHP Filter のマシン名は php なので Drush なら次のコマンドを実行しましょう。

$ drush -y en php

つづいて、「 PHP コード」を選択可能なユーザでログインした後、適当にノード（コンテンツ）の新規作成ページを開きます。 テキストフォーマットに「 PHP code 」を選択し、本文に以下のコードを書き込みましょう。

// dd() 関数のテストです。
dd("Hello, I'm in the dd() func.");

保存して、作成したばかりのページを開いてみましょう。 設定が問題なくいっていれば、画面が表示される度に dd() 関数が実行されるはずです。

では、結果を確認するために、システムの方でテンポラリディレクトリの drupal_debug.txt を見にいってみましょう。 Mac の場合のデフォルトのファイルパスは /tmp/drupal_debug.txt です。

drupal_debug.txt ファイルが存在して、上の画像のような内容が書き込まれていればロギングは無事成功、です。

以上です。

今回は開発 / デバッグフェーズで便利な dd() 関数のご紹介でした。

今回は説明をかんたんにするため dd() 関数に文字列を渡しましたが、通常は変数を直接渡す形で OK です。 内部的には print_r() 関数が使われているため、配列やオブジェクトなども整形した形できれいに表示してくれます。

ちなみに、 Drupal 7 の場合関数の中身は次のようになっています (コメントの部分は私の日本語訳です。元のコードの正確なニュアンスが知りたい方は Devel モジュール内の devel.module の中身を覗いてみてください)。

/**
 * drupal_debug() のエイリアス。
 */
function dd($data, $label = NULL) {
  return drupal_debug($data, $label);
}



/**
 * サイトのテンポラリディレクトリの中の drupal_debug.txt に変数を書き込みます。
 *
 * @param mixed $data
 *   ログファイル drupal_debug.txt に書き込みたい変数。
 * @param string $label
 *   (オプション) セットされた場合は $data の出力の前のラベルになります。
 *
 * @return void|false
 *   成功した場合は空、ログファイルが書き込み不能だった場合は FALSE を返します。
 *
 * @see dd()
 * @see http://drupal.org/node/314112
 */
function drupal_debug($data, $label = NULL) {
  $out = ($label ? $label . ': ' : '') . print_r($data, TRUE) . "\n";

  // テンポラリディレクトリは複数の simpletest インスタンスにまたがることがあります。
  $file = file_directory_temp() . '/drupal_debug.txt';
  if (file_put_contents($file, $out, FILE_APPEND) === FALSE) {
    drupal_set_message(t('Devel was unable to write to %file.', array('%file' => $file)), 'error');
    return FALSE;
  }
}