2026年7月1日

WP-CLIのeval・eval-fileでPHPを実行する方法と安全な使い方

カスタマイズ

WP-CLI の wp eval を使うと、WordPress を読み込んだ状態で PHP コードを1行だけ実行できます。数行を超える処理は wp eval-file でスクリプトファイルとして実行するのが基本です。この記事では、2つのコマンドの使い分け、シェルごとのクォートの違い、引数の渡し方、本番環境で事故を起こさないための注意点までを順に説明します。

wp eval と wp eval-file の違い

どちらも「WordPress のコアとプラグイン・テーマを読み込んだ後に、任意の PHP を実行する」コマンドです。管理画面や functions.php を触らずに、get_option() や WP_Query などの関数をその場で呼び出せるため、調査や一回限りのデータ修正に向いています。

wp eval '<コード>' … コマンドラインに書いた PHP を実行します。値の確認や関数の戻り値を見るなど、1行で済む処理向けです。
wp eval-file <ファイル> [引数...] … PHP ファイルを読み込んで実行します。複数行の処理、繰り返し使う処理、レビューしてから実行したい処理向けです。

判断の目安は「コマンド履歴に残しても読み返せる長さかどうか」です。セミコロンが3つ以上並ぶようなら、ファイルに切り出したほうがクォートの問題も避けられ、内容を確認してから実行できます。

wp eval の基本

まずは動作確認として、サイト名とWordPressのバージョンを表示してみます。

wp eval 'echo get_option( "blogname" ) . PHP_EOL;'
wp eval 'echo get_bloginfo( "version" ) . PHP_EOL;'

書き方のポイントは3つあります。

コードの先頭に <?php は付けません。渡した文字列はそのまま PHP として評価されます。
文の終わりにはセミコロンが要ります。付け忘れると構文エラーになります。
結果を見るには echo や var_dump() で明示的に出力します。改行を付けないとプロンプトが同じ行に続いて読みにくくなるため、PHP_EOL を付けておくと便利です。

配列やオブジェクトを確認したいときは print_r() や var_export() が使えます。

wp eval 'print_r( wp_get_theme()->get( "Name" ) ); echo PHP_EOL;'
wp eval 'var_export( wp_count_posts( "post" ) );'

ログインユーザーとして実行する

WP-CLI は通常、ログインユーザーがいない状態で動きます。そのため current_user_can() は false を返し、権限チェックのある関数は期待どおりに動かないことがあります。特定のユーザーとして実行するには、グローバル引数の --user を付けます。

wp eval 'var_dump( current_user_can( "manage_options" ) );' --user=admin

マルチサイトでは、対象サイトを --url=https://example.com/sub/ のように指定しないとメインサイトで実行されます。

WordPress を読み込まずに実行する（--skip-wordpress）

--skip-wordpress を付けると、WordPress を読み込まずに素の PHP として実行します。WP-CLI が使っている PHP のバージョンや拡張モジュールを確かめたいときに役立ちます。

wp eval 'echo PHP_VERSION . PHP_EOL;' --skip-wordpress
wp eval 'var_dump( extension_loaded( "imagick" ) );' --skip-wordpress

このモードでは WordPress の関数は使えません。また、Web サーバー経由の PHP と CLI の PHP は別の設定（php.ini）で動いていることが多いため、ここで見えるバージョンがサイトの PHP と一致するとは限りません。サイト側は「サイトヘルス」の情報画面などで確認してください。

シェルごとのクォートの違い

wp eval でいちばんつまずくのがクォートです。PHP コードには $ や " が頻繁に出てくるため、シェルがそれを先に解釈してしまうと、PHP に届く前にコードが壊れます。

Linux・macOS（bash・zsh）

外側をシングルクォート、PHP の文字列をダブルクォートにするのが安全です。シングルクォートの中では $ が展開されないため、PHP の変数をそのまま書けます。

wp eval '$p = get_post( 1 ); echo $p->post_title . PHP_EOL;'

外側をダブルクォートにすると、bash が $p を空のシェル変数として展開し、PHP 側では構文エラーになります。

Windows（コマンドプロンプト・PowerShell）

コマンドプロンプト（cmd.exe）はシングルクォートを引用符として扱いません。外側をダブルクォート、PHP の文字列をシングルクォートにします。

wp eval "echo get_option('blogname') . PHP_EOL;"

PowerShell では、ダブルクォートの中の $ が PowerShell の変数として展開されるため、外側はシングルクォートにします。ただし、外部コマンドに渡す引数の中のダブルクォートが PowerShell のバージョンによって削られることがあり、挙動が環境で変わります。Windows で $ やクォートを含むコードを実行する場合は、後述の eval-file を使うほうが安定します。

wp eval-file でスクリプトを実行する

