发布于 由admin

阐述 WordPress `wp_filesystem()` 函数的源码：如何根据配置初始化 `WP_Filesystem` 类。

各位观众，早上好！今天咱们来聊聊 WordPress 里的一个“幕后英雄”—— wp_filesystem() 函数。它在 WordPress 中扮演着文件系统操作的“总指挥”，负责根据你的配置来初始化 WP_Filesystem 类，让你可以安全、便捷地读写文件。

一、故事的开端：为什么我们需要 wp_filesystem()？

在 WordPress 的世界里，插件和主题经常需要操作文件，比如上传图片、创建缓存文件、修改配置文件等等。但是，直接使用 PHP 的 fopen()、fwrite() 等函数存在一些问题：

  1. 权限问题： Web 服务器运行的用户可能没有足够的权限去访问或修改某些文件。
  2. 安全问题： 直接暴露文件系统路径可能会导致安全漏洞。
  3. 兼容性问题： 不同的服务器环境对文件系统操作的支持程度可能不同。

为了解决这些问题，WordPress 引入了 WP_Filesystem 类，它提供了一个统一的接口来操作文件系统，并且可以根据不同的服务器环境选择合适的底层实现。而 wp_filesystem() 函数，就是负责初始化这个 WP_Filesystem 实例的关键。

二、wp_filesystem() 函数：初始化背后的秘密

让我们一起深入 wp_filesystem() 函数的源码，看看它是如何工作的。

/**
 * Sets up the WordPress Filesystem.
 *
 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass.
 *
 * @param mixed $args Optional. See WP_Filesystem().
 * @param bool  $allow_relaxed_file_ownership Optional. Whether to allow relaxed file ownership. Default false.
 * @return bool True on success, false on failure.
 */
function wp_filesystem( $args = '', $allow_relaxed_file_ownership = false ) {
    global $wp_filesystem;

    if ( isset( $wp_filesystem ) ) {
        return true;
    }

    require_once ABSPATH . 'wp-admin/includes/file.php';

    if ( ! defined( 'FS_METHOD' ) ) {
        define( 'FS_METHOD', 'direct' );
    }

    $method = defined( 'FS_METHOD' ) ? FS_METHOD : false;

    if ( 'direct' === $method ) {
        $wp_filesystem = new WP_Filesystem_Direct( $args );
        return true;
    }

    if ( ! class_exists( 'WP_Filesystem_Base' ) ) {
        return false;
    }

    if ( ! class_exists( 'SSH2' ) ) {
        require_once ABSPATH . 'wp-admin/includes/class-ssh2.php';
    }

    $skin = isset( $args['skin'] ) ? $args['skin'] : false;

    if ( ! $skin ) {
        $skin = new WP_Error();
    }

    if ( ! $skin instanceof WP_Error ) {
        $skin = new WP_Error();
    }

    $have_credentials = false;

    if ( 'ftpext' === $method || 'ftp' === $method ) {
        $have_credentials = request_filesystem_credentials( $skin, '', true, false, $args );

        if ( ! $have_credentials ) {
            return false;
        }
    } elseif ( 'ssh2' === $method ) {
        $have_credentials = request_filesystem_credentials( $skin, '', true, false, $args );

        if ( ! $have_credentials ) {
            return false;
        }
    }

    if ( 'ftpext' === $method ) {
        require_once ABSPATH . 'wp-admin/includes/class-ftp-ext.php';
        $wp_filesystem = new WP_Filesystem_FTPext( $args );
    } elseif ( 'ftp' === $method ) {
        require_once ABSPATH . 'wp-admin/includes/class-ftp.php';
        $wp_filesystem = new WP_Filesystem_FTP( $args );
    } elseif ( 'ssh2' === $method ) {
        require_once ABSPATH . 'wp-admin/includes/class-ssh2.php';
        $wp_filesystem = new WP_Filesystem_SSH2( $args );
    } else {
        return false;
    }

    if ( is_wp_error( $wp_filesystem->errors ) && $wp_filesystem->errors->get_error_code() ) {
        return false;
    }

    if ( $allow_relaxed_file_ownership ) {
        $wp_filesystem->options['allow_relaxed_file_ownership'] = true;
    }

    return true;
}

让我们逐行拆解这段代码：

  1. 检查全局变量：

    global $wp_filesystem;

