深入理解 WordPress `request_filesystem_credentials()` 函数的源码：当需要文件系统权限时，它是如何显示表单并获取凭据的。

各位，欢迎来到今天的“WordPress文件系统权限大冒险”讲座！我是你们的向导，今天咱们要深入挖掘一个神秘的函数：request_filesystem_credentials()。别被“文件系统”吓到，这玩意儿其实没那么可怕，咱们一步一步把它拆解清楚。

先来个“前情提要”：为啥需要文件系统权限？

想象一下，你的 WordPress 网站就像一座城堡，而你的主题、插件、上传的图片等等，都像是城堡里的各种房间和家具。要想安装一个新的主题（相当于装修），或者更新一个插件（相当于升级家具），你就需要拥有进入城堡并进行操作的权限。

在 WordPress 中，这些操作涉及到修改服务器上的文件和目录，所以就需要“文件系统权限”。request_filesystem_credentials() 就是用来请求这些权限的“敲门砖”。

request_filesystem_credentials()：初探庐山真面目

request_filesystem_credentials() 函数主要负责两件事：

检查是否已经拥有权限： 如果已经拥有了，那就万事大吉，直接跳过下一步。
如果没有权限，显示一个表单： 这个表单会要求用户输入 FTP、SSH 等连接信息，也就是“凭据”。

咱们先来看一段简化版的代码，帮助大家理解它的基本流程：

<?php
function my_plugin_update_files() {
  global $wp_filesystem;

  // 检查 WP_Filesystem 是否已初始化
  if ( empty( $wp_filesystem ) ) {
    require_once ABSPATH . 'wp-admin/includes/file.php';
    WP_Filesystem(); //尝试初始化
  }

  // 检查是否拥有文件系统权限
  if ( empty( $wp_filesystem ) || ! $wp_filesystem->wp_filesystem ) {
    $url = wp_nonce_url( 'update-plugin_my-plugin', 'update-plugin_my-plugin' ); //生成安全链接
    $method = ''; // 指定连接方式，留空让 WordPress 自动判断
    $context = WP_PLUGIN_DIR . '/my-plugin'; // 指定操作的目录

    // 请求文件系统权限
    $result = request_filesystem_credentials( $url, $method, false, $context );

    // 如果请求失败，停止执行
    if ( false === $result ) {
      return false; // 表单已经显示，等待用户输入
    }

    // 再次检查 WP_Filesystem 是否已初始化
    if ( empty( $wp_filesystem ) || ! $wp_filesystem->wp_filesystem ) {
      return false; // 用户可能取消了操作，或者输入了错误的凭据
    }
  }

  // 如果走到这里，说明已经获得了文件系统权限，可以进行文件操作了
  // ... 进行插件更新或其他文件操作 ...
  return true;
}

这段代码演示了一个插件更新文件的场景。如果 WP_Filesystem 对象不存在或未初始化，或者没有文件系统权限，就会调用 request_filesystem_credentials() 来显示表单。

深入 request_filesystem_credentials() 的源码：一场代码探险

现在，咱们要深入到 WordPress 的核心代码中，看看 request_filesystem_credentials() 到底是怎么工作的。这个函数定义在 wp-admin/includes/file.php 文件中。

第一步：参数解析

request_filesystem_credentials() 函数接受四个参数：

参数	类型	描述
`$url`	string	用于验证凭据的 URL，通常是一个包含 nonce 的 URL，确保安全性。
`$method`	string	指定连接方式，例如 ‘ftp’、’ssh’ 等。如果留空，WordPress 会尝试自动检测。
`$error`	boolean	是否显示错误信息。如果为 true，当用户输入错误的凭据时，会显示错误提示。
`$context`	string	操作的上下文，也就是要操作的目录。这有助于 WordPress 确定需要请求哪些权限。
`$override`	boolean	是否覆盖已保存的凭据，默认为false。如果为 true，即使已经保存了凭据，也会强制显示表单。

第二步：检查是否已经有凭据

函数首先会检查是否已经有有效的凭据保存在 $_COOKIE 中。如果找到了，它会尝试用这些凭据来初始化 WP_Filesystem 对象。

if ( ! empty( $_COOKIE[ 'wp-fs-'.$context ] ) ) {
  $saved_credentials = json_decode( stripslashes( $_COOKIE[ 'wp-fs-'.$context ] ), true );

  if ( is_array( $saved_credentials ) && ! empty( $saved_credentials['hostname'] ) && ! empty( $saved_credentials['username'] ) ) {
    $method = $saved_credentials['connection_type'];
    $hostname = $saved_credentials['hostname'];
    $username = $saved_credentials['username'];
    $password = $saved_credentials['password'];

    //尝试使用保存的凭据初始化 WP_Filesystem
    //...
  }
}

第三步：显示表单（如果需要）

如果找不到有效的凭据，或者 $override 参数为 true，函数就会显示一个表单，让用户输入连接信息。这个表单是用 get_filesystem_method_form() 函数生成的。

