阐述 WordPress `wp_filesystem()` 函数的源码：WP-CLI 如何与文件系统交互。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位靓仔靓女，老少爷们，大家好！今天咱们来聊聊WordPress里一个挺重要，但又容易被忽略的家伙：wp_filesystem()。别看它名字有点生硬，其实它就像是WordPress的“文件总管”，负责跟服务器的文件系统打交道。咱们不仅要扒开它的源码看看，还要聊聊WP-CLI这个命令行神器是怎么利用它来耍的。准备好了吗？Let’s dive in!

第一部分：wp_filesystem() 概览： WordPress 的文件系统抽象层

首先，我们要明确一个概念：wp_filesystem()并不是一个函数，而是一个函数，它返回一个对象。这个对象属于WP_Filesystem 类（或者它的子类）。WP_Filesystem 类提供了一系列方法，用来操作文件系统，比如读取文件、写入文件、创建目录、删除文件等等。

为什么WordPress要搞这么一套东西呢？原因很简单：兼容性！不同的服务器环境，文件系统的访问方式可能不一样。有的用fopen，有的用SSH2，有的用FTP。如果WordPress直接用这些底层函数，那就要针对不同的环境写不同的代码，维护起来简直是噩梦。

WP_Filesystem 就像一个中间人，它把这些不同的文件系统访问方式抽象成统一的接口，WordPress只需要跟它打交道，不用关心底层细节。这样一来，无论服务器环境怎么变，WordPress的代码都不用改，是不是很方便？

第二部分：wp_filesystem() 的“前世今生”：源码剖析

好了，现在我们来扒开wp_filesystem()的源码，看看它到底是怎么工作的。这个函数定义在 wp-includes/functions.php 文件中。

function wp_filesystem( $args = '', $context = false ) {
    global $wp_filesystem;

    if ( isset( $wp_filesystem ) && ( is_object( $wp_filesystem ) ) ) {
        return $wp_filesystem;
    }

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

    $defaults = array(
        'context'         => ABSPATH,
        'extra_requires'  => false,
        'fs_chmod_file'   => ( defined( 'FS_CHMOD_FILE' ) ) ? FS_CHMOD_FILE : 0644,
        'fs_chmod_dir'    => ( defined( 'FS_CHMOD_DIR' ) ) ? FS_CHMOD_DIR : 0755,
        'fs_method'       => '', // Leave blank for auto.  'direct', 'ssh', 'ftpext', 'ftpsockets'
        'hostname'        => '',
        'username'        => '',
        'password'        => '',
        'public_key'      => '',
        'private_key'     => '',
        'connection_type' => '',
    );

    $args = wp_parse_args( $args, $defaults );

    // Sanitize the context.
    $args['context'] = validate_file( $args['context'] );
    if ( is_wp_error( $args['context'] ) ) {
        return $args['context'];
    }

    // Handle FTP/SSH constants.
    if ( defined( 'FTP_HOST' ) ) {
        $args['hostname'] = FTP_HOST;
    }
    if ( defined( 'FTP_USER' ) ) {
        $args['username'] = FTP_USER;
    }
    if ( defined( 'FTP_PASS' ) ) {
        $args['password'] = FTP_PASS;
    }
    if ( defined( 'FTP_PUBKEY' ) ) {
        $args['public_key'] = FTP_PUBKEY;
    }
    if ( defined( 'FTP_PRIKEY' ) ) {
        $args['private_key'] = FTP_PRIKEY;
    }
    if ( defined( 'FTP_SSL' ) && FTP_SSL ) {
        $args['connection_type'] = 'ftps';
    }

    // Determine the requested method.
    if ( ! empty( $args['fs_method'] ) ) {
        $method = $args['fs_method'];
    } elseif ( defined( 'FS_METHOD' ) ) {
        $method = FS_METHOD;
    } else {
        $method = false;
    }

    switch ( $method ) {
        case 'direct':
            require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-direct.php';
            $wp_filesystem = new WP_Filesystem_Direct( $args );
            break;
        case 'ssh':
            require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-ssh2.php';
            $wp_filesystem = new WP_Filesystem_SSH2( $args );
            break;
        case 'ftpext':
            require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-ftpext.php';
            $wp_filesystem = new WP_Filesystem_FTPext( $args );
            break;
        case 'ftpsockets':
            require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-ftpsockets.php';
            $wp_filesystem = new WP_Filesystem_FTPSockets( $args );
            break;
        default:
            // Determine the proper method.
            $skin = isset( $args['skin'] ) ? $args['skin'] : null;
            $method = get_filesystem_method( $skin, $args );

            if ( false === $method ) {
                return new WP_Error( 'fs_unavailable', __( 'Filesystem unavailable.' ) );
            }

            wp_filesystem( $args ); // Recursive call, now with a method to use.

            return $wp_filesystem;
    }

    if ( ! $wp_filesystem->ready() ) {
        return new WP_Error( 'fs_no_connection', __( 'Could not connect to the filesystem.' ), $wp_filesystem->errors->get_error_data() );
    }

    return $wp_filesystem;
}

这段代码有点长，我们来简化一下，提取出关键步骤：

