［PHP］set_include_path()完全解説｜インクルードパスの設定方法とオートローダーとの使い分け

PHP

はじめに

PHPで require や include を使ってファイルを読み込む際、ファイルパスを毎回フルパスで書くのは大変です。set_include_path() を使うと、PHPがファイルを検索するディレクトリのリスト（インクルードパス）を実行時に設定できます。

Composerが普及した現代では直接使う機会は減りましたが、レガシーコードのメンテナンス・Composer未使用環境・複数ライブラリのパス管理など、今でも重要な場面があります。また get_include_path() と合わせた安全なパス操作や、restore_include_path() による一時的な変更・復元パターンは実践的なスキルです。

関数の概要

項目内容
関数名set_include_path()
所属PHP オプション・情報関数
導入バージョンPHP 4.3.0以降
PHP 8.x対応済み

構文

set_include_path(string $include_path): string|false

パラメータ

パラメータ型説明
$include_pathstring設定するインクルードパス。複数ディレクトリは PATH_SEPARATOR で区切る

戻り値

  • 成功時：変更前のインクルードパス（文字列）を返します
  • 失敗時：false を返します

PATH_SEPARATOR 定数

OS値例
Linux / macOS:/app/lib:/app/vendor:/usr/share/php
Windows;C:\app\lib;C:\app\vendor

PATH_SEPARATOR を使うと OS を問わず安全に記述できます。

set_include_path('/app/lib' . PATH_SEPARATOR . '/app/vendor');

関連関数

関数役割
set_include_path()インクルードパスを設定する
get_include_path()現在のインクルードパスを取得する
restore_include_path()インクルードパスを php.ini のデフォルト値に戻す

基本的な使い方

<?php
// 現在のパスを確認
echo get_include_path() . "\n";
// 例: .:/usr/share/php

// インクルードパスを設定
$previous = set_include_path('/app/lib' . PATH_SEPARATOR . '/app/vendor');
echo "変更前: {$previous}\n";
echo "変更後: " . get_include_path() . "\n";

// パスを追加する（既存を保持しつつ追加）
set_include_path(get_include_path() . PATH_SEPARATOR . '/app/extra');

// php.ini のデフォルト値に戻す
restore_include_path();

実践的なクラスベースの使用例

例1：インクルードパス管理クラス

<?php
/**
 * インクルードパスを安全に追加・削除・復元するクラス
 * 既存のパスを壊さずにパスを追加・削除できる
 */
class IncludePathManager
{
    private string $originalPath;

    public function __construct()
    {
        $this->originalPath = get_include_path();
    }

    /**
     * パスを末尾に追加する（重複チェック付き）
     */
    public function append(string $path): void
    {
        if (!$this->has($path)) {
            set_include_path(get_include_path() . PATH_SEPARATOR . $path);
            echo "パス追加（末尾）: {$path}\n";
        } else {
            echo "スキップ（既存）: {$path}\n";
        }
    }

    /**
     * パスを先頭に追加する（優先度を高くする）
     */
    public function prepend(string $path): void
    {
        if (!$this->has($path)) {
            set_include_path($path . PATH_SEPARATOR . get_include_path());
            echo "パス追加（先頭）: {$path}\n";
        } else {
            echo "スキップ（既存）: {$path}\n";
        }
    }

    /**
     * 指定したパスを削除する
     */
    public function remove(string $path): void
    {
        $paths   = $this->toArray();
        $filtered = array_filter($paths, fn($p) => $p !== $path);

        if (count($filtered) < count($paths)) {
            set_include_path(implode(PATH_SEPARATOR, $filtered));
            echo "パス削除: {$path}\n";
        } else {
            echo "パスが見つかりません: {$path}\n";
        }
    }

    /**
     * 指定したパスが含まれているか確認する
     */
    public function has(string $path): bool
    {
        return in_array($path, $this->toArray(), true);
    }

    /**
     * 現在のインクルードパスを配列で返す
     */
    public function toArray(): array
    {
        return explode(PATH_SEPARATOR, get_include_path());
    }

    /**
     * インクルードパスをリセットしてコンストラクタ時の状態に戻す
     */
    public function reset(): void
    {
        set_include_path($this->originalPath);
        echo "インクルードパスをリセットしました\n";
    }

    /**
     * php.ini のデフォルト値に戻す
     */
    public function restoreDefault(): void
    {
        restore_include_path();
        echo "php.ini のデフォルトに戻しました\n";
    }

    public function print(): void
    {
        echo "=== 現在のインクルードパス ===\n";
        foreach ($this->toArray() as $i => $path) {
            printf("  %d: %s\n", $i + 1, $path);
        }
    }
}