function get_filesystem_method_form( $args = array() ) {
  global $context, $url, $wp_filesystem;

  $defaults = array(
    'url' => '',
    'method' => '',
    'context' => false,
    'extra_fields' => array()
  );

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

  $url = esc_url( $args['url'] );
  $method = esc_attr( $args['method'] );
  $context = $args['context'];
  $extra_fields = $args['extra_fields'];

  $form = '<form method="post" action="' . esc_url( $url ) . '" style="margin-top: 1em;">';
  $form .= '<table class="form-table">';

  // 连接方式选择
  $form .= '<tr><th scope="row"><label for="connection_type">' . __( '连接类型' ) . '</label></th><td><select name="connection_type" id="connection_type">';
  $form .= '<option value="ftpext"' . selected( $method, 'ftpext', false ) . '>' . __( 'FTP' ) . ' (FTP扩展)' . '</option>';
  $form .= '<option value="ftpsockets"' . selected( $method, 'ftpsockets', false ) . '>' . __( 'FTP' ) . ' (FTP Sockets)' . '</option>';
  $form .= '<option value="ssh2"' . selected( $method, 'ssh2', false ) . '>' . __( 'SSH2' ) . '</option>';
  $form .= '</select></td></tr>';

  // 主机名
  $form .= '<tr><th scope="row"><label for="hostname">' . __( '主机名' ) . '</label></th><td><input type="text" name="hostname" id="hostname" value="' . esc_attr( defined('FTP_HOST') ? FTP_HOST : '' ) . '" /></td></tr>';

  // 用户名
  $form .= '<tr><th scope="row"><label for="username">' . __( '用户名' ) . '</label></th><td><input type="text" name="username" id="username" value="' . esc_attr( defined('FTP_USER') ? FTP_USER : '' ) . '" /></td></tr>';

  // 密码
  $form .= '<tr><th scope="row"><label for="password">' . __( '密码' ) . '</label></th><td><input type="password" name="password" id="password" value="' . esc_attr( defined('FTP_PASS') ? FTP_PASS : '' ) . '" /></td></tr>';

  // ... 其他字段 ...

  $form .= '</table>';
  $form .= '<input type="hidden" name="context" value="' . esc_attr( $context ) . '" />';
  $form .= '<input type="submit" class="button" value="' . esc_attr__( '继续' ) . '" />';
  $form .= '</form>';

  return $form;
}

这个函数会生成一个包含连接类型、主机名、用户名和密码等字段的 HTML 表单。用户填写完表单并提交后，WordPress 会尝试使用这些凭据来连接服务器。

第四步：处理表单提交

当用户提交表单后，WordPress 会接收到这些凭据，并尝试使用它们来初始化 WP_Filesystem 对象。如果初始化成功，说明获得了文件系统权限，就可以进行文件操作了。

if ( isset( $_POST['connection_type'] ) && isset( $_POST['hostname'] ) && isset( $_POST['username'] ) && isset( $_POST['password'] ) ) {
  $method = $_POST['connection_type'];
  $hostname = $_POST['hostname'];
  $username = $_POST['username'];
  $password = $_POST['password'];

  // 尝试使用提交的凭据初始化 WP_Filesystem
  // ...
}

第五步：保存凭据（如果需要）

如果用户勾选了“记住我的凭据”选项，WordPress 会将这些凭据保存到 $_COOKIE 中，以便下次使用。

关键代码片段解析

代码片段	作用
`require_once ABSPATH . 'wp-admin/includes/file.php';`	引入文件系统相关的函数和类。
`WP_Filesystem();`	尝试初始化 `WP_Filesystem` 对象。
`wp_nonce_url( 'update-plugin_my-plugin', 'update-plugin_my-plugin' );`	生成一个包含 nonce 的 URL，用于验证表单提交的安全性。
`get_filesystem_method_form( $args );`	生成包含连接类型、主机名、用户名和密码等字段的 HTML 表单。
`$_COOKIE[ 'wp-fs-'.$context ]`	用于存储已保存的凭据的 Cookie 键名。

一些需要注意的地方

安全性： request_filesystem_credentials() 函数使用 nonce 来保护表单的安全性，防止 CSRF 攻击。
错误处理： 如果用户输入了错误的凭据，或者连接服务器失败，WordPress 会显示错误提示。
用户体验： 尽量避免频繁地请求文件系统权限，这会影响用户体验。可以考虑使用其他方式，例如使用 WordPress API 来进行文件操作。
自动检测： 如果 $method 参数留空，WordPress 会尝试自动检测连接方式。但这种方式可能不总是有效，建议明确指定连接方式。
FTP 常量： WordPress 可以通过定义 FTP_HOST, FTP_USER, FTP_PASS 常量来预先设置 FTP 信息。如果定义了这些常量，在表单中会默认填充这些值。

实际应用场景

插件和主题安装/更新： 当安装或更新插件和主题时，WordPress 需要写入文件系统，这时就需要文件系统权限。
上传媒体文件： 上传媒体文件时，WordPress 需要将文件保存到 wp-content/uploads 目录，同样需要文件系统权限。
编辑主题文件： 如果用户直接在 WordPress 后台编辑主题文件，也需要文件系统权限。

总结：request_filesystem_credentials() 的“生存之道”

request_filesystem_credentials() 函数是 WordPress 中一个重要的安全机制，它确保只有拥有足够权限的用户才能修改文件系统。虽然它的工作原理稍微复杂，但理解了它的基本流程和关键代码，就能更好地理解 WordPress 的安全机制，并在开发插件和主题时更加得心应手。

它就像城堡的守卫，只有你提供了正确的“通行证”（凭据），才能进入城堡并进行操作。记住，永远不要轻易泄露你的“通行证”，确保你的网站安全！

希望今天的讲座能帮助大家更深入地理解 request_filesystem_credentials() 函数。谢谢大家！

发表回复 取消回复

发表回复取消回复