2026年7月10日

WP-CLI scaffoldでプラグイン・子テーマ・カスタム投稿タイプの雛形を作る方法

カスタマイズ

wp scaffold は、プラグインや子テーマ、カスタム投稿タイプ、タクソノミー、ユニットテスト環境の「雛形（ボイラープレート）」を生成する WP-CLI のコマンドです。毎回手で書いていたヘッダーコメントや register_post_type() の長い引数を数秒で用意でき、書き間違いも減らせます。この記事では主要なサブコマンドの使い方と、生成後に手を入れるべき箇所、ブロック開発で使うべきツールの選び方を説明します。

scaffold で生成できるもの

手元の WP-CLI で使えるサブコマンドは wp help scaffold で一覧できます。よく使うのは次のものです。

wp scaffold plugin … プラグインの雛形一式
wp scaffold child-theme … 子テーマの雛形
wp scaffold post-type … カスタム投稿タイプの登録コード
wp scaffold taxonomy … カスタムタクソノミーの登録コード
wp scaffold plugin-tests / wp scaffold theme-tests … PHPUnit で動かすテスト環境のファイル

scaffold が作るのはあくまで出発点です。生成されたコードは読んで理解し、プロジェクトの命名規則やテキストドメインに合わせて直してから使います。作業はローカル環境かステージング環境で行い、本番サーバー上で直接生成するのは避けてください。

プラグインの雛形を作る（wp scaffold plugin）

wp scaffold plugin my-tools \
  --plugin_name="My Tools" \
  --plugin_description="サイト固有の機能をまとめたプラグイン" \
  --plugin_author="Your Name"

wp-content/plugins/my-tools/ に、プラグイン本体の my-tools.php、readme.txt、.gitignore や .distignore、コーディング規約チェック用の設定、テスト関連のファイルなどが作られます。生成されるファイルの構成は WP-CLI のバージョンで変わることがあるため、作成後にディレクトリの中身を確認してください。

主なオプションは次のとおりです。

--skip-tests … テスト関連のファイルを作らない。テストを書く予定がない小さなプラグインならこちらで十分です。
--activate … 生成後にそのまま有効化する
--dir=<パス> … plugins ディレクトリ以外に出力する
--force … 同名のファイルがあっても上書きする

--force は既存ファイルを置き換えるため、既に書き進めたプラグインに対して実行すると変更が失われます。Git などで管理していない場合は使わないでください。

生成された本体ファイルの先頭にはプラグインヘッダーが入っています。Version や Text Domain、Requires at least などの値を実態に合わせて書き換えたうえで、機能を追加していきます。

子テーマの雛形を作る（wp scaffold child-theme）

親テーマを直接編集すると、テーマの更新で変更が消えます。子テーマを使えば、親テーマの更新を受けながらカスタマイズを分けて管理できます。

wp scaffold child-theme my-child --parent_theme=twentytwentyfive --theme_name="My Child"

--parent_theme には親テーマのディレクトリ名（スラッグ）を指定します。表示名ではないため、wp theme list の name 列で確認してください。間違ったスラッグを指定しても子テーマ自体は作られますが、有効化すると親テーマが見つからずエラーになります。

生成されるのは style.css と functions.php などの最小限のファイルです。functions.php には親テーマのスタイルを読み込む処理が入ります。ただし、ブロックテーマ（theme.json を使うテーマ）では、子テーマ側に theme.json やテンプレートを追加してカスタマイズするのが一般的です。有効化は生成時に --activate を付けるか、後から wp theme activate my-child で行えます。本番サイトでは、ステージングで表示崩れが無いことを確かめてから切り替えてください。

カスタム投稿タイプを生成する（wp scaffold post-type）

wp scaffold post-type event --label=イベント --textdomain=my-tools --plugin=my-tools

出力先によって挙動が変わる点に注意が必要です。