$manager = new IncludePathManager();
$manager->append('/app/lib');
$manager->append('/app/vendor');
$manager->prepend('/app/override');  // 最高優先度
$manager->append('/app/lib');        // 重複はスキップ
$manager->print();
$manager->remove('/app/vendor');
$manager->print();
$manager->reset();

/*
出力例:
パス追加（末尾）: /app/lib
パス追加（末尾）: /app/vendor
パス追加（先頭）: /app/override
スキップ（既存）: /app/lib
=== 現在のインクルードパス ===
  1: /app/override
  2: .
  3: /usr/share/php
  4: /app/lib
  5: /app/vendor
パス削除: /app/vendor
=== 現在のインクルードパス ===
  1: /app/override
  2: .
  3: /usr/share/php
  4: /app/lib
インクルードパスをリセットしました
*/

例2：スコープ付きインクルードパス一時変更クラス

<?php
/**
 * 特定の処理ブロックだけインクルードパスを変更し、
 * 終了後に自動で元に戻すクラス
 * try-finally で例外時も確実に復元する
 */
class ScopedIncludePath
{
    private string $savedPath;

    /**
     * コンストラクタでパスを一時変更する
     */
    public function __construct(array $paths, bool $prepend = true)
    {
        $this->savedPath = get_include_path();
        $newPaths = implode(PATH_SEPARATOR, $paths);

        if ($prepend) {
            set_include_path($newPaths . PATH_SEPARATOR . $this->savedPath);
        } else {
            set_include_path($this->savedPath . PATH_SEPARATOR . $newPaths);
        }

        echo "一時パス設定: " . implode(', ', $paths) . "\n";
    }

    /**
     * 元のパスに戻す
     */
    public function restore(): void
    {
        set_include_path($this->savedPath);
        echo "パスを復元しました\n";
    }

    /**
     * スコープ付きでインクルードパスを変更して処理を実行する静的ファクトリ
     */
    public static function with(array $paths, callable $callback, bool $prepend = true): mixed
    {
        $scoped = new self($paths, $prepend);
        try {
            return $callback();
        } finally {
            $scoped->restore(); // 例外が発生しても必ず復元
        }
    }
}

// 使い方①：手動管理
$scoped = new ScopedIncludePath(['/app/legacy/lib', '/app/legacy/vendor']);
// ... ここで /app/legacy 配下のファイルを include できる ...
// require 'LegacyHelper.php'; // /app/legacy/lib/LegacyHelper.php を検索
$scoped->restore();

// 使い方②：クロージャで自動管理
$result = ScopedIncludePath::with(
    paths: ['/app/plugin/src'],
    callback: function (): string {
        echo "プラグイン処理中...\n";
        // require 'Plugin.php'; // /app/plugin/src/Plugin.php を検索
        return 'プラグイン処理完了';
    }
);
echo $result . "\n";

/*
出力例:
一時パス設定: /app/legacy/lib, /app/legacy/vendor
パスを復元しました
一時パス設定: /app/plugin/src
プラグイン処理中...
パスを復元しました
プラグイン処理完了
*/

例3：レガシーコードのオートローダークラス

<?php
/**
 * set_include_path() を活用したレガシーコード向けオートローダー
 * Composer が使えない環境やレガシープロジェクトの移行期に有効
 *
 * ディレクトリ構造例:
 * /app/src/
 *   Model/User.php       → クラス名 Model_User
 *   Service/Auth.php     → クラス名 Service_Auth
 *   Helper/Format.php    → クラス名 Helper_Format
 */
class LegacyAutoloader
{
    private array  $basePaths  = [];
    private array  $classMap   = [];
    private array  $loadedLog  = [];
    private string $separator;

    /**
     * @param string $separator クラス名のセパレータ（レガシーは '_'、PSR-0 は '\\'）
     */
    public function __construct(string $separator = '_')
    {
        $this->separator = $separator;
    }

    /**
     * 検索対象のベースパスを登録してインクルードパスに追加する
     */
    public function addBasePath(string $path): void
    {
        $realPath = realpath($path);
        if ($realPath === false) {
            echo "⚠️ パスが存在しません: {$path}\n";
            return;
        }

        $this->basePaths[] = $realPath;

        // インクルードパスにも追加する
        $current = get_include_path();
        if (!str_contains($current, $realPath)) {
            set_include_path($current . PATH_SEPARATOR . $realPath);
        }

        echo "ベースパス登録: {$realPath}\n";
    }