if ( isset( $wp_filesystem ) ) {
    return true;
}

    首先，函数会检查全局变量 $wp_filesystem 是否已经存在。如果存在，说明 WP_Filesystem 实例已经初始化过了，直接返回 true。这避免了重复初始化。

  2. 引入文件：

    require_once ABSPATH . 'wp-admin/includes/file.php';

    引入 wp-admin/includes/file.php 文件，该文件包含了 WP_Filesystem_Base 抽象类和一些辅助函数。

  3. 定义 FS_METHOD：

    if ( ! defined( 'FS_METHOD' ) ) {
    define( 'FS_METHOD', 'direct' );
}

$method = defined( 'FS_METHOD' ) ? FS_METHOD : false;

    这一步至关重要。它检查是否定义了 FS_METHOD 常量。FS_METHOD 用于指定 WordPress 使用哪种文件系统操作方法。如果没有定义，默认设置为 'direct'。

    FS_METHOD 常量可以在 wp-config.php 文件中设置。常见的取值有：

    • 'direct'：直接使用 PHP 的文件系统函数。
    • 'ftpext'：使用 PHP 的 FTP 扩展。
    • 'ftp'：使用 PHP 的 FTP 函数（不依赖 FTP 扩展）。
    • 'ssh2'：使用 PHP 的 SSH2 扩展。

  4. direct 方法：

    if ( 'direct' === $method ) {
    $wp_filesystem = new WP_Filesystem_Direct( $args );
    return true;
}

    如果 FS_METHOD 设置为 'direct'，则直接实例化 WP_Filesystem_Direct 类。WP_Filesystem_Direct 类是 WP_Filesystem 的一个子类，它直接使用 PHP 的文件系统函数进行操作。

    direct 方法通常在服务器具有足够的权限时使用，是最简单、最快速的方法。

  5. 检查基础类：

    if ( ! class_exists( 'WP_Filesystem_Base' ) ) {
    return false;
}

if ( ! class_exists( 'SSH2' ) ) {
    require_once ABSPATH . 'wp-admin/includes/class-ssh2.php';
}

    检查 WP_Filesystem_Base 类是否存在。如果不存在，说明文件引入失败，返回 false。 同时检测 SSH2 类是否存在，不存在则引入。

  6. 处理 skin 参数：

    $skin = isset( $args['skin'] ) ? $args['skin'] : false;

if ( ! $skin ) {
    $skin = new WP_Error();
}

if ( ! $skin instanceof WP_Error ) {
    $skin = new WP_Error();
}

    $args 参数可以传递一些配置信息给 WP_Filesystem 类。其中，skin 参数用于在需要用户输入 FTP 或 SSH 凭据时，显示一个界面。

    如果 $args 中没有 skin 参数，或者 skin 参数不是 WP_Error 类的实例，则创建一个 WP_Error 实例作为默认的 skin。

  7. 获取凭据：

    $have_credentials = false;

if ( 'ftpext' === $method || 'ftp' === $method ) {
    $have_credentials = request_filesystem_credentials( $skin, '', true, false, $args );

    if ( ! $have_credentials ) {
        return false;
    }
} elseif ( 'ssh2' === $method ) {
    $have_credentials = request_filesystem_credentials( $skin, '', true, false, $args );

    if ( ! $have_credentials ) {
        return false;
    }
}

    如果 FS_METHOD 设置为 'ftpext'、'ftp' 或 'ssh2'，则需要获取 FTP 或 SSH 凭据。request_filesystem_credentials() 函数会尝试从已保存的凭据中获取，或者提示用户输入。

    如果无法获取到凭据，则返回 false。

  8. 实例化 WP_Filesystem 子类：

    if ( 'ftpext' === $method ) {
    require_once ABSPATH . 'wp-admin/includes/class-ftp-ext.php';
    $wp_filesystem = new WP_Filesystem_FTPext( $args );
} elseif ( 'ftp' === $method ) {
    require_once ABSPATH . 'wp-admin/includes/class-ftp.php';
    $wp_filesystem = new WP_Filesystem_FTP( $args );
} elseif ( 'ssh2' === $method ) {
    require_once ABSPATH . 'wp-admin/includes/class-ssh2.php';
    $wp_filesystem = new WP_Filesystem_SSH2( $args );
} else {
    return false;
}

    根据 FS_METHOD 的值，实例化相应的 WP_Filesystem 子类：

    • WP_Filesystem_FTPext：使用 PHP 的 FTP 扩展进行文件系统操作。
    • WP_Filesystem_FTP：使用 PHP 的 FTP 函数进行文件系统操作。
    • WP_Filesystem_SSH2：使用 PHP 的 SSH2 扩展进行文件系统操作。

    如果 FS_METHOD 的值不在上述列表中，则返回 false。

  9. 检查错误：

    if ( is_wp_error( $wp_filesystem->errors ) && $wp_filesystem->errors->get_error_code() ) {
    return false;
}

    检查 WP_Filesystem 实例是否出现错误。如果出现错误，则返回 false。

  10. 允许宽松的文件所有权：

    if ( $allow_relaxed_file_ownership ) {
    $wp_filesystem->options['allow_relaxed_file_ownership'] = true;
}

    如果 $allow_relaxed_file_ownership 参数为 true，则允许宽松的文件所有权检查。这在某些情况下可以解决权限问题。

  11. 返回 true：

    return true;

    如果一切顺利，则返回 true，表示 WP_Filesystem 实例初始化成功。