--plugin も --theme も付けない … 登録コードが画面（標準出力）に表示されるだけで、ファイルは作られません。コピーして自分のファイルに貼り付ける使い方です。
--plugin=<スラッグ> … 指定したプラグインの post-types/ ディレクトリにファイルが作られます。
--theme … 有効なテーマの post-types/ ディレクトリにファイルが作られます。

ファイルが作られても、それだけでは読み込まれません。プラグイン本体から require_once で読み込む必要があります。

// my-tools.php に追記
require_once plugin_dir_path( __FILE__ ) . 'post-types/event.php';

カスタム投稿タイプはテーマではなくプラグインに置くことをおすすめします。テーマに置くと、テーマを切り替えた時点で投稿タイプが登録されなくなり、記事が管理画面から見えなくなるためです。

生成されたコードには labels の配列や show_in_rest などの設定が並んでいます。ブロックエディターで編集したい場合は show_in_rest が true になっているか、アーカイブページが必要なら has_archive の値を確認してください。--raw を付けると、フックで包まない register_post_type() の呼び出し部分だけを出力します。

新しい投稿タイプのページが 404 になる場合

投稿タイプを追加した直後は、パーマリンクのルールが更新されていないため、記事ページやアーカイブが 404 になることがあります。wp rewrite flush を一度実行するか、管理画面の「設定」→「パーマリンク」で保存し直すと解消します。

タクソノミーを生成する（wp scaffold taxonomy）

wp scaffold taxonomy venue --post_types=event --label=会場 --textdomain=my-tools --plugin=my-tools

--post_types で紐付ける投稿タイプを指定します。複数ある場合はカンマ区切りです。出力先の考え方と require_once が要る点は post-type と同じです。階層を持たせたい（カテゴリーのように親子にしたい）場合は、生成後に hierarchical の値を見直します。

テスト環境を用意する（wp scaffold plugin-tests）

既存のプラグインに PHPUnit のテスト環境を追加するコマンドです。

wp scaffold plugin-tests my-tools

tests/ ディレクトリ、phpunit.xml.dist、テスト用の WordPress とデータベースを準備するシェルスクリプト bin/install-wp-tests.sh などが作られます。スクリプトの引数にはテスト専用のデータベース名を指定してください。

bash bin/install-wp-tests.sh wordpress_test db_user 'db_password' localhost latest

テストのたびにこのデータベースの中身は作り直される前提なので、サイトで使っているデータベース名を指定してはいけません。必要な PHPUnit のバージョンや追加ライブラリは WordPress のテストスイート側の要件によって変わるため、エラーが出たら WordPress の開発者向けドキュメントで対応表を確認してください。--ci オプションで CI サービス用の設定ファイルも生成できますが、指定できる値は wp help scaffold plugin-tests で確認します。

ブロックの雛形は create-block を使う

古い記事では wp scaffold block でブロックの雛形を作る方法が紹介されていることがあります。しかしこのサブコマンドは、ビルド工程を前提とする現在のブロック開発の流れに合っておらず、WP-CLI 側でも非推奨の扱いになっています。お使いの WP-CLI で表示されるかどうかは wp help scaffold で確認できますが、新しく作るなら WordPress 公式の @wordpress/create-block を使うのが現在の標準です（2026年10月現在）。

cd wp-content/plugins
npx @wordpress/create-block@latest my-block
cd my-block
npm start

Node.js と npm が必要です。block.json を中心とした構成、ビルド設定、PHP の登録コードまでがまとめて作られ、npm start で開発用のビルドが、npm run build で本番用のビルドが動きます。

まとめ

wp scaffold はプラグイン・子テーマ・投稿タイプ・タクソノミー・テスト環境の雛形を作るコマンド
post-type と taxonomy は、出力先を指定しないと画面に表示されるだけ。ファイルに出したら require_once で読み込む
投稿タイプはテーマではなくプラグインに置く。追加後に 404 なら wp rewrite flush
--force は既存ファイルを上書きするため、バージョン管理していない場所では使わない
テスト用スクリプトにはサイトとは別のデータベースを指定する
ブロックの雛形は npx @wordpress/create-block で作る