    /**
     * 個別クラスのファイルパスを明示的にマッピングする
     */
    public function addClassMap(array $map): void
    {
        $this->classMap = array_merge($this->classMap, $map);
    }

    /**
     * オートローダーを spl_autoload_register() に登録する
     */
    public function register(): void
    {
        spl_autoload_register([$this, 'load']);
        echo "オートローダー登録完了\n";
    }

    /**
     * クラスのロード処理
     */
    public function load(string $className): bool
    {
        // 明示マップを優先
        if (isset($this->classMap[$className])) {
            return $this->requireFile($this->classMap[$className], $className);
        }

        // セパレータをディレクトリ区切りに変換
        // 例: Model_User → Model/User.php
        $relativePath = str_replace($this->separator, DIRECTORY_SEPARATOR, $className) . '.php';

        // インクルードパスから検索
        foreach ($this->basePaths as $base) {
            $fullPath = $base . DIRECTORY_SEPARATOR . $relativePath;
            if (file_exists($fullPath)) {
                return $this->requireFile($fullPath, $className);
            }
        }

        echo "⚠️ クラスが見つかりません: {$className}\n";
        return false;
    }

    private function requireFile(string $path, string $className): bool
    {
        require_once $path;
        $this->loadedLog[] = ['class' => $className, 'path' => $path, 'time' => microtime(true)];
        echo "ロード: {$className} ← {$path}\n";
        return true;
    }

    public function printLoadedLog(): void
    {
        echo "=== ロード済みクラス ===\n";
        foreach ($this->loadedLog as $entry) {
            printf("  %s ← %s\n", $entry['class'], basename($entry['path']));
        }
    }
}

$loader = new LegacyAutoloader(separator: '_');
$loader->addBasePath('/app/src');
$loader->addClassMap([
    'SpecialHelper' => '/app/compat/special_helper.php',
]);
$loader->register();

// new Model_User() などで自動ロードが走る

例4：環境別インクルードパス設定クラス

<?php
/**
 * 環境（本番・ステージング・開発・テスト）に応じて
 * インクルードパスを自動的に切り替えるクラス
 */
class EnvironmentIncludePathConfigurator
{
    private array $envPaths;

    public function __construct(string $baseDir)
    {
        $base = rtrim($baseDir, '/');
        $this->envPaths = [
            'production' => [
                $base . '/src',
                $base . '/lib',
                $base . '/vendor',
            ],
            'staging' => [
                $base . '/src',
                $base . '/lib',
                $base . '/vendor',
                $base . '/staging-patches',
            ],
            'development' => [
                $base . '/src',
                $base . '/lib',
                $base . '/vendor',
                $base . '/dev-tools',
                $base . '/test-fixtures',
            ],
            'testing' => [
                $base . '/src',
                $base . '/lib',
                $base . '/tests/stubs',
                $base . '/tests/fixtures',
            ],
        ];
    }

    /**
     * 環境を指定してインクルードパスを設定する
     */
    public function configure(string $environment): string
    {
        if (!isset($this->envPaths[$environment])) {
            throw new \InvalidArgumentException("未定義の環境: {$environment}");
        }

        // 存在するディレクトリだけを有効なパスとして使用
        $validPaths = array_filter(
            $this->envPaths[$environment],
            fn($p) => is_dir($p)
        );

        if (empty($validPaths)) {
            echo "⚠️ 有効なパスがありません（環境: {$environment}）\n";
            return get_include_path();
        }

        $previous = set_include_path(
            implode(PATH_SEPARATOR, $validPaths)
        );

        echo "環境 [{$environment}] のインクルードパスを設定しました\n";
        echo "有効パス数: " . count($validPaths) . " / " . count($this->envPaths[$environment]) . "\n";

        return $previous;
    }

    /**
     * 環境に含まれるパス一覧を返す
     */
    public function getPathsFor(string $environment): array
    {
        return $this->envPaths[$environment] ?? [];
    }

    /**
     * 各環境のパス設定を比較表示する
     */
    public function printComparison(): void
    {
        echo "=== 環境別インクルードパス比較 ===\n";
        foreach ($this->envPaths as $env => $paths) {
            echo "\n[{$env}]\n";
            foreach ($paths as $path) {
                $exists = is_dir($path) ? '✅' : '❌';
                echo "  {$exists} {$path}\n";
            }
        }
    }
}

$configurator = new EnvironmentIncludePathConfigurator('/var/www/myapp');
$configurator->configure('development');
// $configurator->printComparison();

例5：インクルードパスを使ったプラグインシステムクラス

