2026年8月27日

WordPressプラグインでComposerを使った依存関係管理とautoloadの設定方法

カスタマイズ

WordPressのプラグイン開発でComposerを使うと、外部ライブラリのバージョン管理と、クラスファイルの自動読み込み（autoload）をまとめて任せられます。基本は composer.json に依存関係とautoloadの設定を書き、プラグインの本体ファイルで vendor/autoload.php を読み込むだけです。この記事では、その設定手順に加えて、本番へ持っていくときのビルド方法、他のプラグインとのライブラリ衝突への対策、サイト全体をComposerで管理する場合の考え方までを説明します。

クラスの置き場所やnamespaceとディレクトリの対応づけ（PSR-4の設計）は別記事で詳しく扱っているため、ここでは依存関係の管理とautoloadの設定に重点を置きます。

Composerで何が楽になるのか

Composerを使わずに外部ライブラリを使う場合、ライブラリのファイルをダウンロードしてプラグインのフォルダに置き、require_once を並べることになります。バージョンを上げるたびに手作業で入れ替え、そのライブラリが依存する別のライブラリも自分で揃えなければなりません。

Composerでは、必要なパッケージとバージョンの範囲を composer.json に書けば、依存先も含めて vendor/ に取得し、どのバージョンを入れたかを composer.lock に記録します。チームの誰が実行しても同じ構成を再現でき、vendor/autoload.php を1行読み込むだけで、すべてのクラスが必要なときに自動で読み込まれます。

準備：Composerのインストール

Composerは公式サイトの手順に従ってインストールします。現在はComposer 2系が主流です（2026年10月現在）。

composer --version

で導入を確認します。Composerの実行は開発環境とビルド環境で行い、本番サーバーにComposerを入れる必要はありません（理由は後述します）。

ステップ1：composer.jsonを作る

プラグインのフォルダで composer init を実行すると対話形式で作れますが、手で書いても構いません。最小構成は次のとおりです。

{
    "name": "acme/book-shelf",
    "description": "Book Shelf plugin for WordPress",
    "type": "wordpress-plugin",
    "license": "GPL-2.0-or-later",
    "require": {
        "php": ">=7.4"
    },
    "require-dev": {
        "phpunit/phpunit": "^9.6"
    },
    "autoload": {
        "psr-4": {
            "Acme\\BookShelf\\": "src/"
        }
    },
    "config": {
        "platform": {
            "php": "7.4"
        },
        "optimize-autoloader": true
    }
}

各項目の役割は次のとおりです。

require: プラグインの動作に必要なパッケージ。本番にも含めます
require-dev: テストツールやコード規約チェックなど、開発時だけ使うもの
autoload: 自分のクラスをどこから読み込むかの指定
config.platform.php: 本番サーバーのPHPバージョンを指定します。開発機のPHPが新しくても、本番で動かないバージョンのパッケージが選ばれるのを防げます

ライセンスはWordPressとの互換性から、GPLv2以降にするのが一般的です。

ステップ2：パッケージを追加する

ライブラリの追加は composer.json を直接編集するより、コマンドで行うほうが安全です。バージョン範囲を自動で決め、composer.lock も更新されます。

# 本番でも使うライブラリ
composer require vendor/package-name

# 開発時だけ使うツール
composer require --dev squizlabs/php_codesniffer

# 登録内容に問題がないかを確認
composer validate

^2.1 のような指定は「2.1以上、3.0未満」を意味し、互換性を壊さない範囲の更新だけを受け入れます。更新は composer update vendor/package-name のように対象を絞り、変更内容を確認しながら進めるとトラブルを追いやすくなります。

composer audit を使うと、インストール済みのパッケージに既知の脆弱性が報告されていないかを確認できます。定期的に実行しておくと安心です。

ステップ3：autoloadの種類を選ぶ

autoload には主に3つの方式があります。

psr-4: namespaceとディレクトリを対応させる方式。新しく書くクラスはこれが基本です
classmap: 指定したフォルダを走査してクラスの一覧を作る方式。class-acme-foo.php のような、WordPress流のファイル名で書かれた既存コードに向いています
files: クラスではない関数の定義ファイルを、毎回読み込む方式。ヘルパー関数をまとめたファイルなどに使います

"autoload": {
    "psr-4": { "Acme\\BookShelf\\": "src/" },
    "classmap": [ "includes/" ],
    "files": [ "src/functions.php" ]
}

