云策 WordPress 开发者社区

函数文档

WP_Filesystem()

查看官方原文 ↗
💡 云策文档标注

概述

WP_Filesystem() 函数用于初始化和连接 WordPress 文件系统抽象类，提供统一的文件操作接口。它根据环境自动选择传输方法（如 direct、FTP），并支持插件通过过滤器扩展。

关键要点

  • 函数初始化全局变量 $wp_filesystem，加载并实例化相应的 WP_Filesystem_* 类（如 WP_Filesystem_Direct）。
  • 参数包括 $args（连接参数）、$context（上下文路径）和 $allow_relaxed_file_ownership（放宽文件所有权），默认使用 "direct" 方法。
  • 返回值为 bool|null：成功返回 true，失败返回 false，若类文件不存在则返回 null。
  • 初始化时机受限：不能在任意位置调用，最早可在 admin_init 钩子后使用，因为 request_filesystem_credentials() 仅在管理区域可用。
  • 支持过滤器 filesystem_method_file 允许插件自定义传输方法类文件路径。
  • 自动定义文件系统超时常量（如 FS_CONNECT_TIMEOUT）和权限常量（如 FS_CHMOD_DIR）。

代码示例

global $wp_filesystem;
require_once( ABSPATH . '/wp-admin/includes/file.php' );
if ( WP_Filesystem() ) {
    // 使用 $wp_filesystem 进行文件操作，例如检查文件存在性
    if ( $wp_filesystem->exists( $file_path ) ) {
        $content = $wp_filesystem->get_contents( $file_path );
    }
} else {
    // 处理初始化失败情况
}

注意事项

  • 调用前需确保已包含 wp-admin/includes/file.php 文件。
  • 务必检查 WP_Filesystem() 的返回值，避免在未初始化时使用 $wp_filesystem 对象。
  • 在非管理区域使用时，需注意凭证请求限制，可能需要用户交互。
  • 参考官方 Filesystem API 文档以获取正确用法，避免示例中的错误（如未检查返回值）。
📄 原文内容

Initializes and connects the WordPress Filesystem Abstraction classes.

Description

This function will include the chosen transport and attempt connecting.

Plugins may add extra transports, And force WordPress to use them by returning the filename via the ‘filesystem_method_file’ filter.

Parameters

$argsarray|falseoptional
Connection args, These are passed directly to the WP_Filesystem_*() classes.

Default:false

$contextstring|falseoptional
Context for get_filesystem_method() .

More Arguments from get_filesystem_method( … $context )

Full path to the directory that is tested for being writable. Default empty.

Default:false

$allow_relaxed_file_ownershipbooloptional
Whether to allow Group/World writable.

Default:false

Return

bool|null True on success, false on failure, null if the filesystem method class file does not exist.

More Information

If no parameters are specified, the “direct” method is used. The method is determined using the get_filesystem_method() function.

One of the initial challenges for developers using the WP Filesystem API is you cannot initialize it just anywhere. The request_filesystem_credentials() function isn’t available until AFTER the wp_loaded action hook, and is only included in the admin area. One of the earliest hooks you can utilize is admin_init.

Filesystem API on Common APIs Handbook:
https://developer.wordpress.org/apis/handbook/filesystem/

Filesystem API Class Reference:
Class: WP_Filesystem_Base
Class: WP_Filesystem_Direct
Class: WP_Filesystem_FTPext
Class: WP_Filesystem_ftpsocket
Class: WP_Filesystem_SSH2

Source