<?php
/**
 * プラグインディレクトリを動的にインクルードパスに追加することで
 * プラグインのクラスやファイルを透過的に読み込めるようにするクラス
 */
class PluginIncludePathRegistry
{
    private array  $plugins   = [];
    private string $pluginRoot;

    public function __construct(string $pluginRoot = '/app/plugins')
    {
        $this->pluginRoot = rtrim($pluginRoot, '/');
    }

    /**
     * プラグインを登録してそのソースディレクトリをインクルードパスに追加する
     */
    public function register(string $pluginName, array $subDirs = ['src', 'lib']): bool
    {
        $pluginDir = $this->pluginRoot . '/' . $pluginName;

        if (!is_dir($pluginDir)) {
            echo "⚠️ プラグインディレクトリが存在しません: {$pluginDir}\n";
            return false;
        }

        $addedPaths = [];
        foreach ($subDirs as $sub) {
            $path = $pluginDir . '/' . $sub;
            if (is_dir($path)) {
                $current = get_include_path();
                if (!str_contains($current, $path)) {
                    set_include_path($current . PATH_SEPARATOR . $path);
                    $addedPaths[] = $path;
                }
            }
        }

        $this->plugins[$pluginName] = [
            'dir'         => $pluginDir,
            'added_paths' => $addedPaths,
            'registered_at' => time(),
        ];

        echo "プラグイン登録: {$pluginName}\n";
        foreach ($addedPaths as $p) {
            echo "  → パス追加: {$p}\n";
        }

        return true;
    }

    /**
     * プラグインをアンロードしてインクルードパスから除去する
     */
    public function unregister(string $pluginName): bool
    {
        if (!isset($this->plugins[$pluginName])) {
            echo "未登録のプラグイン: {$pluginName}\n";
            return false;
        }

        $plugin  = $this->plugins[$pluginName];
        $current = explode(PATH_SEPARATOR, get_include_path());
        $cleaned = array_filter($current, fn($p) => !in_array($p, $plugin['added_paths'], true));

        set_include_path(implode(PATH_SEPARATOR, $cleaned));
        unset($this->plugins[$pluginName]);

        echo "プラグインアンロード: {$pluginName}\n";
        return true;
    }

    public function getRegistered(): array
    {
        return array_keys($this->plugins);
    }

    public function printStatus(): void
    {
        echo "=== プラグイン登録状況 ===\n";
        foreach ($this->plugins as $name => $info) {
            echo "  [{$name}]\n";
            foreach ($info['added_paths'] as $path) {
                echo "    → {$path}\n";
            }
        }
        echo "登録済み: " . count($this->plugins) . " プラグイン\n";
    }
}

$registry = new PluginIncludePathRegistry('/app/plugins');
// $registry->register('payment');
// $registry->register('analytics', ['src', 'helpers']);
// $registry->printStatus();

例6：インクルードパスの診断・検証クラス

<?php
/**
 * 現在のインクルードパスを診断して問題点を報告するクラス
 * デプロイ時のチェックや設定ミスの早期発見に使用する
 */
class IncludePathDiagnostics
{
    public function diagnose(): array
    {
        $raw     = get_include_path();
        $paths   = explode(PATH_SEPARATOR, $raw);
        $results = [];

        foreach ($paths as $path) {
            $result = [
                'path'       => $path,
                'exists'     => $path === '.' ? true : is_dir($path),
                'readable'   => $path === '.' ? true : is_readable($path),
                'is_dot'     => $path === '.',
                'is_absolute'=> str_starts_with($path, '/') || (strlen($path) > 1 && $path[1] === ':'),
            ];

            $result['status'] = match (true) {
                !$result['exists']   => '❌ 存在しない',
                !$result['readable'] => '⚠️ 読み取り不可',
                $result['is_dot']    => '✅ カレントディレクトリ',
                default              => '✅ 正常',
            };

            $results[] = $result;
        }

        return $results;
    }

    /**
     * 指定したファイル名がインクルードパスのどこで見つかるかを検索する
     */
    public function searchFile(string $filename): ?string
    {
        $paths = explode(PATH_SEPARATOR, get_include_path());
        foreach ($paths as $path) {
            $fullPath = ($path === '.' ? getcwd() : $path) . DIRECTORY_SEPARATOR . $filename;
            if (file_exists($fullPath)) {
                echo "発見: {$fullPath}\n";
                return $fullPath;
            }
        }
        echo "見つかりません: {$filename}\n";
        return null;
    }

