WordPressテーマをComposerで管理する方法（オートロード・本番での扱い）

WordPress テーマに Composer を導入すると、外部ライブラリの管理と、自作クラスの自動読み込み（オートロード）をまとめて扱えるようになります。やることは、テーマフォルダに composer.json を置き、functions.php から vendor/autoload.php を読み込むだけです。この記事では、その手順に加えて、ファイルが無いときの対策、プラグインとのライブラリ衝突、vendor をコミットするかどうか、本番向けのインストール方法までを説明します。

テーマで Composer を使う利点

テーマが大きくなると、functions.php に require を何十行も並べたり、外部ライブラリのファイルを手作業でコピーしたりするようになります。Composer を使うと次のような点が楽になります。

• PSR-4 に沿ってクラスを置けば、require を書かなくても使った時点で読み込まれる
• 外部ライブラリのバージョンを composer.json と composer.lock で固定でき、ほかの環境でも同じ版を再現できる
• コード規約チェックやテスト用のツールを、本番には含めない開発用依存として分けられる

一方で、WordPress のテーマやプラグインは同じPHPプロセスの中で一緒に動くため、Composer で入れたライブラリがほかのプラグインと衝突することがあります。この点は後半で扱います。

composer.json を作る

Composer がインストールされていることを確認し、テーマフォルダで初期化します。

composer --version
cd wp-content/themes/my-theme
composer init

対話形式の質問に答えると composer.json ができます。手で書く場合の最小構成は次のとおりです。

{
    "name": "your-name/my-theme",
    "description": "My WordPress theme",
    "type": "wordpress-theme",
    "require": {
        "php": ">=7.4"
    },
    "autoload": {
        "psr-4": {
            "MyTheme\\": "inc/"
        }
    },
    "config": {
        "optimize-autoloader": true
    }
}

"MyTheme\\": "inc/" は「MyTheme 名前空間のクラスは inc/ フォルダから探す」という意味です。JSONの中ではバックスラッシュを2つ重ねて書きます。設定を書いたら、オートローダーを生成します。

composer dump-autoload

ライブラリを追加するときは composer require ベンダー名/パッケージ名、開発時だけ使うツールは composer require --dev squizlabs/php_codesniffer のように --dev を付けて追加します。

PSR-4 でクラスを置く

MyTheme\Setup というクラスなら、inc/Setup.php に置きます。名前空間の区切りがフォルダ、クラス名がファイル名に対応します。

<?php
// inc/Setup.php
namespace MyTheme;

class Setup {

    public static function init() {
        add_action( 'after_setup_theme', array( self::class, 'theme_supports' ) );
        add_action( 'wp_enqueue_scripts', array( self::class, 'enqueue_assets' ) );
    }

    public static function theme_supports() {
        add_theme_support( 'title-tag' );
        add_theme_support( 'post-thumbnails' );
    }

    public static function enqueue_assets() {
        wp_enqueue_style(
            'my-theme-style',
            get_stylesheet_uri(),
            array(),
            wp_get_theme()->get( 'Version' )
        );
    }
}

MyTheme\Admin\Settings のように階層を深くした場合は inc/Admin/Settings.php です。つまずきやすいのは大文字・小文字で、Windows や macOS の開発環境では inc/setup.php でも読み込めてしまうことがありますが、Linux の本番サーバーではクラスが見つからずエラーになります。ファイル名はクラス名と同じ表記にそろえてください。

functions.php から autoload.php を読み込む

functions.php の冒頭で vendor/autoload.php を読み込みます。vendor が無い状態でそのまま require すると致命的エラーでサイト全体が表示できなくなるため、ファイルの存在を確認してから読み込みます。

<?php
// functions.php
$my_theme_autoload = __DIR__ . '/vendor/autoload.php';

if ( ! file_exists( $my_theme_autoload ) ) {
    // 管理者にだけ原因を知らせ、サイトは止めない
    add_action( 'admin_notices', function () {
        if ( ! current_user_can( 'manage_options' ) ) {
            return;
        }
        echo '<div class="notice notice-error"><p>'
            . esc_html__( 'My Theme: vendor/autoload.php が見つかりません。テーマフォルダで composer install を実行してください。', 'my-theme' )
            . '</p></div>';
    } );
    return;
}

