WP_Filesystem() │ WP 2.5.0

Создает объект работы с файлами WordPress. Созданный объект сохраняется в переменную global $wp_filesystem.

Что делает функция:

Функция находит подходящий метод взаимодействия с файлами с помощью get_filesystem_method().
Подключает все необходимые php файлы WordPress, которые нужны для работы найденного метода.
На основе найденного метода взаимодействия, создает объект для работы с файлами и записывает его в переменную global $wp_filesystem. Её затем мы будем использовать.
Устанавливает константы FS_CHMOD_DIR и FS_CHMOD_FILE, если они не были установлены ранее в wp-config.php.

Если в качестве метода взаимодействия был определен протокол требующий подключения, например, ssh2, ftpext, или ftpsockets, то функция пытается подключиться. Если подключиться не удалось вернет false.

Плагины могут добавлять свои классы для взаимодействия с файлами, с помощью фильтра filesystem_method_file. Фильтр должен вернуть путь к файлу класса.

Примеры таких классов:

WP_Filesystem_Direct{}
WP_Filesystem_FTPext{}
WP_Filesystem_ftpsockets{}
WP_Filesystem_SSH2{}
WP_Filesystem_Base{} - базовый класс от которого наследуются все классы.

1 раз — 0.001446 сек (очень медленно) | 50000 раз — 4.11 сек (быстро)

Хуки из функции

filesystem_method_file

Возвращает

true|false|null.

True при успехе, когда подключение к файловой системе прошло успешно.
false при неудаче, например, не удалось подключиться по ФТП. Или не найден метод - get_filesystem_method() вернула пустоту.
null, если файл класса метода не существует.

Использование

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

$args(массив|false)

Параметры подключения, Они передаются напрямую в класс WP_Filesystem_*( $args ).
По умолчанию: false - предустановки

$context(строка|false)

Контекст для get_filesystem_method().
Полный путь к директории, которая проверяется на возможность записи. По умолчанию $context = WP_CONTENT_DIR.
По умолчанию: false - WP_CONTENT_DIR

$allow_relaxed_file_ownership(true|false)

Разрешить ли группе/миру возможность записи файлов. Напрямую передается в функцию get_filesystem_method().

При true, будет использован класс WP_Filesystem_Direct{}, если жестко не указан метод взаимодействия с файлами через константу FS_METHOD и папка $context позволяет записывать файлы текущему PHP процессу.

При false, метод WP_Filesystem_Direct{} будет использоваться только если PHP процесс является владельцем файлов. А конкретнее владелец файла /wp-admin/includes/file.php и владелец временно-созданного файла в папке $context должны совпадать.

По умолчанию: false

Примеры

#1 Использование wp_filesystem

global $wp_filesystem;

// создадим объект взаимодействия с файлами, если он еще не создан
if( ! $wp_filesystem ){
	require_once ABSPATH . 'wp-admin/includes/file.php';
	WP_Filesystem();
} 

// Используем объект
echo $wp_filesystem->abspath(); //  /home/www/example.com/public_html/

$wp_filesystem->delete( $maintenance_file );
$wp_filesystem->put_contents( $maintenance_file, $maintenance_string );
// и т.д.

Список полезных методов:

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 Каждый вызов создает новый экземпляр

Каждый вызов WP_Filesystem() перезаписывает переменную global $wp_filesystem;. Поэтому прежде чем вызывать функцию возможно стоит проверить не создан ли уже объект.

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

global $wp_filesystem;

// вызовем функцию
WP_Filesystem();
echo get_class( $wp_filesystem ); // WP_Filesystem_Direct

// вызовем еще раз
define( 'FS_METHOD', 'ssh2' );
WP_Filesystem();
echo get_class( $wp_filesystem ); // WP_Filesystem_SSH2

Заметки

Global. WP_Filesystem_Base. $wp_filesystem WordPress filesystem subclass.

Список изменений

С версии 2.5.0

Введена.

Код `WP_Filesystem() WP Filesystem` ^{WP 6.7.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;
}