    /**
     * 重複パスを検出して削除する
     */
    public function deduplicatePaths(): int
    {
        $paths   = explode(PATH_SEPARATOR, get_include_path());
        $unique  = array_unique($paths);
        $removed = count($paths) - count($unique);

        if ($removed > 0) {
            set_include_path(implode(PATH_SEPARATOR, $unique));
            echo "重複パスを {$removed}件 削除しました\n";
        } else {
            echo "重複パスはありません\n";
        }

        return $removed;
    }

    public function printReport(): void
    {
        $results = $this->diagnose();
        echo "=== インクルードパス診断レポート ===\n";
        printf("%-4s %-40s %s\n", 'No.', 'パス', 'ステータス');
        echo str_repeat('-', 65) . "\n";
        foreach ($results as $i => $r) {
            printf("%-4d %-40s %s\n", $i + 1, $r['path'], $r['status']);
        }
        echo str_repeat('-', 65) . "\n";

        $ok      = count(array_filter($results, fn($r) => str_starts_with($r['status'], '✅')));
        $ng      = count($results) - $ok;
        printf("合計: %d パス（正常: %d / 問題あり: %d）\n", count($results), $ok, $ng);
    }
}

$diag = new IncludePathDiagnostics();
$diag->deduplicatePaths();
$diag->printReport();
// $diag->searchFile('autoload.php');

/*
出力例:
重複パスはありません
=== インクルードパス診断レポート ===
No.  パス                                     ステータス
-----------------------------------------------------------------
1    .                                        ✅ カレントディレクトリ
2    /usr/share/php                           ✅ 正常
-----------------------------------------------------------------
合計: 2 パス（正常: 2 / 問題あり: 0）
*/

set_include_path() と Composer の使い分け

状況推奨アプローチ
新規プロジェクトComposer + PSR-4 オートローダー
レガシーコードの維持管理set_include_path() + spl_autoload_register()
Composer 未導入環境（共有ホスティングなど）set_include_path()
Composer 導入済みプロジェクトへのパス追加composer.json の autoload.psr-4 or classmap
一時的なパス変更（テスト・プラグインなど）ScopedIncludePath パターン（例2参照）

php.ini との関係

<?php
// php.ini の include_path に設定された値が初期値
// デフォルト例: ".:/usr/share/php"

// set_include_path() は実行時にのみ有効（php.ini は変更しない）
$prev = set_include_path('/app/lib' . PATH_SEPARATOR . get_include_path());

// restore_include_path() で php.ini の値に戻る
restore_include_path();

// ini_set() でも同様の操作が可能
ini_set('include_path', '/app/lib' . PATH_SEPARATOR . ini_get('include_path'));

よくある落とし穴

<?php
// ❌ NG：既存のパスを上書きしてしまう
set_include_path('/app/lib'); // 元のパスがすべて消える！

// ✅ OK：既存パスを保持しつつ追加する
set_include_path(get_include_path() . PATH_SEPARATOR . '/app/lib');

<?php
// ❌ NG：OS固有の区切り文字をハードコーディングする
set_include_path('/app/lib:/app/vendor'); // Linux のみ動作

// ✅ OK：PATH_SEPARATOR 定数を使う
set_include_path('/app/lib' . PATH_SEPARATOR . '/app/vendor'); // クロスプラットフォーム

<?php
// ❌ NG：存在しないディレクトリをパスに追加しても
//         エラーにならず、ファイルが見つからないだけで原因特定が難しい
set_include_path('/typo/path' . PATH_SEPARATOR . get_include_path());
// require 'MyClass.php'; → No such file or directory（原因が分かりにくい）

// ✅ パスを追加する前に存在確認する
$path = '/app/lib';
if (is_dir($path)) {
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
} else {
    throw new \RuntimeException("インクルードパスが存在しません: {$path}");
}

まとめ

項目内容
関数名set_include_path(string $include_path): string|false
主な用途require / include のファイル検索先ディレクトリを実行時に設定
戻り値変更前のインクルードパス
区切り文字PATH_SEPARATOR（Linux: : / Windows: ;）
既存パスの保持get_include_path() . PATH_SEPARATOR . $newPath で追加
デフォルトへの復元restore_include_path()
現代での位置づけComposer未使用環境・レガシーコード・一時的なパス変更で活用

set_include_path() は Composer が普及した現代でもレガシープロジェクトの維持・一時的なパス変更・プラグインシステムの動的パス追加など実践的な用途が残っています。get_include_path() で既存パスを保持しながら追加する習慣と、PATH_SEPARATOR によるクロスプラットフォーム対応を押さえておけば、安全に活用できます。

参考リンク

タイトルとURLをコピーしました