function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
	global $wp_filesystem;

	require_once ABSPATH . 'wp-admin/includes/class-wp-filesystem-base.php';

	$method = get_filesystem_method( $args, $context, $allow_relaxed_file_ownership );

	if ( ! $method ) {
		return false;
	}

	if ( ! class_exists( "WP_Filesystem_$method" ) ) {

		/**
		 * Filters the path for a specific filesystem method class file.
		 *
		 * @since 2.6.0
		 *
		 * @see get_filesystem_method()
		 *
		 * @param string $path   Path to the specific filesystem method class file.
		 * @param string $method The filesystem method to use.
		 */
		$abstraction_file = apply_filters( 'filesystem_method_file', ABSPATH . 'wp-admin/includes/class-wp-filesystem-' . $method . '.php', $method );

		if ( ! file_exists( $abstraction_file ) ) {
			return;
		}

		require_once $abstraction_file;
	}
	$method = "WP_Filesystem_$method";

	$wp_filesystem = new $method( $args );

	/*
	 * Define the timeouts for the connections. Only available after the constructor is called
	 * to allow for per-transport overriding of the default.
	 */
	if ( ! defined( 'FS_CONNECT_TIMEOUT' ) ) {
		define( 'FS_CONNECT_TIMEOUT', 30 ); // 30 seconds.
	}
	if ( ! defined( 'FS_TIMEOUT' ) ) {
		define( 'FS_TIMEOUT', 30 ); // 30 seconds.
	}

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

	if ( ! $wp_filesystem->connect() ) {
		return false; // There was an error connecting to the server.
	}

	// Set the permission constants if not already set.
	if ( ! defined( 'FS_CHMOD_DIR' ) ) {
		define( 'FS_CHMOD_DIR', ( fileperms( ABSPATH ) & 0777 | 0755 ) );
	}
	if ( ! defined( 'FS_CHMOD_FILE' ) ) {
		define( 'FS_CHMOD_FILE', ( fileperms( ABSPATH . 'index.php' ) & 0777 | 0644 ) );
	}

	return true;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘filesystem_method_file’, string $path, string $method )

Filters the path for a specific filesystem method class file.

Uses Description
get_filesystem_method()wp-admin/includes/file.php

Determines which method to use for reading, writing, modifying, or deleting files on the filesystem.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

Show 1 moreShow less

Used by Description
_wp_delete_all_temp_backups()wp-includes/update.php

Deletes all contents in the temporary backup directory.
WP_Site_Health::get_test_update_temp_backup_writable()wp-admin/includes/class-wp-site-health.php

Tests if plugin and theme temporary backup directories are writable or can be created.
WP_Site_Health_Auto_Updates::test_all_files_writable()wp-admin/includes/class-wp-site-health-auto-updates.php

Checks if core files are writable by the web user/group.
wp_ajax_delete_plugin()wp-admin/includes/ajax-actions.php

Handles deleting a plugin via AJAX.
wp_ajax_delete_theme()wp-admin/includes/ajax-actions.php

Handles deleting a theme via AJAX.
WP_Upgrader::fs_connect()wp-admin/includes/class-wp-upgrader.php

Connects to the filesystem.
WP_Upgrader::maintenance_mode()wp-admin/includes/class-wp-upgrader.php

Toggles maintenance mode for the site.
delete_theme()wp-admin/includes/theme.php

Removes a theme.
delete_plugins()wp-admin/includes/plugin.php

Removes directory and files of a plugin for a list of plugins.
do_core_upgrade()wp-admin/update-core.php

Upgrades WordPress core display.

Show 5 moreShow less

Changelog

Version Description
2.5.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Mahdi Yazdani


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    /**
 * This method gets a list of the most popular Google web fonts. 
 * Initialize the WP filesystem and no more using file_put_contents function
 *
 * @see 	wp_filesystem()
 * @see 	get_parent_theme_file_path()
 * @return 	array 	A list of Google web fonts
 */
function prefix_get_google_fonts() {

	global $wp_filesystem;

	require_once ( ABSPATH . '/wp-admin/includes/file.php' );
	WP_Filesystem();
	
	$local_file = 	get_parent_theme_file_path( '/assets/json/google-web-fonts.json' );
	$content 	= 	'';

    if ( $wp_filesystem->exists( $local_file ) ) {
        $content = json_decode( $wp_filesystem->get_contents( $local_file ) );
    } // End If Statement

	return $content;

}