scandir() 返回空数组？__DIR__ 作用域陷阱解析

本文详解 PHP 中 scandir() 在跨文件调用时返回空数组的根本原因——__DIR__ 是编译时常量，始终指向定义它的文件所在目录，而非调用处；通过修正路径逻辑与提供健壮实践方案，确保目录扫描行为可预测、可移植。

本文详解 PHP 中 `scandir()` 在跨文件调用时返回空数组的根本原因——`__DIR__` 是编译时常量，始终指向**定义它的文件所在目录**，而非调用处；通过修正路径逻辑与提供健壮实践方案，确保目录扫描行为可预测、可移植。

在 PHP 开发中，scandir() 是常用的基础函数，用于读取指定路径下的所有文件和子目录。然而，当它被封装在类方法中（如 Core::availableControllers()），并从其他文件（如 Engine/ControllerLoader.php）调用时，开发者常遇到“返回空数组”或“仅列出 . 和 ..”的异常现象。这并非 scandir() 本身失效，而是对 __DIR__ 魔术常量作用域的误解所致。

根据 PHP 官方文档，__DIR__ 永远表示当前文件（即该常量所出现的 PHP 文件）所在的绝对目录路径，且该值在编译阶段即已确定，与运行时调用栈无关。因此，在 ./Core.php 中：

public function availableControllers()
{   
    $dir = scandir(__DIR__); // ✅ 始终扫描 Core.php 所在目录（例如 /var/www/project/Core/）
    // ...
}

无论 availableControllers() 是在 Core.php 内直接调用，还是被 ControllerLoader.php 实例化后调用，__DIR__ 永远指向 Core.php 的父目录，不会自动切换为 ControllerLoader.php 所在目录，更不会指向项目根目录或控制器目录。若你的控制器实际存放在 ./Controllers/ 下，而 Core.php 位于 ./Core/，那么 scandir(__DIR__) 就是在扫描 ./Core/ 目录——自然找不到控制器子目录，导致返回空数组。

✅ 正确解决方案：显式传入目标路径

应将“待扫描目录”作为参数注入方法，避免硬编码 __DIR__：

// ./Core.php —— 修改后的健壮实现
class Core
{
    /**
     * 扫描指定目录下所有子目录（排除 . 和 ..）
     * @param string $path 要扫描的绝对或相对路径
     * @return array 子目录名称列表
     */
    public function availableControllers($path)
    {
        if (!is_dir($path) || !is_readable($path)) {
            trigger_error("Directory not accessible: {$path}", E_USER_WARNING);
            return [];
        }

        $entries = scandir($path);
        $controllers = [];

        foreach ($entries as $entry) {
            if (is_dir($path . '/' . $entry) && $entry !== '.' && $entry !== '..') {
                $controllers[] = $entry;
            }
        }

        return $controllers;
    }
}

在 ControllerLoader.php 中，明确传入控制器目录路径（推荐使用 dirname(__DIR__) 向上定位）：

// ./Engine/ControllerLoader.php
include __DIR__ . "/../Core.php";

class ControllerLoader
{
    public function load()
    {
        $core = new Core();

        // ✅ 正确：假设控制器位于项目根目录下的 Controllers/ 子目录
        $controllersDir = dirname(__DIR__) . '/Controllers';
        // 或者更安全地使用 realpath() 确保路径有效：
        // $controllersDir = realpath(dirname(__DIR__) . '/Controllers');

        $available = $core->availableControllers($controllersDir);

        // 后续逻辑...
        var_dump($available); // 现在将正确输出 Controllers/ 下的子目录名
    }
}

⚠️ 关键注意事项

• 永远不要依赖 __DIR__ 自动适配调用上下文：它是静态的、文件级的，不是动态的、调用级的。
• 路径需绝对化或确保相对路径基准正确：推荐使用 realpath() 或 dirname(__DIR__) 构建稳定路径，避免因工作目录（getcwd()）变化引发问题。
• 添加基础校验：如 is_dir() 和 is_readable()，避免静默失败。
• 避免重复 include/require：示例中 include __DIR__ . "/../Core.php" 应替换为自动加载（PSR-4），提升可维护性。

✅ 总结

scandir() “不工作”的本质是路径语义错误，而非函数缺陷。核心原则只有一条：让路径意图显式化、可控化。将目录路径作为参数传递，不仅解决了当前问题，更提升了代码的可测试性、可配置性和跨环境兼容性。在现代 PHP 架构中，进一步结合依赖注入容器或配置中心管理路径，可彻底规避此类陷阱。