检查全局变量： 首先，它会检查全局变量 $wp_filesystem 是否已经存在，如果存在且是一个对象，就直接返回这个对象。也就是说，wp_filesystem() 函数只会实例化一次 WP_Filesystem 对象，后续调用都会返回同一个实例，保证单例模式。
加载文件： 如果 $wp_filesystem 不存在，它会加载 wp-admin/includes/file.php 文件，这个文件定义了 WP_Filesystem 类以及它的子类。
处理参数： 它会用 wp_parse_args() 函数合并传入的参数和默认参数。默认参数包括文件和目录的权限（fs_chmod_file 和 fs_chmod_dir），文件系统访问方式（fs_method），以及 FTP/SSH 连接信息等等。
选择文件系统访问方式： 关键的一步来了！它会根据 fs_method 参数来选择使用哪种文件系统访问方式。fs_method 可以是 'direct'、'ssh'、'ftpext' 或 'ftpsockets'。
- 'direct': 直接访问文件系统，不需要任何认证。
- 'ssh': 使用 SSH2 扩展访问文件系统。
- 'ftpext': 使用 FTP 扩展访问文件系统。
- 'ftpsockets': 使用 FTP sockets 访问文件系统。
实例化 WP_Filesystem 子类： 根据选择的文件系统访问方式，实例化对应的 WP_Filesystem 子类。比如，如果 fs_method 是 'direct'，就实例化 WP_Filesystem_Direct 类。
检查连接： 调用 $wp_filesystem->ready() 方法检查是否成功连接到文件系统。
返回对象： 最后，返回 $wp_filesystem 对象。

fs_method的优先级：

优先级	来源	说明
1	`$args['fs_method']`	直接传递给 `wp_filesystem()` 函数的参数。
2	`FS_METHOD`	在 `wp-config.php` 文件中定义的常量。
3	自动检测	如果以上两者都没有设置，WordPress 会自动检测可用的文件系统访问方式。

第三部分：WP_Filesystem 的“十八般武艺”：常用方法

WP_Filesystem 类提供了一系列方法，用来操作文件系统。我们来看几个常用的：

init( $args ): 初始化文件系统连接。
connect(): 尝试连接到文件系统。
ready(): 检查文件系统是否准备好。
exists( $file ): 检查文件是否存在。
is_file( $file ): 检查是否是文件。
is_dir( $path ): 检查是否是目录。
is_writable( $path ): 检查是否可写。
atime( $file ): 获取上次访问时间。
mtime( $file ): 获取上次修改时间。
size( $file ): 获取文件大小。
mkdir( $path, $chmod = false, $chown = false, $chgrp = false ): 创建目录。
rmdir( $path, $recursive = false ): 删除目录。
dirlist( $path, $include_hidden = true, $recursive = false ): 获取目录列表。
get_contents( $file ): 获取文件内容。
get_contents_array( $file ): 获取文件内容，返回数组。
put_contents( $file, $contents, $mode = false ): 写入文件内容。
delete( $file, $recursive = false ): 删除文件。
move( $source, $destination, $overwrite = false ): 移动文件。
copy( $source, $destination, $overwrite = false ): 复制文件。
chmod( $file, $chmod = false, $recursive = false ): 修改文件权限。
owner( $file ): 获取文件所有者。
getchmod( $file ): 获取文件权限。

这些方法是不是很强大？它们几乎涵盖了所有常用的文件系统操作。

第四部分：WP-CLI 与 wp_filesystem() 的“爱恨情仇”：如何交互

WP-CLI 是 WordPress 的命令行工具，它可以让你在命令行界面管理 WordPress。很多 WP-CLI 命令都需要操作文件系统，比如安装插件、更新主题、备份数据库等等。

WP-CLI 是怎么利用 wp_filesystem() 来跟文件系统打交道的呢？

其实很简单，WP-CLI 内部也会调用 wp_filesystem() 函数，获取 WP_Filesystem 对象，然后利用这个对象的方法来操作文件系统。

我们来看一个例子： WP-CLI 的 wp plugin install 命令可以安装插件。这个命令的内部实现就用到了 wp_filesystem() 函数。

// 简化后的代码
WP_CLI::log( 'Downloading plugin...' );
$package = WP_CLI::get_url( $url ); // 下载插件压缩包

if ( is_wp_error( $package ) ) {
    WP_CLI::error( $package->get_error_message() );
}

$temp_file = download_url( $url ); // 下载文件到临时目录

if ( is_wp_error( $temp_file ) ) {
    WP_CLI::error( $temp_file->get_error_message() );
}

WP_CLI::log( 'Unpacking plugin...' );
$destination = WP_PLUGIN_DIR;

$result = unzip_file( $temp_file, $destination ); // 解压插件

if ( is_wp_error( $result ) ) {
    WP_CLI::error( $result->get_error_message() );
}

unlink( $temp_file ); // 删除临时文件

WP_CLI::success( 'Plugin installed successfully.' );

// 在 unzip_file 函数中会使用 wp_filesystem()

