2022.12.10

Craft CMS のデバッグに Ray を利用する

Craft CMS のテンプレートを実装する際、変数やオブジェクトの内容を確認したいときがあります。

Craft 3.2 以降、Twig の独自タグとして {% dd %} が追加され、プラグインを追加することなく内容を確認しやすくなりました。

とはいえ、都度都度 Twig タグの追加・削除をするのはちょっと面倒ですよね。

そこで、今回は Ray プラグインを利用したテンプレートのデバッグ方法についてご紹介したいと思います。
これは Craft CMS Advent Calendar 2022 10日目の記事です。

Ray とは？

Ray は、ローカル・リモート環境のデバッグ情報の出力内容を確認できる、デスクトップアプリケーションです。

Understand and fix bugs faster using Ray - Ray
https://myray.app/

サブスクリプションモデルの有償アプリ（執筆時点で年額4,639円）ですが、Craft CMS 専用ではなく PHP・JavaScript・Laravel・WordPress・Vue などでも導入できるため、重宝しています。

Craft CMS での導入方法

Craft CMS で Ray を利用するには、事前にプラグインのインストールと初期設定が必要です。

プラグインのインストール

管理画面のメニューから プラグインストア に移動し、Ray で検索します。

アセット編集画面のサンプル

プラグイン詳細にある「インストール」ボタンをクリックして、インストールします。

インストールできたら 設定 > プラグイン 枠にある「Ray」アイコンをクリックして管理画面上で直接設定してもよいのですが、過去記事でも紹介したプラグイン設定を専用ファイルとして用意するのがオススメです。

プラグイン設定の準備

Craft CMS のインストールディレクトリ直下の config/ に create-ray.php を作成します。
公式ドキュメントのサンプルコードをベースにすると効率的です。

<?php
// Save this in a file called "craft-ray.php" in the config directory of your project

use craft\helpers\App;

return [
    /*
    * This settings controls whether data should be sent to Ray.
    *
    * By default, `ray()` will only transmit data in non-production environments.
    * Add `RAY_ENABLED=true` in your .env file.
    */
    'enable' => App::parseBooleanEnv('$RAY_ENABLED'),

    /*
    * The host used to communicate with the Ray app.
    * For usage in Docker on Mac or Windows, you can replace host with 'host.docker.internal'
    * For usage in Homestead on Mac or Windows, you can replace host with '10.0.2.2'
    * Add `RAY_HOST=localhost` in your .env file.
    */
    'host' => App::env('RAY_HOST'),

    /*
    * The port number used to communicate with the Ray app.
    */
    'port' => 23517,

    /*
     * Absolute base path for your sites or projects in Homestead,
     * Vagrant, Docker, or another remote development server.
     */
    'remote_path' => CRAFT_BASE_PATH,

    /*
     * Absolute base path for your sites or projects on your local
     * computer where your IDE or code editor is running on.
     */
    'local_path' => App::env('RAY_LOCAL_PATH'),

    /*
     * When this setting is enabled, the package will not try to format values sent to Ray.
     */
    'always_send_raw_values' => false,
];

次に App::parseBooleanEnv や App::env で定義した環境変数をインストールディレクトリ直下の .env に追記します。

RAY_ENABLED=true
RAY_HOST="host.docker.internal"
RAY_LOCAL_PATH="/PathTo/craft4core"

ここでは RAY_HOST は Docker 環境向けの設定値、RAY_LOCAL_PATH はローカル環境のパスをセットしています。

使ってみる

よく使うコードをいくつかご紹介します。

変数の出力

変数や配列、オブジェクトなどの内容を確認できます。

{# 変数を出力 #}
{% set foo = '出力サンプル' %}
{% set bar = [1, 2, 3, 4, 5] %}
{{ ray(foo, bar) }}

{# オブジェクト #}
{% set entry = craft.entries.section('news').one() %}
{{ ray(entry) }}

変数の出力

ログの色分け

ログを色分けして出力します。Ray のアプリケーションウィンドウ上部中央にあるアイコンをクリックすると、特定の色だけに絞り込めます。

{% set foo = '出力サンプル' %}
{{ ray(foo).green() }}
{{ ray(foo).orange() }}
{{ ray(foo).purple() }}
{{ ray(foo).blue() }}
{{ ray(foo).gray() }}

ログの色分け

実行時間と最大メモリ使用量

過去記事でご紹介したようなテンプレートのレンダリングにかかる時間を Ray でも計測できます。メモリ使用量も確認できるため、より便利です。

{{ ray.measure() }}
{% set entryQuery = craft.entries.section('news').limit(10) %}
{{ ray.measure() }}
{% for entry in entryQuery.all() %}
  {{ ray('エントリのループ処理').orange() }}
{% endfor %}
{{ ray.measure() }}

実行時間と最大メモリ使用量

その他、公式リファレンスや Qiita 記事なども参考にしてください。

Reference | ray | Spatie
https://spatie.be/docs/ray/v1/usage/reference

Laravel Ray 進化したDumpデバッグデスクトップアプリ - Qiita
https://qiita.com/ucan-lab/items/a51393db3d421bf78a57

最後に

あらかじめ「導入方法」でご紹介した設定をしておけば、独自プラグインやモジュール開発時のデバッグにも Ray アプリを使えるのは便利ですね。