wp eval-file コマンド情報まとめ
ターミナルの wp eval-file コマンドについて、オプション情報、wp eval との違い、AIエージェントが実行した場合の危険性を紹介しています。
wp eval-file とは
wp eval-file（WP-CLI evaluate PHP file）は、指定した PHP ファイルを WordPress の実行環境をロードした状態で実行する WP-CLI コマンドです。
wp eval がコマンドライン引数にコードを直接記述するのに対し、wp eval-file はファイルのパスを渡す形式のため、複数行にわたる処理や繰り返し使うスクリプトを管理しやすくなっています。
WordPress のすべての関数・クラス・データベース接続を利用できるため、バッチ処理・データ移行・定期メンテナンス作業のスクリプトとして広く活用されています。
実行内容はファイルの内容に依存するため、ファイルの内容次第でデータベースの書き換えやファイルの削除も可能です。
主なオプション
| オプション | 意味 |
|---|---|
--path=<path> | WordPress のインストールパスを明示的に指定する。複数サイトを管理している環境で対象サイトを切り替えるときに使う |
--url=<url> | マルチサイト環境で操作対象のサイト URL を指定する |
-- <arg>... | -- 以降の値をスクリプト内で $args 配列として受け取れる。ファイルを汎用化して引数で挙動を切り替えたいときに使う |
| –skip-plugins | プラグインをロードせずに PHP ファイルを実行する。特定のプラグインの不具合で WordPress が正常に起動できない環境での調査や、プラグインに依存しない処理を高速に走らせたい場合に使用する。 |
基本構文は wp eval-file <ファイルパス> です。
-- を使った引数渡しの構文は wp eval-file script.php -- arg1 arg2 のように書き、スクリプト内では $args[0]・$args[1] で参照できます。
よく使う組み合わせ
投稿データを一括処理するスクリプトを実行する
// bulk-update-posts.php
// 下書き状態の投稿をすべて非公開（private）に変更する
$posts = get_posts([
'post_status' => 'draft',
'post_type' => 'post',
'numberposts' => -1,
]);
$count = 0;
foreach ( $posts as $post ) {
wp_update_post([
'ID' => $post->ID,
'post_status' => 'private',
]);
WP_CLI::log( "Updated: [{$post->ID}] {$post->post_title}" );
$count++;
}
WP_CLI::success( "{$count} 件の投稿を更新しました。" );# スクリプトを実行する
wp eval-file bulk-update-posts.php処理内容をファイルに書き出しておくことで、実行前に内容をレビューでき、Git で変更履歴も管理できます。
WP_CLI::log() で進捗を出力し、WP_CLI::success() で完了メッセージを表示するとスクリプトの動作が把握しやすくなります。
引数を受け取って汎用スクリプトとして使う
$post_type,
'post_status' => $from_status,
'numberposts' => -1,
]);
foreach ( $posts as $post ) {
wp_update_post(['ID' => $post->ID, 'post_status' => $to_status]);
WP_CLI::log( "Updated: [{$post->ID}] {$post->post_title}" );
}
WP_CLI::success( count($posts) . " 件を {$from_status} から {$to_status} に変更しました。" );
# 投稿タイプ・変更前・変更後ステータスを引数で渡す
wp eval-file change-post-status.php -- post draft private
# ページの下書きを公開に変更する場合
wp eval-file change-post-status.php -- page draft publish$args で引数を受け取ることでスクリプトを汎用化でき、投稿タイプやステータスの組み合わせを変えて繰り返し使えます。
引数付きで実行する際はスクリプト内のデフォルト値（?? 'post' など）を適切に設定しておくと、引数省略時の意図しない動作を防げます。
wp eval-file と wp eval の違い
どちらも WordPress 環境で PHP コードを実行しますが、コードの渡し方と管理のしやすさに明確な差があります。
| 項目 | wp eval-file | wp eval |
|---|---|---|
| コードの渡し方 | PHP ファイルのパスを指定 | コマンドライン引数に直接記述 |
| 向いている用途 | 複数行・複雑なロジック・繰り返し使うバッチ処理 | 1〜3行程度の簡単な確認・変更 |
| 実行前レビュー | しやすい（ファイルを事前に確認・共有できる） | しにくい（インライン記述のためレビューが難しい） |
| 再利用性 | 高い（ファイルとして保存・バージョン管理可） | 低い（コマンド履歴にのみ残る） |
| 引数の受け渡し | -- 以降の値を $args で受け取れる | シェル変数・ヒアドキュメントで対応 |
| 危険度 | ファイルの内容次第（事前レビューで制御しやすい） | インラインのため誤りが混入しやすい |
その場限りの即席確認には wp eval、定期バッチや複数環境で繰り返し使うスクリプトには wp eval-file が適しています。
本番環境での変更を伴う処理はファイルで管理してレビューできる wp eval-file を優先してください。
ユースケース
サイト移行後にカスタムフィールドの値を一括変換する
# 実行前にスクリプトの内容を確認する
cat migrate-meta.php
# 問題がなければ実行する
wp eval-file migrate-meta.phpデータ移行スクリプトは事前に cat や Git の差分確認でレビューしてから実行するのが安全です。
本番実行前にステージング環境で動作を確認する手順も徹底してください。
定期メンテナンスをcronと組み合わせて自動化する
# crontab に登録して毎週日曜深夜3時に自動実行する
# 0 3 * * 0 /usr/local/bin/wp eval-file /var/www/html/scripts/weekly-cleanup.php --path=/var/www/html定期メンテナンス処理をファイルとして管理しておくと、cron への登録や他サーバーへの展開が容易になります。
cron での自動実行時は --path で WordPress のインストールパスを明示的に指定してください。
AIエージェントが実行しようとした場合
AIエージェントの目的
AIエージェントは主に次のような目的で wp eval-file を実行しようとすることがあります。
- データ移行・バッチ処理・定期メンテナンスなど、複数行にわたる PHP スクリプトを WordPress 環境で実行するために使用することがあります。
- エージェント自身が生成した PHP スクリプトファイルを、そのまま WordPress 環境で実行するために使用することがあります。
- デプロイ自動化の一環として、環境ごとの設定変更・初期データ投入・クリーンアップ処理をスクリプトファイルとして実行するために使用することがあります。
危険性
wp eval-file コマンドは、指定したファイルの PHP コードを WordPress の管理者権限と同等以上の権限で即時実行する不可逆的な操作を伴います。
特に注意が必要なのは、AIエージェントが自動生成した PHP ファイルをそのまま wp eval-file で実行するパターンです。
ファイルの内容にバグや意図しない処理が含まれていた場合、データベースの全削除・ユーザーパスワードのリセット・悪意あるコードの挿入なども技術的には可能です。
AIエージェントが自動生成・自動実行することは推奨されません。スクリプトファイルの内容を人間が必ずレビューし、ステージング環境で動作を検証してから本番環境で実行するフローを徹底してください。
エージェント設定での wp eval-file のブロックリスト登録も強く推奨します。