function unzip_file( $file, $destination ) {
    global $wp_filesystem;

    $result = WP_Filesystem( ); // 确保 wp_filesystem 已经初始化

    if ( ! $wp_filesystem ) {
        return new WP_Error( 'could_not_initiate_filesystem', __( 'Could not access filesystem.' ) );
    }

    $unzipfile = unzip_file_ziparchive( $file, $destination ); // 使用 ZipArchive 解压

    if ( ! $unzipfile ) {
        $unzipfile = unzip_file_pclzip( $file, $destination ); // 使用 PclZip 解压，作为备选方案
    }

    return $unzipfile;
}

function unzip_file_ziparchive( $file, $destination ) {
    global $wp_filesystem;

    if ( ! class_exists( 'ZipArchive', false ) ) {
        return false;
    }

    $zip = new ZipArchive();
    if ( true !== ( $open = $zip->open( $file, ZipArchive::CHECKCONS ) ) ) {
        return new WP_Error( 'incompatible_archive', sprintf( __( 'Incompatible archive (%s).' ), $open ) );
    }

    if ( ! $zip->extractTo( $destination ) ) {
        $zip->close();
        return new WP_Error( 'unzip_file_error', __( 'Unable to extract the archive.' ) );
    }

    $zip->close();

    return true;
}

function unzip_file_pclzip( $file, $destination ) {
    global $wp_filesystem;

    if ( ! class_exists( 'PclZip', false ) ) {
        require_once ABSPATH . 'wp-admin/includes/class-pclzip.php';
    }

    $archive = new PclZip( $file );

    if ( 0 == ( $archive_files = $archive->extract( PCLZIP_OPT_PATH, $destination ) ) ) {
        return new WP_Error( 'pclzip_extract_error', $archive->errorInfo( true ) );
    }

    return true;
}

在这个例子中，unzip_file 函数内部调用了 wp_filesystem() 函数，确保 $wp_filesystem 对象已经初始化。虽然这里没有直接使用 $wp_filesystem 对象的方法，但是它确保了后续的解压操作可以正常进行。

总结：

wp_filesystem() 是 WordPress 的文件系统抽象层，它提供了一系列方法，用来操作文件系统。 WP-CLI 内部也会调用 wp_filesystem() 函数，利用 WP_Filesystem 对象的方法来操作文件系统。了解 wp_filesystem() 的工作原理，可以帮助我们更好地理解 WordPress 和 WP-CLI 的运作机制。

第五部分：WP_Filesystem的“避坑指南”：使用注意事项

虽然 wp_filesystem() 很好用，但是使用的时候也要注意一些问题，避免踩坑。

权限问题： 文件系统操作涉及到权限问题。如果 WordPress 没有足够的权限，就可能无法读取、写入或删除文件。在使用 wp_filesystem() 的时候，要确保 WordPress 拥有足够的文件系统权限。
FTP/SSH 连接问题： 如果使用 FTP 或 SSH 访问文件系统，要确保 FTP/SSH 连接信息正确。如果连接信息错误，就可能无法连接到文件系统。
FS_METHOD 设置问题： FS_METHOD 参数决定了使用哪种文件系统访问方式。如果 FS_METHOD 设置不正确，就可能导致文件系统操作失败。建议将 FS_METHOD 设置为 'direct'，除非服务器环境不允许。
缓存问题： 有些文件系统操作可能会被缓存。如果文件系统发生变化，但是缓存没有更新，就可能导致 WordPress 显示错误的信息。在使用 wp_filesystem() 的时候，要注意清除缓存。
安全性问题： 文件系统操作涉及到安全性问题。如果不小心，可能会导致文件被篡改或删除。在使用 wp_filesystem() 的时候，要小心谨慎，避免出现安全漏洞。

第六部分：WP_Filesystem 的“进阶玩法”：自定义扩展

WP_Filesystem 类是一个抽象类，我们可以通过继承它来扩展 WordPress 的文件系统功能。比如，我们可以创建一个 WP_Filesystem_Dropbox 类，用来访问 Dropbox 文件系统。

class WP_Filesystem_Dropbox extends WP_Filesystem {
    public function __construct( $args ) {
        // 初始化 Dropbox 连接
    }

    public function connect() {
        // 连接到 Dropbox
    }

    public function ready() {
        // 检查是否连接成功
    }

    public function get_contents( $file ) {
        // 从 Dropbox 获取文件内容
    }

    public function put_contents( $file, $contents, $mode = false ) {
        // 将文件内容写入 Dropbox
    }

    // 实现其他文件系统操作方法
}

通过自定义 WP_Filesystem 子类，我们可以将 WordPress 的文件系统功能扩展到各种云存储服务，比如 Amazon S3、Google Cloud Storage 等等。

第七部分：WP_Filesystem 的“江湖地位”：总结

wp_filesystem() 是 WordPress 的一个核心函数，它提供了一个抽象的文件系统访问层，使得 WordPress 可以兼容各种服务器环境。了解 wp_filesystem() 的工作原理，可以帮助我们更好地理解 WordPress 和 WP-CLI 的运作机制，并且可以扩展 WordPress 的文件系统功能。

希望今天的讲座对大家有所帮助！谢谢大家！

发表回复 取消回复

发表回复取消回复