autoload の設定を変えたら、composer dump-autoload を実行して vendor/ 内の読み込み設定を作り直します。

ステップ4：プラグインでautoload.phpを読み込む

プラグインの本体ファイルで、vendor/autoload.php を読み込みます。ファイルが無い状態（ビルドし忘れなど）で致命的エラーにならないよう、存在を確認してから読み込み、無ければ管理画面に通知を出すようにしておきます。

<?php
/**
 * Plugin Name: Book Shelf
 * Requires PHP: 7.4
 */

defined( 'ABSPATH' ) || exit;

$acme_bookshelf_autoload = __DIR__ . '/vendor/autoload.php';

if ( ! is_readable( $acme_bookshelf_autoload ) ) {
    add_action( 'admin_notices', function () {
        if ( ! current_user_can( 'activate_plugins' ) ) {
            return;
        }
        echo '<div class="notice notice-error"><p>'
            . esc_html__( 'Book Shelf: 依存ファイルが見つかりません。composer install を実行してください。', 'book-shelf' )
            . '</p></div>';
    } );
    return;
}

require_once $acme_bookshelf_autoload;

add_action( 'plugins_loaded', array( new \Acme\BookShelf\Plugin(), 'register' ) );

本番へ持っていくときのビルド

開発中の vendor/ には、テストツールなど本番で不要なものが含まれています。本番用には、開発用パッケージを除き、読み込みを最適化した状態で vendor/ を作り直します。

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

--optimize-autoloader（-o）はクラスの一覧表を事前に作り、ファイルを探す処理を減らします。さらに一覧表にないクラスを探さないようにする --classmap-authoritative もありますが、この場合は後から追加したクラスが読み込まれなくなるため、ビルドのたびに作り直す運用が前提です。

Gitでの管理は、composer.json と composer.lock をコミットし、vendor/ はコミットしない形が一般的です。ただし、WordPress.orgで配布するプラグインや、管理画面からアップロードするzipには vendor/ を含める必要があります。利用者の環境でComposerが実行される保証がないためです。ビルドしたzipを作る手順を、スクリプトやCIにまとめておくと漏れを防げます。

本番サーバーでComposerを実行しない理由は、ネットワーク越しにパッケージを取得する処理を本番に持ち込まず、開発で確認した vendor/ と同じものをそのまま置くためです。

他のプラグインとのライブラリ衝突

WordPressでは、複数のプラグインがそれぞれ自分の vendor/ を持ち込みます。2つのプラグインが同じライブラリの別バージョンを同梱していると、先に読み込まれた側のクラスが使われ、もう一方は想定と違うバージョンで動きます。エラーの原因が自分のコードに見えないため、気づきにくい問題です。

配布するプラグインでは、同梱するライブラリのnamespaceに自分専用の接頭辞を付け直すツール（Strauss や PHP-Scoper など）を使う方法がよく取られます。設定方法はツールごとに異なり、更新もあるため、各ツールのドキュメントに従ってください。自社サイト専用のプラグインで、読み込むライブラリを把握できているなら、まずは依存を少なく保つことが一番の対策です。

サイト全体をComposerで管理する場合

プラグイン単体ではなく、WordPress本体・テーマ・プラグインをまとめてComposerで管理する方法もあります。WordPress.orgのプラグインやテーマをComposerのパッケージとして扱えるWPackagistや、その構成をまとめたBedrock（Roots）が知られています。導入すると、ディレクトリ構成や更新の手順が通常のWordPressと変わるため、既存サイトに途中から入れる場合はステージングで十分に試し、バックアップを取ってから移行してください。

つまずきやすい点

Class not found が出る: namespaceと autoload の指定が一致しているか、composer dump-autoload を実行したかを確認する
本番でだけ動かない: 開発機と本番のPHPバージョン差。config.platform.php を本番に合わせる
vendorがWebから見える: vendor/ 内のファイルに直接アクセスされても困らないよう、不要な開発用パッケージを本番に置かない

まとめ

composer.json に require・require-dev・autoload を書き、composer.lock と一緒にGitで管理する
autoloadは新しいコードならpsr-4、既存コードはclassmap、関数ファイルはfiles
プラグイン本体では vendor/autoload.php の存在を確認してから読み込む
本番用は composer install --no-dev --optimize-autoloader でビルドし、配布zipには vendor/ を含める
同梱ライブラリの衝突には、namespaceの付け直しツールを検討する