ファイルに書いた PHP を実行するのが wp eval-file です。こちらは通常の PHP ファイルと同じく <?php で始めて構いません。

例として、指定したカテゴリーの公開記事数を数えるスクリプトを用意します。

<?php
// count-posts.php
// 使い方: wp eval-file count-posts.php news

$slug = isset( $args[0] ) ? sanitize_title( $args[0] ) : '';
if ( '' === $slug ) {
	WP_CLI::error( 'カテゴリーのスラッグを指定してください。' );
}

$term = get_term_by( 'slug', $slug, 'category' );
if ( ! $term ) {
	WP_CLI::error( "カテゴリー {$slug} が見つかりません。" );
}

$query = new WP_Query(
	array(
		'post_type'      => 'post',
		'post_status'    => 'publish',
		'cat'            => $term->term_id,
		'fields'         => 'ids',
		'posts_per_page' => -1,
		'no_found_rows'  => true,
	)
);

WP_CLI::success( sprintf( '%s の公開記事は %d 件です。', $term->name, count( $query->posts ) ) );

wp eval-file count-posts.php news

引数は $args で受け取る

ファイル名の後ろに並べた値は、スクリプト内で配列 $args として参照できます。上の例では news が $args[0] に入ります。位置引数として渡されるだけなので、値の検証やサニタイズはスクリプト側で行います。

スクリプト内では WP_CLI::log()・WP_CLI::success()・WP_CLI::warning()・WP_CLI::error() が使えます。WP_CLI::error() はメッセージを出してその場で終了し、終了コードが 0 以外になるため、シェルスクリプトや CI から呼んだときに失敗を検知できます。

eval-file にも --skip-wordpress が使えます。また、ファイル名に - を指定すると標準入力からコードを読み込めますが、何が実行されたかが残りにくいため、普段はファイルに保存して実行するほうが後から追いかけやすくなります。

データを書き換える前の準備

eval や eval-file には確認画面もドライラン機能もありません。wp_update_post() や update_option()、$wpdb->query() を含むコードは、実行した瞬間に本番のデータベースが変わります。書き換えを伴う処理は、次の流れで進めてください。

実行前に wp db export でデータベースを書き出しておく
ステージング環境で同じスクリプトを実行し、結果を確かめる
スクリプトに「何件が対象か」だけを表示するモードを用意し、件数を見てから本番で実行する

wp db export before-fix.sql
wp eval-file fix-meta.php --user=admin

対象件数の確認は、処理の最初で WP_Query や get_posts() の結果を数えて表示し、引数に run が無ければそこで終わるように書いておくと手軽です。

セキュリティ上の注意

wp eval はサーバー上で任意の PHP を実行できる強力な機能です。次の点を守ってください。

出どころの分からないコードを貼り付けて実行しない。ブログやフォーラムで見かけたワンライナーも、内容を理解してから使います。
スクリプトファイルを公開ディレクトリ（WordPress のルートや wp-content 配下）に置かない。ブラウザから直接アクセスされると、WordPress を介さずに実行される恐れがあります。ホームディレクトリの専用フォルダーなど、Web から見えない場所に置きます。
パスワードや API キーをコマンドラインに直接書かない。シェルの履歴やプロセス一覧に残ります。必要な値は環境変数や権限を絞ったファイルから読み込みます。
作業が終わったら、使い捨てのスクリプトは削除するか、リポジトリで管理して残す場所を決めておきます。

よくあるエラーと対処

PHP Parse error が出る … セミコロンの付け忘れか、シェルがクォートや $ を解釈してしまったケースがほとんどです。同じコードをファイルに書いて eval-file で実行すると、どちらが原因か切り分けられます。
Call to undefined function が出る … --skip-wordpress を付けている、またはプラグインが無効で関数が定義されていない可能性があります。wp plugin list --status=active で状態を確認してください。
Allowed memory size が出る … 全件を一度に読み込んでいる可能性があります。'fields' => 'ids' で ID だけ取得する、ページ単位に分けて処理するなどで負荷を下げます。
権限関連の関数が false を返す … ログインユーザーがいない状態のためです。--user を付けて実行します。

WP-CLI のバージョンによってオプションが増えている場合があるため、手元の環境で wp help eval と wp help eval-file を確認する習慣を付けておくと安心です（2026年10月現在）。

まとめ

1行で済む確認は wp eval、複数行や書き換えを伴う処理は wp eval-file に分ける
bash・zsh では外側をシングルクォート、cmd.exe では外側をダブルクォート。迷ったらファイルに書く
eval-file の追加引数は $args 配列で受け取り、値の検証はスクリプト側で行う
--skip-wordpress は PHP 環境の確認用。WordPress の関数は使えない
書き換えの前は wp db export とステージングでの確認を行い、スクリプトは Web から見えない場所に置く