Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2025-01-03 15:08:10 +01:00
Code Issues Projects Releases Wiki Activity

First pass at documenting the WP_Filesystem methods. This also introduces stubs of the methods into the base class which are documented, which subclasses can override, some methods were cleaned up at the same time.

Browse Source 
See #18476 See #23122. Props kurtpayne, bananastalktome, and, DrewAPicture 

Built from https://develop.svn.wordpress.org/trunk@25560


git-svn-id: http://core.svn.wordpress.org/trunk@25478 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Dion Hulse 2013-09-22 04:44:10 +00:00
parent e6e033aa08
commit c43600ea4b
5 changed files with 458 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

504
wp-admin/includes/class-wp-filesystem-base.php
View File

@ -1,6 +1,6 @@
<?php
/**
* Base WordPress Filesystem.
* Base WordPress Filesystem
*
* @package WordPress
* @subpackage Filesystem
@ -9,14 +9,14 @@
/**
* Base WordPress Filesystem class for which Filesystem implementations extend
*
* @since 2.5
* @since 2.5.0
*/
class WP_Filesystem_Base {
/**
* Whether to display debug data for the connection.
*
* @since 2.5
* @access public
* @since 2.5.0
* @var bool
*/
var $verbose = false;
@ -24,8 +24,8 @@ class WP_Filesystem_Base {
/**
* Cached list of local filepaths to mapped remote filepaths.
*
* @since 2.7
* @access private
* @since 2.7.0
* @var array
*/
var $cache = array();
@ -33,17 +33,23 @@ class WP_Filesystem_Base {
/**
* The Access method of the current connection, Set automatically.
*
* @since 2.5
* @access public
* @since 2.5.0
* @var string
*/
var $method = '';
/**
* Returns the path on the remote filesystem of ABSPATH
* Constructor (empty).
*/
function __construct() {}
/**
* Return the path on the remote filesystem of ABSPATH.
*
* @since 2.7
* @access public
* @since 2.7.0
*
* @return string The location of the remote path.
*/
function abspath() {
@ -55,10 +61,11 @@ class WP_Filesystem_Base {
}
/**
* Returns the path on the remote filesystem of WP_CONTENT_DIR
* Return the path on the remote filesystem of WP_CONTENT_DIR.
*
* @since 2.7
* @access public
* @since 2.7.0
*
* @return string The location of the remote path.
*/
function wp_content_dir() {
@ -66,10 +73,10 @@ class WP_Filesystem_Base {
}
/**
* Returns the path on the remote filesystem of WP_PLUGIN_DIR
* Return the path on the remote filesystem of WP_PLUGIN_DIR.
*
* @since 2.7
* @access public
* @since 2.7.0
*
* @return string The location of the remote path.
*/
@ -78,12 +85,12 @@ class WP_Filesystem_Base {
}
/**
* Returns the path on the remote filesystem of the Themes Directory
* Return the path on the remote filesystem of the Themes Directory.
*
* @since 2.7
* @access public
* @since 2.7.0
*
* @param string $theme The Theme stylesheet or template for the directory
* @param string $theme The Theme stylesheet or template for the directory.
* @return string The location of the remote path.
*/
function wp_themes_dir( $theme = false ) {
@ -97,10 +104,10 @@ class WP_Filesystem_Base {
}
/**
* Returns the path on the remote filesystem of WP_LANG_DIR
* Return the path on the remote filesystem of WP_LANG_DIR.
*
* @since 3.2.0
* @access public
* @since 3.2.0
*
* @return string The location of the remote path.
*/
@ -109,56 +116,63 @@ class WP_Filesystem_Base {
}
/**
* Locates a folder on the remote filesystem.
* Locate a folder on the remote filesystem.
*
* Deprecated; use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() methods instead.
*
* @since 2.5
* @deprecated 2.7
* @access public
* @since 2.5.0
* @deprecated 2.7.0 use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() instead.
* @see WP_Filesystem::abspath()
* @see WP_Filesystem::wp_content_dir()
* @see WP_Filesystem::wp_plugins_dir()
* @see WP_Filesystem::wp_themes_dir()
* @see WP_Filesystem::wp_lang_dir()
*
* @param string $base The folder to start searching from
* @param bool $echo True to display debug information
* @param string $base The folder to start searching from.
* @param bool $echo True to display debug information.
* Default false.
* @return string The location of the remote path.
*/
function find_base_dir($base = '.', $echo = false) {
function find_base_dir( $base = '.', $echo = false ) {
_deprecated_function(__FUNCTION__, '2.7', 'WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir()' );
$this->verbose = $echo;
return $this->abspath();
}
/**
* Locates a folder on the remote filesystem.
* Locate a folder on the remote filesystem.
*
* Deprecated; use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() methods instead.
*
* @since 2.5
* @deprecated 2.7
* @access public
* @since 2.5.0
* @deprecated 2.7.0 use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() methods instead.
* @see WP_Filesystem::abspath()
* @see WP_Filesystem::wp_content_dir()
* @see WP_Filesystem::wp_plugins_dir()
* @see WP_Filesystem::wp_themes_dir()
* @see WP_Filesystem::wp_lang_dir()
*
* @param string $base The folder to start searching from
* @param bool $echo True to display debug information
* @param string $base The folder to start searching from.
* @param bool $echo True to display debug information.
* @return string The location of the remote path.
*/
function get_base_dir($base = '.', $echo = false) {
function get_base_dir( $base = '.', $echo = false ) {
_deprecated_function(__FUNCTION__, '2.7', 'WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir()' );
$this->verbose = $echo;
return $this->abspath();
}
/**
* Locates a folder on the remote filesystem.
* Locate a folder on the remote filesystem.
*
* Assumes that on Windows systems, Stripping off the Drive letter is OK
* Sanitizes \\ to / in windows filepaths.
* Assumes that on Windows systems, Stripping off the Drive
* letter is OK Sanitizes \\ to / in windows filepaths.
*
* @since 2.7
* @access public
* @since 2.7.0
*
* @param string $folder the folder to locate
* @param string $folder the folder to locate.
* @return string The location of the remote path.
*/
function find_folder($folder) {
function find_folder( $folder ) {
if ( isset( $this->cache[ $folder ] ) )
return $this->cache[ $folder ];
@ -215,19 +229,19 @@ class WP_Filesystem_Base {
}
/**
* Locates a folder on the remote filesystem.
* Locate a folder on the remote filesystem.
*
* Expects Windows sanitized path
* Expects Windows sanitized path.
*
* @since 2.7
* @access private
* @since 2.7.0
*
* @param string $folder the folder to locate
* @param string $base the folder to start searching from
* @param bool $loop if the function has recursed, Internal use only
* @param string $folder The folder to locate.
* @param string $base The folder to start searching from.
* @param bool $loop If the function has recursed, Internal use only.
* @return string The location of the remote path.
*/
function search_for_folder($folder, $base = '.', $loop = false ) {
function search_for_folder( $folder, $base = '.', $loop = false ) {
if ( empty( $base ) || '.' == $base )
$base = trailingslashit($this->cwd());
@ -282,18 +296,19 @@ class WP_Filesystem_Base {
}
/**
* Returns the *nix style file permissions for a file
* Return the *nix-style file permissions for a file.
*
* From the PHP documentation page for fileperms()
* From the PHP documentation page for fileperms().
*
* @link http://docs.php.net/fileperms
* @since 2.5
* @access public
*
* @param string $file string filename
* @return string *nix style representation of permissions
* @access public
* @since 2.5.0
*
* @param string $file String filename.
* @return string The *nix-style representation of permissions.
*/
function gethchmod($file){
function gethchmod( $file ){
$perms = $this->getchmod($file);
if (($perms & 0xC000) == 0xC000) // Socket
$info = 's';
@ -336,19 +351,20 @@ class WP_Filesystem_Base {
}
/**
* Converts *nix style file permissions to a octal number.
* Convert *nix-style file permissions to a octal number.
*
* Converts '-rw-r--r--' to 0644
* From "info at rvgate dot nl"'s comment on the PHP documentation for chmod()
*
* @link http://docs.php.net/manual/en/function.chmod.php#49614
* @since 2.5
* @access public
*
* @param string $mode string *nix style file permission
* @access public
* @since 2.5.0
*
* @param string $mode string The *nix-style file permission.
* @return int octal representation
*/
function getnumchmodfromh($mode) {
function getnumchmodfromh( $mode ) {
$realmode = '';
$legal = array('', 'w', 'r', 'x', '-');
$attarray = preg_split('//', $mode);
@ -369,15 +385,379 @@ class WP_Filesystem_Base {
}
/**
* Determines if the string provided contains binary characters.
* Determine if the string provided contains binary characters.
*
* @since 2.7
* @access private
* @since 2.7.0
*
* @param string $text String to test against
* @return bool true if string is binary, false otherwise
* @param string $text String to test against.
* @return bool true if string is binary, false otherwise.
*/
function is_binary( $text ) {
return (bool) preg_match( '|[^\x20-\x7E]|', $text ); // chr(32)..chr(127)
}
}
/**
* Change the ownership of a file / folder.
*
* Default behavior is to do nothing, override this in your subclass, if desired.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @param mixed $owner A user name or number.
* @param bool $recursive Optional. If set True changes file owner recursivly. Defaults to False.
* @return bool Returns true on success or false on failure.
*/
function chown( $file, $owner, $recursive = false ) {
return false;
}
/**
* Connect filesystem.
*
* @since 2.5.0
*
* @return bool True on success or false on failure (always true for WP_Filesystem_Direct).
*/
function connect() {
return true;
}
/**
* Read entire file into a string.
*
* @since 2.5.0
*
* @param string $file Name of the file to read.
* @return string|bool Returns the read data or false on failure.
*/
function get_contents( $file ) {
return false;
}
/**
* Read entire file into an array.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @return array|bool the file contents in an array or false on failure.
*/
function get_contents_array( $file ) {
return false;
}
/**
* Write a string to a file.
*
* @since 2.5.0
*
* @param string $file Remote path to the file where to write the data.
* @param string $contents The data to write.
* @param int $mode Optional. The file permissions as octal number, usually 0644.
* @return bool False on failure.
*/
function put_contents( $file, $contents, $mode = false ) {
return false;
}
/**
* Get the current working directory.
*
* @since 2.5.0
*
* @return string|bool The current working directory on success, or false on failure.
*/
function cwd() {
return false;
}
/**
* Change current directory.
*
* @since 2.5.0
*
* @param string $dir The new current directory.
* @return bool Returns true on success or false on failure.
*/
function chdir( $dir ) {
return false;
}
/**
* Change the file group.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @param mixed $group A group name or number.
* @param bool $recursive Optional. If set True changes file group recursively. Defaults to False.
* @return bool Returns true on success or false on failure.
*/
function chgrp( $file, $group, $recursive = false ) {
return false;
}
/**
* Change filesystem permissions.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @param int $mode Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
* @param bool $recursive Optional. If set True changes file group recursively. Defaults to False.
* @return bool Returns true on success or false on failure.
*/
function chmod( $file, $mode = false, $recursive = false ) {
return false;
}
/**
* Get the file owner.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @return string|bool Username of the user or false on error.
*/
function owner( $file ) {
return false;
}
/**
* Get the file's group.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @return string|bool The group or false on error.
*/
function group( $file ) {
return false;
}
/**
* Copy a file.
*
* @since 2.5.0
*
* @param string $source Path to the source file.
* @param string $destination Path to the destination file.
* @param bool $overwrite Optional. Whether to overwrite the destination file if it exists.
* Default false.
* @param int $mode Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
* Default false.
* @return bool True if file copied successfully, False otherwise.
*/
function copy( $source, $destination, $overwrite = false, $mode = false ) {
return false;
}
/**
* Move a file.
*
* @since 2.5.0
*
* @param string $source Path to the source file.
* @param string $destination Path to the destination file.
* @param bool $overwrite Optional. Whether to overwrite the destination file if it exists.
* Default false.
* @return bool True if file copied successfully, False otherwise.
*/
function move( $source, $destination, $overwrite = false ) {
return false;
}
/**
* Delete a file or directory.
*
* @since 2.5.0
*
* @param string $file Path to the file.
* @param bool $recursive Optional. If set True changes file group recursively. Defaults to False.
* Default false.
* @param bool $type Type of resource. 'f' for file, 'd' for directory.
* Default false.
* @return bool True if the file or directory was deleted, false on failure.
*/
function delete( $file, $recursive = false, $type = false ) {
return false;
}
/**
* Check if a file or directory exists.
*
* @since 2.5.0
*
* @param string $file Path to file/directory.
* @return bool Whether $file exists or not.
*/
function exists( $file ) {
return false;
}
/**
* Check if resource is a file.
*
* @since 2.5.0
*
* @param string $file File path.
* @return bool Whether $file is a file.
*/
function is_file( $file ) {
return false;
}
/**
* Check if resource is a directory.
*
* @since 2.5.0
*
* @param string $path Directory path.
* @return bool Whether $path is a directory.
*/
function is_dir( $path ) {
return false;
}
/**
* Check if a file is readable.
*
* @since 2.5.0
*
* @param string $file Path to file.
* @return bool Whether $file is readable.
*/
function is_readable( $file ) {
return false;
}
/**
* Check if a file or directory is writable.
*
* @since 2.5.0
*
* @param string $path Path to file/directory.
* @return bool Whether $file is writable.
*/
function is_writable( $file ) {
return false;
}
/**
* Gets the file's last access time.
*
* @since 2.5.0
*
* @param string $file Path to file.
* @return int Unix timestamp representing last access time.
*/
function atime( $file ) {
return false;
}
/**
* Gets the file modification time.
*
* @since 2.5.0
*
* @param string $file Path to file.
* @return int Unix timestamp representing modification time.
*/
function mtime( $file ) {
return false;
}
/**
* Gets the file size (in bytes).
*
* @since 2.5.0
*
* @param string $file Path to file.
* @return int Size of the file in bytes.
*/
function size( $file ) {
return false;
}
/**
* Set the access and modification times of a file.
*
* Note: If $file doesn't exist, it will be created.
*
* @since 2.5.0
*
* @param string $file Path to file.
* @param int $time Optional. Modified time to set for file.
* Default 0.
* @param int $atime Optional. Access time to set for file.
* Default 0.
* @return bool Whether operation was successful or not.
*/
function touch( $file, $time = 0, $atime = 0 ) {
return false;
}
/**
* Create a directory.
*
* @since 2.5.0
*
* @param string $path Path for new directory.
* @param mixed $chmod Optional. The permissions as octal number, (or False to skip chmod)
* Default false.
* @param mixed $chown Optional. A user name or number (or False to skip chown)
* Default false.
* @param mixed $chgrp Optional. A group name or number (or False to skip chgrp).
* Default false.
* @return bool False if directory cannot be created, true otherwise.
*/
function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
return false;
}
/**
* Delete a directory.
*
* @since 2.5.0
*
* @param string $path Path to directory.
* @param bool $recursive Optional. Whether to recursively remove files/directories.
* Default false.
* @return bool Whether directory is deleted successfully or not.
*/
function rmdir( $path, $recursive = false ) {
return false;
}
/**
* Get details for files in a directory or a specific file.
*
* @since 2.5.0
*
* @param string $path Path to directory or file.
* @param bool $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
* Default true.
* @param bool $recursive Optional. Whether to recursively include file details in nested directories.
* Default false.
* @return array|bool {
* Array of files. False if unable to list directory contents.
*
* @type string 'name' Name of the file/directory.
* @type string 'perms' *nix representation of permissions.
* @type int 'permsn' Octal representation of permissions.
* @type string 'owner' Owner name or ID.
* @type int 'size' Size of file in bytes.
* @type int 'lastmodunix' Last modified unix timestamp.
* @type mixed 'lastmod' Last modified month (3 letter) and day (without leading 0).
* @type int 'time' Last modified time.
* @type string 'type' Type of resource. 'f' for file, 'd' for directory.
* @type mixed 'files' If a directory and $recursive is true, contains another array of files.
* }
*/
function dirlist( $path, $include_hidden = true, $recursive = false ) {
return false;
}
} // WP_Filesystem_Base

13
wp-admin/includes/class-wp-filesystem-direct.php
View File

@ -15,7 +15,7 @@
* @uses WP_Filesystem_Base Extends class
*/
class WP_Filesystem_Direct extends WP_Filesystem_Base {
var $errors = null;
/**
* constructor
*
@ -26,15 +26,6 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
$this->errors = new WP_Error();
}
/**
* connect filesystem.
*
* @return bool Returns true on success or false on failure (always true for WP_Filesystem_Direct).
*/
function connect() {
return true;
}
/**
* Reads entire file into a string
*
@ -185,7 +176,7 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
* Gets file owner
*
* @param string $file Path to the file.
* @return string Username of the user.
* @return string|bool Username of the user or false on error.
*/
function owner($file) {
$owneruid = @fileowner($file);

4
wp-admin/includes/class-wp-filesystem-ftpext.php
View File

@ -181,10 +181,6 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
return (bool)@ftp_chmod($this->link, $mode, $file);
}
function chown($file, $owner, $recursive = false ) {
return false;
}
function owner($file) {
$dir = $this->dirlist($file);
return $dir[$file]['owner'];

4
wp-admin/includes/class-wp-filesystem-ftpsockets.php
View File

@ -187,10 +187,6 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
return $this->ftp->chmod($file, $mode);
}
function chown($file, $owner, $recursive = false ) {
return false;
}
function owner($file) {
$dir = $this->dirlist($file);
return $dir[$file]['owner'];

25
wp-admin/includes/class-wp-filesystem-ssh2.php
View File

@ -1,13 +1,6 @@
<?php
/**
* WordPress SSH2 Filesystem.
*
* @package WordPress
* @subpackage Filesystem
*/
/**
* WordPress Filesystem Class for implementing SSH2.
* WordPress Filesystem Class for implementing SSH2
*
* To use this class you must follow these steps for PHP 5.2.6+
*
@ -35,10 +28,10 @@
*
* Note: as of WordPress 2.8, This utilises the PHP5+ function 'stream_get_contents'
*
* @since 2.7
* @since 2.7.0
*
* @package WordPress
* @subpackage Filesystem
* @uses WP_Filesystem_Base Extends class
*/
class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
@ -208,7 +201,17 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
return $this->run_command(sprintf('chmod -R %o %s', $mode, escapeshellarg($file)), true);
}
function chown($file, $owner, $recursive = false ) {
/**
* Change the ownership of a file / folder.
*
* @since Unknown
*
* @param string $file Path to the file.
* @param mixed $owner A user name or number.
* @param bool $recursive Optional. If set True changes file owner recursivly. Defaults to False.
* @return bool Returns true on success or false on failure.
*/
function chown( $file, $owner, $recursive = false ) {
if ( ! $this->exists($file) )
return false;
if ( ! $recursive || ! $this->is_dir($file) )