WP_Filesystem() │ WP 2.5.0

Creates an object for working with files in WordPress. The created object is saved in the variable global $wp_filesystem.

What the function does:

The function finds the appropriate method for interacting with files using get_filesystem_method().
It includes all necessary PHP files from WordPress that are needed for the found method to work.
Based on the found interaction method, it creates an object for working with files and writes it to the variable global $wp_filesystem. We will use it later.
It sets the constants FS_CHMOD_DIR and FS_CHMOD_FILE, if they have not been previously set in wp-config.php.

If a connection-requiring interaction method has been defined, such as ssh2, ftpext, or ftpsockets, the function attempts to connect. If the connection fails, it returns false.

Plugins can add their own classes for interacting with files using the filter filesystem_method_file. The filter must return the path to the class file.

Examples of such classes:

WP_Filesystem_Direct{}
WP_Filesystem_FTPext{}
WP_Filesystem_ftpsockets{}
WP_Filesystem_SSH2{}
WP_Filesystem_Base{} - the base class from which all classes inherit.

1 time — 0.001446 sec (very slow) | 50000 times — 4.11 sec (fast)

Hooks from the function

filesystem_method_file

Returns

true|false|null.

True on success, when the connection to the file system was successful.
false on failure, for example, if the FTP connection failed. Or if no method was found - get_filesystem_method() returned empty.
null, if the class file for the method does not exist.

Usage

// require_once ABSPATH . 'wp-admin/includes/file.php';
WP_Filesystem( $args, $context, $allow_relaxed_file_ownership );

$args(array|false)

Parameters for the connection, passed directly to the class WP_Filesystem_*( $args ).
Default: false - presets

$context(string|false)

Context for get_filesystem_method().
The full path to the directory that is checked for write permissions. By default, $context = WP_CONTENT_DIR.
Default: false - WP_CONTENT_DIR

$allow_relaxed_file_ownership(true|false)

Whether to allow the group/world to write files. Passed directly to the function get_filesystem_method().

When true, the class WP_Filesystem_Direct{} will be used unless a method for interacting with files is strictly specified via the constant FS_METHOD and the $context folder allows the current PHP process to write files.

When false, the method WP_Filesystem_Direct{} will only be used if the PHP process is the owner of the files. More specifically, the owner of the file /wp-admin/includes/file.php and the owner of the temporarily created file in the $context folder must match.

Default: false

Examples

#1 Using the wp_filesystem

global $wp_filesystem;

// create a file interaction object, if it is not already created
if( ! $wp_filesystem ){
	require_once ABSPATH . 'wp-admin/includes/file.php';
	WP_Filesystem();
} 

// use the object
echo $wp_filesystem->abspath(); //  /home/www/example.com/public_html/

$wp_filesystem->delete( $maintenance_file );
$wp_filesystem->put_contents( $maintenance_file, $maintenance_string );
// etc.

A list of useful methods:

abspath( ) — Returns the path on the remote filesystem of ABSPATH.
copy( $source, $destination, $overwrite, $mode ) — Copies a file.
cwd( ) — Gets the current working directory.
delete( $file, $recursive, $type ) — Deletes a file or directory.
dirlist( $path, $include_hidden, $recursive ) — Gets details for files in a directory or a specific file.
exists( $path ) — Checks if a file or directory exists.
get_contents( $file ) — Reads entire file into a string.
get_contents_array( $file ) — Reads entire file into an array.
is_binary( $text ) — Determines if the string provided contains binary characters.
is_dir( $path ) — Checks if resource is a directory.
is_file( $file ) — Checks if resource is a file.
is_readable( $file ) — Checks if a file is readable.
is_writable( $path ) — Checks if a file or directory is writable.
mkdir( $path, $chmod, $chown, $chgrp ) — Creates a directory.
move( $source, $destination, $overwrite ) — Moves a file.
mtime( $file ) — Gets the file modification time.
put_contents( $file, $contents, $mode ) — Writes a string to a file.
rmdir( $path, $recursive ) — Deletes a directory.
search_for_folder( $folder, $base, $loop ) — Locates a folder on the remote filesystem.
size( $file ) — Gets the file size (in bytes).
touch( $file, $time, $atime ) — Sets the access and modification times of a file.
wp_content_dir( ) — Returns the path on the remote filesystem of WP_CONTENT_DIR.
wp_lang_dir( ) — Returns the path on the remote filesystem of WP_LANG_DIR.
wp_plugins_dir( ) — Returns the path on the remote filesystem of WP_PLUGIN_DIR.
wp_themes_dir( $theme ) — Returns the path on the remote filesystem of the Themes Directory.

#2 Each call creates a new instance

Each call to WP_Filesystem() overwrites the variable global $wp_filesystem;. So it may be a good idea to check if the object has already been created before calling this function.

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

global $wp_filesystem;

// base init
WP_Filesystem();
echo get_class( $wp_filesystem ); // WP_Filesystem_Direct

// call one more time
define( 'FS_METHOD', 'ssh2' );
WP_Filesystem();
echo get_class( $wp_filesystem ); // WP_Filesystem_SSH2

Notes

Global. WP_Filesystem_Base. $wp_filesystem WordPress filesystem subclass.

Changelog

Since 2.5.0

Introduced.

`WP_Filesystem() WP Filesystem` code ^{WP 6.9.1}

wp-admin/includes/file.php

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;
}