Get WordPress

Make WordPress Core

Changeset 25560

Timestamp:
09/22/2013 04:43:29 AM (11 years ago)
Author:
dd32
Message:

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.
See #18476 See #23122. Props kurtpayne, bananastalktome, and, DrewAPicture

Location:
trunk/src/wp-admin/includes
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/class-wp-filesystem-base.php

    r25305 r25560  
    11<?php
    22/**
    3  * Base WordPress Filesystem.
     3 * Base WordPress Filesystem
    44 *
    55 * @package WordPress
    … …  
    1010 * Base WordPress Filesystem class for which Filesystem implementations extend
    1111 *
    12  * @since 2.5
     12 * @since 2.5
    1313 */
    1414class WP_Filesystem_Base {
    … …  
    1616     * Whether to display debug data for the connection.
    1717     *
    18      * @since 2.5
    19      * @access public
     18     * @
     19     * @
    2020     * @var bool
    2121     */
    … …  
    2525     * Cached list of local filepaths to mapped remote filepaths.
    2626     *
    27      * @since 2.7
    2827     * @access private
     28
    2929     * @var array
    3030     */
    … …  
    3434     * The Access method of the current connection, Set automatically.
    3535     *
    36      * @since 2.5
    37      * @access public
     36     * @
     37     * @
    3838     * @var string
    3939     */
    … …  
    4141
    4242    /**
    43      * Returns the path on the remote filesystem of ABSPATH
    44      *
    45      * @since 2.7
    46      * @access public
     43     * Constructor (empty).
     44     */
     45    function __construct() {}
     46
     47    /**
     48     * Return the path on the remote filesystem of ABSPATH.
     49     *
     50     * @access public
     51     * @since 2.7.0
     52     *
    4753     * @return string The location of the remote path.
    4854     */
    … …  
    5662
    5763    /**
    58      * Returns the path on the remote filesystem of WP_CONTENT_DIR
    59      *
    60      * @since 2.7
    61      * @access public
     64     * Return the path on the remote filesystem of WP_CONTENT_DIR.
     65     *
     66     * @access public
     67     * @since 2.7.0
     68     *
    6269     * @return string The location of the remote path.
    6370     */
    … …  
    6774
    6875    /**
    69      * Returns the path on the remote filesystem of WP_PLUGIN_DIR
    70      *
    71      * @since 2.7
    72      * @access public
     76     * Return
     77     *
     78     * @
     79     * @
    7380     *
    7481     * @return string The location of the remote path.
    … …  
    7986
    8087    /**
    81      * Returns the path on the remote filesystem of the Themes Directory
    82      *
    83      * @since 2.7
    84      * @access public
    85      *
    86      * @param string $theme The Theme stylesheet or template for the directory
     88     * Return
     89     *
     90     * @
     91     * @
     92     *
     93     * @param string $theme The Theme stylesheet or template for the directory
    8794     * @return string The location of the remote path.
    8895     */
    … …  
    98105
    99106    /**
    100      * Returns the path on the remote filesystem of WP_LANG_DIR
    101      *
     107     * Return the path on the remote filesystem of WP_LANG_DIR.
     108     *
     109     * @access public
    102110     * @since 3.2.0
    103      * @access public
    104111     *
    105112     * @return string The location of the remote path.
    … …  
    110117
    111118    /**
    112      * Locates a folder on the remote filesystem.
    113      *
    114      * Deprecated; use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() methods instead.
    115      *
    116      * @since 2.5
    117      * @deprecated 2.7
    118      * @access public
    119      *
    120      * @param string $base The folder to start searching from
    121      * @param bool $echo True to display debug information
    122      * @return string The location of the remote path.
    123      */
    124     function find_base_dir($base = '.', $echo = false) {
     119     * Locate a folder on the remote filesystem.
     120     *
     121     * @access public
     122     * @since 2.5.0
     123     * @deprecated 2.7.0 use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() instead.
     124     * @see WP_Filesystem::abspath()
     125     * @see WP_Filesystem::wp_content_dir()
     126     * @see WP_Filesystem::wp_plugins_dir()
     127     * @see WP_Filesystem::wp_themes_dir()
     128     * @see WP_Filesystem::wp_lang_dir()
     129     *
     130     * @param string $base The folder to start searching from.
     131     * @param bool   $echo True to display debug information.
     132     *                     Default false.
     133     * @return string The location of the remote path.
     134     */
     135    function find_base_dir( $base = '.', $echo = false ) {
    125136        _deprecated_function(__FUNCTION__, '2.7', 'WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir()' );
    126137        $this->verbose = $echo;
    … …  
    129140
    130141    /**
    131      * Locates a folder on the remote filesystem.
    132      *
    133      * Deprecated; use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() methods instead.
    134      *
    135      * @since 2.5
    136      * @deprecated 2.7
    137      * @access public
    138      *
    139      * @param string $base The folder to start searching from
    140      * @param bool $echo True to display debug information
    141      * @return string The location of the remote path.
    142      */
    143     function get_base_dir($base = '.', $echo = false) {
     142     * Locate a folder on the remote filesystem.
     143     *
     144     * @access public
     145     * @since 2.5.0
     146     * @deprecated 2.7.0 use WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir() methods instead.
     147     * @see WP_Filesystem::abspath()
     148     * @see WP_Filesystem::wp_content_dir()
     149     * @see WP_Filesystem::wp_plugins_dir()
     150     * @see WP_Filesystem::wp_themes_dir()
     151     * @see WP_Filesystem::wp_lang_dir()
     152     *
     153     * @param string $base The folder to start searching from.
     154     * @param bool   $echo True to display debug information.
     155     * @return string The location of the remote path.
     156     */
     157    function get_base_dir( $base = '.', $echo = false ) {
    144158        _deprecated_function(__FUNCTION__, '2.7', 'WP_Filesystem::abspath() or WP_Filesystem::wp_*_dir()' );
    145159        $this->verbose = $echo;
    … …  
    148162
    149163    /**
    150      * Locates a folder on the remote filesystem.
    151      *
    152      * Assumes that on Windows systems, Stripping off the Drive letter is OK
    153      * Sanitizes \\ to / in windows filepaths.
    154      *
    155      * @since 2.7
    156      * @access public
    157      *
    158      * @param string $folder the folder to locate
    159      * @return string The location of the remote path.
    160      */
    161     function find_folder($folder) {
     164     * Locate a folder on the remote filesystem.
     165     *
     166     * Assumes that on Windows systems, Stripping off the Drive
     167     * Sanitizes \\ to / in windows filepaths.
     168     *
     169     * @
     170     * @
     171     *
     172     * @param string $folder the folder to locate
     173     * @return string The location of the remote path.
     174     */
     175    function find_folder() {
    162176
    163177        if ( isset( $this->cache[ $folder ] ) )
    … …  
    216230
    217231    /**
    218      * Locates a folder on the remote filesystem.
    219      *
    220      * Expects Windows sanitized path
    221      *
    222      * @since 2.7
     232     * Locate a folder on the remote filesystem.
     233     *
     234     * Expects Windows sanitized path.
     235     *
    223236     * @access private
    224      *
    225      * @param string $folder the folder to locate
    226      * @param string $base the folder to start searching from
    227      * @param bool $loop if the function has recursed, Internal use only
    228      * @return string The location of the remote path.
    229      */
    230     function search_for_folder($folder, $base = '.', $loop = false ) {
     237     * @since 2.7.0
     238     *
     239     * @param string $folder The folder to locate.
     240     * @param string $base   The folder to start searching from.
     241     * @param bool   $loop   If the function has recursed, Internal use only.
     242     * @return string The location of the remote path.
     243     */
     244    function search_for_folder( $folder, $base = '.', $loop = false ) {
    231245        if ( empty( $base ) || '.' == $base )
    232246            $base = trailingslashit($this->cwd());
    … …  
    283297
    284298    /**
    285      * Returns the *nix style file permissions for a file
    286      *
    287      * From the PHP documentation page for fileperms()
     299     * Return
     300     *
     301     * From the PHP documentation page for fileperms()
    288302     *
    289303     * @link http://docs.php.net/fileperms
    290      * @since 2.5
    291      * @access public
    292      *
    293      * @param string $file string filename
    294      * @return string *nix style representation of permissions
    295      */
    296     function gethchmod($file){
     304     *
     305     * @access public
     306     * @since 2.5.0
     307     *
     308     * @param string $file String filename.
     309     * @return string The *nix-style representation of permissions.
     310     */
     311    function gethchmod( $file ){
    297312        $perms = $this->getchmod($file);
    298313        if (($perms & 0xC000) == 0xC000) // Socket
    … …  
    337352
    338353    /**
    339      * Converts *nix style file permissions to a octal number.
     354     * Convertstyle file permissions to a octal number.
    340355     *
    341356     * Converts '-rw-r--r--' to 0644
    … …  
    343358     *
    344359     * @link http://docs.php.net/manual/en/function.chmod.php#49614
    345      * @since 2.5
    346      * @access public
    347      *
    348      * @param string $mode string *nix style file permission
     360     *
     361     * @access public
     362     * @since 2.5.0
     363     *
     364     * @param string $mode string The *nix-style file permission.
    349365     * @return int octal representation
    350366     */
    351     function getnumchmodfromh($mode) {
     367    function getnumchmodfromh() {
    352368        $realmode = '';
    353369        $legal =  array('', 'w', 'r', 'x', '-');
    … …  
    370386
    371387    /**
    372      * Determines if the string provided contains binary characters.
    373      *
    374      * @since 2.7
     388     * Determine if the string provided contains binary characters.
     389     *
    375390     * @access private
    376      *
    377      * @param string $text String to test against
    378      * @return bool true if string is binary, false otherwise
     391     * @since 2.7.0
     392     *
     393     * @param string $text String to test against.
     394     * @return bool true if string is binary, false otherwise.
    379395     */
    380396    function is_binary( $text ) {
    381397        return (bool) preg_match( '|[^\x20-\x7E]|', $text ); // chr(32)..chr(127)
    382398    }
    383 }
     399
     400    /**
     401     * Change the ownership of a file / folder.
     402     *
     403     * Default behavior is to do nothing, override this in your subclass, if desired.
     404     *
     405     * @since 2.5.0
     406     *
     407     * @param string $file      Path to the file.
     408     * @param mixed  $owner     A user name or number.
     409     * @param bool   $recursive Optional. If set True changes file owner recursivly. Defaults to False.
     410     * @return bool Returns true on success or false on failure.
     411     */
     412    function chown( $file, $owner, $recursive = false ) {
     413        return false;
     414    }
     415
     416    /**
     417     * Connect filesystem.
     418     *
     419     * @since 2.5.0
     420     *
     421     * @return bool True on success or false on failure (always true for WP_Filesystem_Direct).
     422     */
     423    function connect() {
     424        return true;
     425    }
     426
     427    /**
     428     * Read entire file into a string.
     429     *
     430     * @since 2.5.0
     431     *
     432     * @param string $file Name of the file to read.
     433     * @return string|bool Returns the read data or false on failure.
     434     */
     435    function get_contents( $file ) {
     436        return false;
     437    }
     438
     439    /**
     440     * Read entire file into an array.
     441     *
     442     * @since 2.5.0
     443     *
     444     * @param string $file Path to the file.
     445     * @return array|bool the file contents in an array or false on failure.
     446     */
     447    function get_contents_array( $file ) {
     448        return false;
     449    }
     450
     451    /**
     452     * Write a string to a file.
     453     *
     454     * @since 2.5.0
     455     *
     456     * @param string $file     Remote path to the file where to write the data.
     457     * @param string $contents The data to write.
     458     * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
     459     * @return bool False on failure.
     460     */
     461    function put_contents( $file, $contents, $mode = false ) {
     462        return false;
     463    }
     464
     465    /**
     466     * Get the current working directory.
     467     *
     468     * @since 2.5.0
     469     *
     470     * @return string|bool The current working directory on success, or false on failure.
     471     */
     472    function cwd() {
     473        return false;
     474    }
     475
     476    /**
     477     * Change current directory.
     478     *
     479     * @since 2.5.0
     480     *
     481     * @param string $dir The new current directory.
     482     * @return bool Returns true on success or false on failure.
     483     */
     484    function chdir( $dir ) {
     485        return false;
     486    }
     487
     488    /**
     489     * Change the file group.
     490     *
     491     * @since 2.5.0
     492     *
     493     * @param string $file      Path to the file.
     494     * @param mixed  $group     A group name or number.
     495     * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
     496     * @return bool Returns true on success or false on failure.
     497     */
     498    function chgrp( $file, $group, $recursive = false ) {
     499        return false;
     500    }
     501
     502    /**
     503     * Change filesystem permissions.
     504     *
     505     * @since 2.5.0
     506     *
     507     * @param string $file      Path to the file.
     508     * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
     509     * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
     510     * @return bool Returns true on success or false on failure.
     511     */
     512    function chmod( $file, $mode = false, $recursive = false ) {
     513        return false;
     514    }
     515
     516    /**
     517     * Get the file owner.
     518     *
     519     * @since 2.5.0
     520     *
     521     * @param string $file Path to the file.
     522     * @return string|bool Username of the user or false on error.
     523     */
     524    function owner( $file ) {
     525        return false;
     526    }
     527
     528    /**
     529     * Get the file's group.
     530     *
     531     * @since 2.5.0
     532     *
     533     * @param string $file Path to the file.
     534     * @return string|bool The group or false on error.
     535     */
     536    function group( $file ) {
     537        return false;
     538    }
     539
     540    /**
     541     * Copy a file.
     542     *
     543     * @since 2.5.0
     544     *
     545     * @param string $source      Path to the source file.
     546     * @param string $destination Path to the destination file.
     547     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
     548     *                            Default false.
     549     * @param int    $mode        Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
     550     *                            Default false.
     551     * @return bool True if file copied successfully, False otherwise.
     552     */
     553    function copy( $source, $destination, $overwrite = false, $mode = false ) {
     554        return false;
     555    }
     556
     557    /**
     558     * Move a file.
     559     *
     560     * @since 2.5.0
     561     *
     562     * @param string $source      Path to the source file.
     563     * @param string $destination Path to the destination file.
     564     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
     565     *                            Default false.
     566     * @return bool True if file copied successfully, False otherwise.
     567     */
     568    function move( $source, $destination, $overwrite = false ) {
     569        return false;
     570    }
     571
     572    /**
     573     * Delete a file or directory.
     574     *
     575     * @since 2.5.0
     576     *
     577     * @param string $file      Path to the file.
     578     * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
     579     *                          Default false.
     580     * @param bool   $type      Type of resource. 'f' for file, 'd' for directory.
     581     *                          Default false.
     582     * @return bool True if the file or directory was deleted, false on failure.
     583     */
     584    function delete( $file, $recursive = false, $type = false ) {
     585        return false;
     586    }
     587
     588    /**
     589     * Check if a file or directory exists.
     590     *
     591     * @since 2.5.0
     592     *
     593     * @param string $file Path to file/directory.
     594     * @return bool Whether $file exists or not.
     595     */
     596    function exists( $file ) {
     597        return false;
     598    }
     599
     600    /**
     601     * Check if resource is a file.
     602     *
     603     * @since 2.5.0
     604     *
     605     * @param string $file File path.
     606     * @return bool Whether $file is a file.
     607     */
     608    function is_file( $file ) {
     609        return false;
     610    }
     611
     612    /**
     613     * Check if resource is a directory.
     614     *
     615     * @since 2.5.0
     616     *
     617     * @param string $path Directory path.
     618     * @return bool Whether $path is a directory.
     619     */
     620    function is_dir( $path ) {
     621        return false;
     622    }
     623
     624    /**
     625     * Check if a file is readable.
     626     *
     627     * @since 2.5.0
     628     *
     629     * @param string $file Path to file.
     630     * @return bool Whether $file is readable.
     631     */
     632    function is_readable( $file ) {
     633        return false;
     634    }
     635
     636    /**
     637     * Check if a file or directory is writable.
     638     *
     639     * @since 2.5.0
     640     *
     641     * @param string $path Path to file/directory.
     642     * @return bool Whether $file is writable.
     643     */
     644    function is_writable( $file ) {
     645        return false;
     646    }
     647
     648    /**
     649     * Gets the file's last access time.
     650     *
     651     * @since 2.5.0
     652     *
     653     * @param string $file Path to file.
     654     * @return int Unix timestamp representing last access time.
     655     */
     656    function atime( $file ) {
     657        return false;
     658    }
     659
     660    /**
     661     * Gets the file modification time.
     662     *
     663     * @since 2.5.0
     664     *
     665     * @param string $file Path to file.
     666     * @return int Unix timestamp representing modification time.
     667     */
     668    function mtime( $file ) {
     669        return false;
     670    }
     671
     672    /**
     673     * Gets the file size (in bytes).
     674     *
     675     * @since 2.5.0
     676     *
     677     * @param string $file Path to file.
     678     * @return int Size of the file in bytes.
     679     */
     680    function size( $file ) {
     681        return false;
     682    }
     683
     684    /**
     685     * Set the access and modification times of a file.
     686     *
     687     * Note: If $file doesn't exist, it will be created.
     688     *
     689     * @since 2.5.0
     690     *
     691     * @param string $file  Path to file.
     692     * @param int    $time  Optional. Modified time to set for file.
     693     *                      Default 0.
     694     * @param int    $atime Optional. Access time to set for file.
     695     *                      Default 0.
     696     * @return bool Whether operation was successful or not.
     697     */
     698    function touch( $file, $time = 0, $atime = 0 ) {
     699        return false;
     700    }
     701
     702    /**
     703     * Create a directory.
     704     *
     705     * @since 2.5.0
     706     *
     707     * @param string $path  Path for new directory.
     708     * @param mixed  $chmod Optional. The permissions as octal number, (or False to skip chmod)
     709     *                      Default false.
     710     * @param mixed  $chown Optional. A user name or number (or False to skip chown)
     711     *                      Default false.
     712     * @param mixed  $chgrp Optional. A group name or number (or False to skip chgrp).
     713     *                      Default false.
     714     * @return bool False if directory cannot be created, true otherwise.
     715     */
     716    function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     717        return false;
     718    }
     719
     720    /**
     721     * Delete a directory.
     722     *
     723     * @since 2.5.0
     724     *
     725     * @param string $path      Path to directory.
     726     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
     727     *                          Default false.
     728     * @return bool Whether directory is deleted successfully or not.
     729     */
     730    function rmdir( $path, $recursive = false ) {
     731        return false;
     732    }
     733
     734    /**
     735     * Get details for files in a directory or a specific file.
     736     *
     737     * @since 2.5.0
     738     *
     739     * @param string $path           Path to directory or file.
     740     * @param bool   $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
     741     *                               Default true.
     742     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
     743     *                               Default false.
     744     * @return array|bool {
     745     *     Array of files. False if unable to list directory contents.
     746     *
     747     *     @type string 'name'        Name of the file/directory.
     748     *     @type string 'perms'       *nix representation of permissions.
     749     *     @type int    'permsn'      Octal representation of permissions.
     750     *     @type string 'owner'       Owner name or ID.
     751     *     @type int    'size'        Size of file in bytes.
     752     *     @type int    'lastmodunix' Last modified unix timestamp.
     753     *     @type mixed  'lastmod'     Last modified month (3 letter) and day (without leading 0).
     754     *     @type int    'time'        Last modified time.
     755     *     @type string 'type'        Type of resource. 'f' for file, 'd' for directory.
     756     *     @type mixed  'files'       If a directory and $recursive is true, contains another array of files.
     757     * }
     758     */
     759    function dirlist( $path, $include_hidden = true, $recursive = false ) {
     760        return false;
     761    }
     762
     763} // WP_Filesystem_Base

  • trunk/src/wp-admin/includes/class-wp-filesystem-direct.php

    r25349 r25560  
    1616 */
    1717class WP_Filesystem_Direct extends WP_Filesystem_Base {
    18     var $errors = null;
     18
    1919    /**
    2020     * constructor
    … …  
    2525        $this->method = 'direct';
    2626        $this->errors = new WP_Error();
    27     }
    28 
    29     /**
    30      * connect filesystem.
    31      *
    32      * @return bool Returns true on success or false on failure (always true for WP_Filesystem_Direct).
    33      */
    34     function connect() {
    35         return true;
    3627    }
    3728
    … …  
    186177     *
    187178     * @param string $file Path to the file.
    188      * @return string Username of the user.
     179     * @return stringr.
    189180     */
    190181    function owner($file) {

  • trunk/src/wp-admin/includes/class-wp-filesystem-ftpext.php

    r25349 r25560  
    180180            return (bool)@ftp_site($this->link, sprintf('CHMOD %o %s', $mode, $file));
    181181        return (bool)@ftp_chmod($this->link, $mode, $file);
    182     }
    183 
    184     function chown($file, $owner, $recursive = false ) {
    185         return false;
    186182    }
    187183

  • trunk/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php

    r25349 r25560  
    188188    }
    189189
    190     function chown($file, $owner, $recursive = false ) {
    191         return false;
    192     }
    193 
    194190    function owner($file) {
    195191        $dir = $this->dirlist($file);

  • trunk/src/wp-admin/includes/class-wp-filesystem-ssh2.php

    r25306 r25560  
    11<?php
    22/**
    3  * WordPress SSH2 Filesystem.
    4  *
    5  * @package WordPress
    6  * @subpackage Filesystem
    7  */
    8 
    9 /**
    10  * WordPress Filesystem Class for implementing SSH2.
     3 * WordPress Filesystem Class for implementing SSH2
    114 *
    125 * To use this class you must follow these steps for PHP 5.2.6+
    … …  
    3629 * Note: as of WordPress 2.8, This utilises the PHP5+ function 'stream_get_contents'
    3730 *
    38  * @since 2.7
     31 * @since 2.7.0
     32 *
    3933 * @package WordPress
    4034 * @subpackage Filesystem
    41  * @uses WP_Filesystem_Base Extends class
    4235 */
    4336class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
    … …  
    209202    }
    210203
    211     function chown($file, $owner, $recursive = false ) {
     204    /**
     205     * Change the ownership of a file / folder.
     206     *
     207     * @since Unknown
     208     *
     209     * @param string $file    Path to the file.
     210     * @param mixed  $owner   A user name or number.
     211     * @param bool $recursive Optional. If set True changes file owner recursivly. Defaults to False.
     212     * @return bool Returns true on success or false on failure.
     213     */
     214    function chown( $file, $owner, $recursive = false ) {
    212215        if ( ! $this->exists($file) )
    213216            return false;
Note: See TracChangeset for help on using the changeset viewer.