三、WP_Filesystem 类的家族成员

WP_Filesystem 类是一个抽象类，它定义了文件系统操作的通用接口。WordPress 提供了几个 WP_Filesystem 的子类，用于处理不同的文件系统操作方法：

类名 描述 依赖 适用场景
WP_Filesystem_Direct 直接使用 PHP 的文件系统函数进行操作。 无 服务器具有足够的权限，可以直接访问和修改文件。
WP_Filesystem_FTPext 使用 PHP 的 FTP 扩展进行文件系统操作。 PHP 的 FTP 扩展（php-ftp） 服务器没有足够的权限，需要通过 FTP 协议进行文件系统操作。FTP 扩展提供了更好的性能和安全性。
WP_Filesystem_FTP 使用 PHP 的 FTP 函数（不依赖 FTP 扩展）进行文件系统操作。 无 服务器没有足够的权限，需要通过 FTP 协议进行文件系统操作，但 FTP 扩展不可用。
WP_Filesystem_SSH2 使用 PHP 的 SSH2 扩展进行文件系统操作。 PHP 的 SSH2 扩展（php-ssh2） 服务器没有足够的权限，需要通过 SSH2 协议进行文件系统操作。SSH2 提供了更高的安全性，可以避免 FTP 协议的明文传输问题。

四、FS_METHOD：选择正确的姿势

FS_METHOD 常量的选择至关重要，它直接影响到 WordPress 的文件系统操作的效率和安全性。

  • direct： 如果服务器具有足够的权限，强烈建议使用 direct 方法。它是最简单、最快速的方法。

  • ftpext 或 ftp： 如果服务器没有足够的权限，需要通过 FTP 协议进行文件系统操作，可以选择 ftpext 或 ftp 方法。ftpext 方法依赖 PHP 的 FTP 扩展，提供了更好的性能和安全性。如果 FTP 扩展不可用，则只能选择 ftp 方法。

  • ssh2： 如果服务器没有足够的权限，需要通过 SSH2 协议进行文件系统操作，可以选择 ssh2 方法。SSH2 提供了更高的安全性，可以避免 FTP 协议的明文传输问题。

五、一些小技巧

  1. 检查权限： 在使用 direct 方法之前，务必确保 Web 服务器运行的用户具有足够的权限去访问和修改文件。

  2. 安全第一： 尽量避免使用 ftp 方法，因为它会以明文方式传输 FTP 凭据。如果必须使用 FTP 协议，建议使用 ftpext 方法，并开启 TLS/SSL 加密。

  3. SSH2 是个好选择： 如果服务器支持 SSH2 扩展，强烈建议使用 ssh2 方法。它提供了更高的安全性。

  4. 调试： 如果文件系统操作出现问题，可以尝试在 wp-config.php 文件中定义 WP_DEBUG 常量为 true，以便查看更详细的错误信息。

六、总结

wp_filesystem() 函数是 WordPress 文件系统操作的核心。它负责根据 FS_METHOD 常量的值，初始化 WP_Filesystem 类的实例，并提供统一的接口来读写文件。通过选择合适的文件系统操作方法，可以确保 WordPress 的文件系统操作的效率和安全性。

希望今天的讲座能帮助你更好地理解 wp_filesystem() 函数的工作原理。下次遇到文件系统操作的问题，不妨回头看看这篇文章，或许能找到答案。

感谢大家的观看！下课！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注