require_once $my_theme_autoload;

MyTheme\Setup::init();

__DIR__ は functions.php があるフォルダを指すので、子テーマでも親テーマでもそのテーマ自身の vendor を参照できます。get_template_directory() は子テーマを使っていると親テーマのフォルダを返すため、子テーマ側で Composer を使う場合は get_stylesheet_directory() か __DIR__ を使います。

読み込めているかは、テーマを有効化して管理画面に上の通知が出ないこと、wp eval 'var_dump( class_exists( "MyTheme\\Setup" ) );' で bool(true) が返ることで確認できます。

プラグインとのライブラリ衝突に注意する

WordPress では、テーマと複数のプラグインがそれぞれ自分の vendor を持ち、同じライブラリを別々のバージョンで同梱していることがあります。PHPは同じ名前のクラスを1回しか読み込めないため、先に読み込まれた側のバージョンが使われ、もう一方は想定と違うバージョンで動きます。その結果、メソッドが存在しないといったエラーが特定の組み合わせのときだけ起きる、という原因の分かりにくい不具合になります。

対策は次のとおりです。

• 自作クラスには、テーマ固有の名前空間（例：MyTheme）を付けてほかと重ならないようにする
• HTTPクライアントなど、多くのプラグインが同梱しがちなライブラリをテーマで使うときは、本当に必要かを検討する（WordPress コアの wp_remote_get() などで足りることも多い）
• 配布するテーマで外部ライブラリを同梱する場合は、PHP-Scoper や Strauss のような、ライブラリの名前空間に独自の接頭辞を付けるツールの利用を検討する

自社サイト専用のテーマで、入っているプラグインを把握できているなら、衝突が起きていないかをステージングで確認する運用でも対応できます。

vendor をコミットするか、同梱するか

vendor フォルダの扱いは、本番サーバーで Composer を実行できるかで決めます。

• 本番やCIで Composer を実行できる場合：vendor/ は .gitignore に入れ、composer.json と composer.lock をコミットします。デプロイ時にサーバーやCIで composer install を実行します。
• 共用サーバーなどで Composer を実行できない場合：手元やCIで本番用の vendor を作り、テーマと一緒にアップロードします。テーマをzipで配布する場合も、vendor を含めた状態で固めます。

どちらの場合も composer.lock はコミットします。ロックファイルが無いと、環境ごとに違うバージョンのライブラリが入る可能性があります。

本番向けのインストール

本番用には、開発用依存を除き、オートローダーを最適化してインストールします。

composer install --no-dev --optimize-autoloader

--no-dev は require-dev に書いたコード規約チェックやテストツールを入れないオプションです。これらが本番の公開フォルダに残ると、不要なファイルが外部から実行できる状態になるおそれがあります。--optimize-autoloader（短縮形は -o）はクラスとファイルの対応表を作り、読み込みを速くします。

開発環境と本番でPHPのバージョンが違う場合は、composer.json の config に "platform": { "php": "7.4" } のように本番のバージョンを書いておくと、本番で動かないバージョンのライブラリが選ばれるのを防げます。

作業の前にはテーマフォルダのバックアップを取り、インストール後はサイトの表示と管理画面にエラーが出ていないかを確認します。（2026年10月現在）Composer は 2 系が使われています。コマンドのオプションは composer help install で確認できます。

まとめ

• テーマフォルダに composer.json を置き、autoload の psr-4 で名前空間とフォルダを対応させる
• functions.php では vendor/autoload.php の存在を確認してから読み込み、無い場合もサイトを止めない
• クラスのファイル名は大文字・小文字までクラス名とそろえる
• 同じライブラリを同梱するプラグインとの衝突に注意し、配布テーマなら接頭辞付けツールを検討する
• composer.lock はコミットし、本番は composer install --no-dev --optimize-autoloader で入れる

• WordPressでPSR-4オートロードを使ってプラグイン構成を整理する方法
• composer.jsonとcomposer.lockの違いと使い方