WordPress.org

Make WordPress Core

Changeset 45226


Ignore:
Timestamp:
04/17/2019 04:12:27 AM (8 months ago)
Author:
SergeyBiryukov
Message:

Docs: Improve documentation for various WP_Filesystem_Base methods and extending classes.

Props jaydeep-rami, man4toman, SaeedFard, mukesh27, mohadeseghasemi, ebrahimzadeh, juiiee8487, SergeyBiryukov.
Fixes #42227, #46806, #46840. See #46543.

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

Legend:

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

    r42343 r45226  
    88
    99/**
    10  * Base WordPress Filesystem class for which Filesystem implementations extend
     10 * Base WordPress Filesystem class which Filesystem implementations extend.
    1111 *
    1212 * @since 2.5.0
    1313 */
    1414class WP_Filesystem_Base {
     15
    1516    /**
    1617     * Whether to display debug data for the connection.
     
    4748
    4849    /**
    49      * Return the path on the remote filesystem of ABSPATH.
     50     * Returns the path on the remote filesystem of ABSPATH.
    5051     *
    5152     * @since 2.7.0
     
    6364
    6465    /**
    65      * Return the path on the remote filesystem of WP_CONTENT_DIR.
     66     * Returns the path on the remote filesystem of WP_CONTENT_DIR.
    6667     *
    6768     * @since 2.7.0
     
    7475
    7576    /**
    76      * Return the path on the remote filesystem of WP_PLUGIN_DIR.
     77     * Returns the path on the remote filesystem of WP_PLUGIN_DIR.
    7778     *
    7879     * @since 2.7.0
     
    8586
    8687    /**
    87      * Return the path on the remote filesystem of the Themes Directory.
     88     * Returns the path on the remote filesystem of the Themes Directory.
    8889     *
    8990     * @since 2.7.0
    9091     *
    91      * @param string $theme The Theme stylesheet or template for the directory.
     92     * @param string|false $theme Optional. The theme stylesheet or template for the directory.
     93     *                            Default false.
    9294     * @return string The location of the remote path.
    9395     */
     
    104106
    105107    /**
    106      * Return the path on the remote filesystem of WP_LANG_DIR.
     108     * Returns the path on the remote filesystem of WP_LANG_DIR.
    107109     *
    108110     * @since 3.2.0
     
    115117
    116118    /**
    117      * Locate a folder on the remote filesystem.
     119     * Locates a folder on the remote filesystem.
    118120     *
    119121     * @since 2.5.0
     
    137139
    138140    /**
    139      * Locate a folder on the remote filesystem.
     141     * Locates a folder on the remote filesystem.
    140142     *
    141143     * @since 2.5.0
     
    158160
    159161    /**
    160      * Locate a folder on the remote filesystem.
     162     * Locates a folder on the remote filesystem.
    161163     *
    162164     * Assumes that on Windows systems, Stripping off the Drive
    163      * letter is OK Sanitizes \\ to / in windows filepaths.
     165     * letter is OK Sanitizes \\ to / in Windows filepaths.
    164166     *
    165167     * @since 2.7.0
     
    230232
    231233    /**
    232      * Locate a folder on the remote filesystem.
     234     * Locates a folder on the remote filesystem.
    233235     *
    234236     * Expects Windows sanitized path.
     
    268270             * Working from /home/ to /user/ to /wordpress/ see if that file exists within
    269271             * the current folder, If it's found, change into it and follow through looking
    270              * for it. If it cant find WordPress down that route, it'll continue onto the next
     272             * for it. If it can't find WordPress down that route, it'll continue onto the next
    271273             * folder level, and see if that matches, and so on. If it reaches the end, and still
    272              * cant find it, it'll return false for the entire function.
     274             * can't find it, it'll return false for the entire function.
    273275             */
    274276            if ( isset( $files[ $key ] ) ) {
     
    312314
    313315    /**
    314      * Return the *nix-style file permissions for a file.
     316     * Returns the *nix-style file permissions for a file.
    315317     *
    316318     * From the PHP documentation page for fileperms().
     
    367369
    368370    /**
    369      * Gets the permissions of the specified file or filepath in their octal format
    370      *
    371      * @since 2.5.0
    372      * @param string $file
    373      * @return string the last 3 characters of the octal number
     371     * Gets the permissions of the specified file or filepath in their octal format.
     372     *
     373     * @since 2.5.0
     374     *
     375     * @param string $file Path to the file.
     376     * @return string Mode of the file (the last 3 digits).
    374377     */
    375378    public function getchmod( $file ) {
     
    378381
    379382    /**
    380      * Convert *nix-style file permissions to a octal number.
     383     * Converts *nix-style file permissions to a octal number.
    381384     *
    382385     * Converts '-rw-r--r--' to 0644
     
    418421
    419422    /**
    420      * Determine if the string provided contains binary characters.
     423     * Determines if the string provided contains binary characters.
    421424     *
    422425     * @since 2.7.0
    423426     *
    424427     * @param string $text String to test against.
    425      * @return bool true if string is binary, false otherwise.
     428     * @return bool True if string is binary, false otherwise.
    426429     */
    427430    public function is_binary( $text ) {
     
    430433
    431434    /**
    432      * Change the ownership of a file / folder.
     435     * Changes the owner of a file or directory.
    433436     *
    434437     * Default behavior is to do nothing, override this in your subclass, if desired.
     
    436439     * @since 2.5.0
    437440     *
    438      * @param string $file      Path to the file.
    439      * @param mixed  $owner     A user name or number.
    440      * @param bool   $recursive Optional. If set True changes file owner recursivly. Defaults to False.
    441      * @return bool Returns true on success or false on failure.
     441     * @param string     $file      Path to the file or directory.
     442     * @param string|int $owner     A user name or number.
     443     * @param bool       $recursive Optional. If set to true, changes file owner recursively.
     444     *                              Default false.
     445     * @return bool True on success, false on failure.
    442446     */
    443447    public function chown( $file, $owner, $recursive = false ) {
     
    446450
    447451    /**
    448      * Connect filesystem.
    449      *
    450      * @since 2.5.0
    451      * @abstract
    452      *
    453      * @return bool True on success or false on failure (always true for WP_Filesystem_Direct).
     452     * Connects filesystem.
     453     *
     454     * @since 2.5.0
     455     * @abstract
     456     *
     457     * @return bool True on success, false on failure (always true for WP_Filesystem_Direct).
    454458     */
    455459    public function connect() {
     
    458462
    459463    /**
    460      * Read entire file into a string.
     464     * Reads entire file into a string.
    461465     *
    462466     * @since 2.5.0
     
    464468     *
    465469     * @param string $file Name of the file to read.
    466      * @return mixed|bool Returns the read data or false on failure.
     470     * @return string|false Read data on success, false on failure.
    467471     */
    468472    public function get_contents( $file ) {
     
    471475
    472476    /**
    473      * Read entire file into an array.
     477     * Reads entire file into an array.
    474478     *
    475479     * @since 2.5.0
     
    477481     *
    478482     * @param string $file Path to the file.
    479      * @return array|bool the file contents in an array or false on failure.
     483     * @return array|false File contents in an array on success, false on failure.
    480484     */
    481485    public function get_contents_array( $file ) {
     
    484488
    485489    /**
    486      * Write a string to a file.
    487      *
    488      * @since 2.5.0
    489      * @abstract
    490      *
    491      * @param string $file     Remote path to the file where to write the data.
    492      * @param string $contents The data to write.
    493      * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
    494      * @return bool False on failure.
     490     * Writes a string to a file.
     491     *
     492     * @since 2.5.0
     493     * @abstract
     494     *
     495     * @param string    $file     Remote path to the file where to write the data.
     496     * @param string    $contents The data to write.
     497     * @param int|false $mode     Optional. The file permissions as octal number, usually 0644.
     498     *                            Default false.
     499     * @return bool True on success, false on failure.
    495500     */
    496501    public function put_contents( $file, $contents, $mode = false ) {
     
    499504
    500505    /**
    501      * Get the current working directory.
    502      *
    503      * @since 2.5.0
    504      * @abstract
    505      *
    506      * @return string|bool The current working directory on success, or false on failure.
     506     * Gets the current working directory.
     507     *
     508     * @since 2.5.0
     509     * @abstract
     510     *
     511     * @return string|false The current working directory on success, false on failure.
    507512     */
    508513    public function cwd() {
     
    511516
    512517    /**
    513      * Change current directory.
     518     * Changes current directory.
    514519     *
    515520     * @since 2.5.0
     
    517522     *
    518523     * @param string $dir The new current directory.
    519      * @return bool|string
     524     * @return bool True on success, false on failure.
    520525     */
    521526    public function chdir( $dir ) {
     
    524529
    525530    /**
    526      * Change the file group.
    527      *
    528      * @since 2.5.0
    529      * @abstract
    530      *
    531      * @param string $file      Path to the file.
    532      * @param mixed  $group     A group name or number.
    533      * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
    534      * @return bool|string
     531     * Changes the file group.
     532     *
     533     * @since 2.5.0
     534     * @abstract
     535     *
     536     * @param string     $file      Path to the file.
     537     * @param string|int $group     A group name or number.
     538     * @param bool       $recursive Optional. If set to true, changes file group recursively.
     539     *                              Default false.
     540     * @return bool True on success, false on failure.
    535541     */
    536542    public function chgrp( $file, $group, $recursive = false ) {
     
    539545
    540546    /**
    541      * Change filesystem permissions.
    542      *
    543      * @since 2.5.0
    544      * @abstract
    545      *
    546      * @param string $file      Path to the file.
    547      * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
    548      * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
    549      * @return bool|string
     547     * Changes filesystem permissions.
     548     *
     549     * @since 2.5.0
     550     * @abstract
     551     *
     552     * @param string    $file      Path to the file.
     553     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
     554     *                             0755 for directories. Default false.
     555     * @param bool      $recursive Optional. If set to true, changes file group recursively.
     556     *                             Default false.
     557     * @return bool True on success, false on failure.
    550558     */
    551559    public function chmod( $file, $mode = false, $recursive = false ) {
     
    554562
    555563    /**
    556      * Get the file owner.
     564     * Gets the file owner.
    557565     *
    558566     * @since 2.5.0
     
    560568     *
    561569     * @param string $file Path to the file.
    562      * @return string|bool Username of the user or false on error.
     570     * @return string|false Username of the owner on success, false on failure.
    563571     */
    564572    public function owner( $file ) {
     
    567575
    568576    /**
    569      * Get the file's group.
     577     * Gets the file's group.
    570578     *
    571579     * @since 2.5.0
     
    573581     *
    574582     * @param string $file Path to the file.
    575      * @return string|bool The group or false on error.
     583     * @return string|false The group on success, false on failure.
    576584     */
    577585    public function group( $file ) {
     
    580588
    581589    /**
    582      * Copy a file.
     590     * Copies a file.
     591     *
     592     * @since 2.5.0
     593     * @abstract
     594     *
     595     * @param string    $source      Path to the source file.
     596     * @param string    $destination Path to the destination file.
     597     * @param bool      $overwrite   Optional. Whether to overwrite the destination file if it exists.
     598     *                               Default false.
     599     * @param int|false $mode        Optional. The permissions as octal number, usually 0644 for files,
     600     *                               0755 for dirs. Default false.
     601     * @return bool True on success, false on failure.
     602     */
     603    public function copy( $source, $destination, $overwrite = false, $mode = false ) {
     604        return false;
     605    }
     606
     607    /**
     608     * Moves a file.
    583609     *
    584610     * @since 2.5.0
     
    589615     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
    590616     *                            Default false.
    591      * @param int    $mode        Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
    592      *                            Default false.
    593      * @return bool True if file copied successfully, False otherwise.
    594      */
    595     public function copy( $source, $destination, $overwrite = false, $mode = false ) {
    596         return false;
    597     }
    598 
    599     /**
    600      * Move a file.
    601      *
    602      * @since 2.5.0
    603      * @abstract
    604      *
    605      * @param string $source      Path to the source file.
    606      * @param string $destination Path to the destination file.
    607      * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
    608      *                            Default false.
    609      * @return bool True if file copied successfully, False otherwise.
     617     * @return bool True on success, false on failure.
    610618     */
    611619    public function move( $source, $destination, $overwrite = false ) {
     
    614622
    615623    /**
    616      * Delete a file or directory.
    617      *
    618      * @since 2.5.0
    619      * @abstract
    620      *
    621      * @param string $file      Path to the file.
    622      * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
    623      *                          Default false.
    624      * @param bool  $type      Type of resource. 'f' for file, 'd' for directory.
    625      *                          Default false.
    626      * @return bool True if the file or directory was deleted, false on failure.
     624     * Deletes a file or directory.
     625     *
     626     * @since 2.5.0
     627     * @abstract
     628     *
     629     * @param string       $file      Path to the file or directory.
     630     * @param bool         $recursive Optional. If set to true, changes file group recursively.
     631     *                                Default false.
     632     * @param string|false $type      Type of resource. 'f' for file, 'd' for directory.
     633     *                                Default false.
     634     * @return bool True on success, false on failure.
    627635     */
    628636    public function delete( $file, $recursive = false, $type = false ) {
     
    631639
    632640    /**
    633      * Check if a file or directory exists.
    634      *
    635      * @since 2.5.0
    636      * @abstract
    637      *
    638      * @param string $file Path to file/directory.
     641     * Checks if a file or directory exists.
     642     *
     643     * @since 2.5.0
     644     * @abstract
     645     *
     646     * @param string $file Path to file or directory.
    639647     * @return bool Whether $file exists or not.
    640648     */
     
    644652
    645653    /**
    646      * Check if resource is a file.
     654     * Checks if resource is a file.
    647655     *
    648656     * @since 2.5.0
     
    657665
    658666    /**
    659      * Check if resource is a directory.
     667     * Checks if resource is a directory.
    660668     *
    661669     * @since 2.5.0
     
    670678
    671679    /**
    672      * Check if a file is readable.
     680     * Checks if a file is readable.
    673681     *
    674682     * @since 2.5.0
     
    683691
    684692    /**
    685      * Check if a file or directory is writable.
     693     * Checks if a file or directory is writable.
     694     *
     695     * @since 2.5.0
     696     * @abstract
     697     *
     698     * @param string $file Path to file or directory.
     699     * @return bool Whether $file is writable.
     700     */
     701    public function is_writable( $file ) {
     702        return false;
     703    }
     704
     705    /**
     706     * Gets the file's last access time.
    686707     *
    687708     * @since 2.5.0
     
    689710     *
    690711     * @param string $file Path to file.
    691      * @return bool Whether $file is writable.
    692      */
    693     public function is_writable( $file ) {
    694         return false;
    695     }
    696 
    697     /**
    698      * Gets the file's last access time.
     712     * @return int|false Unix timestamp representing last access time, false on failure.
     713     */
     714    public function atime( $file ) {
     715        return false;
     716    }
     717
     718    /**
     719     * Gets the file modification time.
    699720     *
    700721     * @since 2.5.0
     
    702723     *
    703724     * @param string $file Path to file.
    704      * @return int|bool Unix timestamp representing last access time.
    705      */
    706     public function atime( $file ) {
    707         return false;
    708     }
    709 
    710     /**
    711      * Gets the file modification time.
     725     * @return int|false Unix timestamp representing modification time, false on failure.
     726     */
     727    public function mtime( $file ) {
     728        return false;
     729    }
     730
     731    /**
     732     * Gets the file size (in bytes).
    712733     *
    713734     * @since 2.5.0
     
    715736     *
    716737     * @param string $file Path to file.
    717      * @return int|bool Unix timestamp representing modification time.
    718      */
    719     public function mtime( $file ) {
    720         return false;
    721     }
    722 
    723     /**
    724      * Gets the file size (in bytes).
    725      *
    726      * @since 2.5.0
    727      * @abstract
    728      *
    729      * @param string $file Path to file.
    730      * @return int|bool Size of the file in bytes.
     738     * @return int|false Size of the file in bytes on success, false on failure.
    731739     */
    732740    public function size( $file ) {
     
    735743
    736744    /**
    737      * Set the access and modification times of a file.
     745     * Sets the access and modification times of a file.
    738746     *
    739747     * Note: If $file doesn't exist, it will be created.
     
    747755     * @param int    $atime Optional. Access time to set for file.
    748756     *                      Default 0.
    749      * @return bool Whether operation was successful or not.
     757     * @return bool True on success, false on failure.
    750758     */
    751759    public function touch( $file, $time = 0, $atime = 0 ) {
     
    754762
    755763    /**
    756      * Create a directory.
    757      *
    758      * @since 2.5.0
    759      * @abstract
    760      *
    761      * @param string $path  Path for new directory.
    762      * @param mixed  $chmod Optional. The permissions as octal number, (or False to skip chmod)
    763      *                      Default false.
    764      * @param mixed  $chown Optional. A user name or number (or False to skip chown)
    765      *                      Default false.
    766      * @param mixed  $chgrp Optional. A group name or number (or False to skip chgrp).
    767      *                      Default false.
    768      * @return bool False if directory cannot be created, true otherwise.
     764     * Creates a directory.
     765     *
     766     * @since 2.5.0
     767     * @abstract
     768     *
     769     * @param string     $path  Path for new directory.
     770     * @param int|false  $chmod Optional. The permissions as octal number (or false to skip chmod).
     771     *                          Default false.
     772     * @param string|int $chown Optional. A user name or number (or false to skip chown).
     773     *                          Default false.
     774     * @param string|int $chgrp Optional. A group name or number (or false to skip chgrp).
     775     *                          Default false.
     776     * @return bool True on success, false on failure.
    769777     */
    770778    public function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     
    773781
    774782    /**
    775      * Delete a directory.
     783     * Deletes a directory.
    776784     *
    777785     * @since 2.5.0
     
    781789     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
    782790     *                          Default false.
    783      * @return bool Whether directory is deleted successfully or not.
     791     * @return bool True on success, false on failure.
    784792     */
    785793    public function rmdir( $path, $recursive = false ) {
     
    788796
    789797    /**
    790      * Get details for files in a directory or a specific file.
     798     * Gets details for files in a directory or a specific file.
    791799     *
    792800     * @since 2.5.0
     
    798806     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
    799807     *                               Default false.
    800      * @return array|bool {
     808     * @return array|false {
    801809     *     Array of files. False if unable to list directory contents.
    802810     *
    803      *     @type string $name        Name of the file/directory.
     811     *     @type string $name        Name of the file or directory.
    804812     *     @type string $perms       *nix representation of permissions.
    805813     *     @type int    $permsn      Octal representation of permissions.
  • trunk/src/wp-admin/includes/class-wp-filesystem-direct.php

    r42343 r45226  
    1717
    1818    /**
    19      * constructor
    20      *
    21      * @param mixed $arg ignored argument
     19     * Constructor.
     20     *
     21     * @since 2.5.0
     22     *
     23     * @param mixed $arg Not used.
    2224     */
    2325    public function __construct( $arg ) {
     
    2729
    2830    /**
    29      * Reads entire file into a string
     31     * Reads entire file into a string.
     32     *
     33     * @since 2.5.0
    3034     *
    3135     * @param string $file Name of the file to read.
    32      * @return string|bool The function returns the read data or false on failure.
     36     * @return string|false Read data on success, false on failure.
    3337     */
    3438    public function get_contents( $file ) {
     
    3741
    3842    /**
    39      * Reads entire file into an array
     43     * Reads entire file into an array.
     44     *
     45     * @since 2.5.0
    4046     *
    4147     * @param string $file Path to the file.
    42      * @return array|bool the file contents in an array or false on failure.
     48     * @return array|false File contents in an array on success, false on failure.
    4349     */
    4450    public function get_contents_array( $file ) {
     
    4753
    4854    /**
    49      * Write a string to a file
    50      *
    51      * @param string $file     Remote path to the file where to write the data.
    52      * @param string $contents The data to write.
    53      * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
    54      *                         Default false.
    55      * @return bool False upon failure, true otherwise.
     55     * Writes a string to a file.
     56     *
     57     * @since 2.5.0
     58     *
     59     * @param string    $file     Remote path to the file where to write the data.
     60     * @param string    $contents The data to write.
     61     * @param int|false $mode     Optional. The file permissions as octal number, usually 0644.
     62     *                            Default false.
     63     * @return bool True on success, false on failure.
    5664     */
    5765    public function put_contents( $file, $contents, $mode = false ) {
     
    8189
    8290    /**
    83      * Gets the current working directory
    84      *
    85      * @return string|bool the current working directory on success, or false on failure.
     91     * Gets the current working directory.
     92     *
     93     * @since 2.5.0
     94     *
     95     * @return string|false The current working directory on success, false on failure.
    8696     */
    8797    public function cwd() {
     
    90100
    91101    /**
    92      * Change directory
     102     * Changes current directory.
     103     *
     104     * @since 2.5.0
    93105     *
    94106     * @param string $dir The new current directory.
    95      * @return bool Returns true on success or false on failure.
     107     * @return bool True on success, false on failure.
    96108     */
    97109    public function chdir( $dir ) {
     
    100112
    101113    /**
    102      * Changes file group
    103      *
    104      * @param string $file      Path to the file.
    105      * @param mixed  $group     A group name or number.
    106      * @param bool   $recursive Optional. If set True changes file group recursively. Default false.
    107      * @return bool Returns true on success or false on failure.
     114     * Changes the file group.
     115     *
     116     * @since 2.5.0
     117     *
     118     * @param string     $file      Path to the file.
     119     * @param string|int $group     A group name or number.
     120     * @param bool       $recursive Optional. If set to true, changes file group recursively.
     121     *                              Default false.
     122     * @return bool True on success, false on failure.
    108123     */
    109124    public function chgrp( $file, $group, $recursive = false ) {
     
    128143
    129144    /**
    130      * Changes filesystem permissions
    131      *
    132      * @param string $file      Path to the file.
    133      * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files,
    134      *                          0755 for dirs. Default false.
    135      * @param bool   $recursive Optional. If set True changes file group recursively. Default false.
    136      * @return bool Returns true on success or false on failure.
     145     * Changes filesystem permissions.
     146     *
     147     * @since 2.5.0
     148     *
     149     * @param string    $file      Path to the file.
     150     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
     151     *                             0755 for directories. Default false.
     152     * @param bool      $recursive Optional. If set to true, changes file group recursively.
     153     *                             Default false.
     154     * @return bool True on success, false on failure.
    137155     */
    138156    public function chmod( $file, $mode = false, $recursive = false ) {
     
    161179
    162180    /**
    163      * Changes file owner
    164      *
    165      * @param string $file      Path to the file.
    166      * @param mixed  $owner     A user name or number.
    167      * @param bool   $recursive Optional. If set True changes file owner recursively.
    168      *                          Default false.
    169      * @return bool Returns true on success or false on failure.
     181     * Changes the owner of a file or directory.
     182     *
     183     * @since 2.5.0
     184     *
     185     * @param string     $file      Path to the file or directory.
     186     * @param string|int $owner     A user name or number.
     187     * @param bool       $recursive Optional. If set to true, changes file owner recursively.
     188     *                              Default false.
     189     * @return bool True on success, false on failure.
    170190     */
    171191    public function chown( $file, $owner, $recursive = false ) {
     
    188208
    189209    /**
    190      * Gets file owner
     210     * Gets the file owner.
     211     *
     212     * @since 2.5.0
    191213     *
    192214     * @param string $file Path to the file.
    193      * @return string|bool Username of the user or false on error.
     215     * @return string|false Username of the owner on success, false on failure.
    194216     */
    195217    public function owner( $file ) {
     
    206228
    207229    /**
    208      * Gets file permissions
     230     * Gets the permissions of the specified file or filepath in their octal format.
    209231     *
    210232     * FIXME does not handle errors in fileperms()
    211233     *
     234     * @since 2.5.0
     235     *
    212236     * @param string $file Path to the file.
    213      * @return string Mode of the file (last 3 digits).
     237     * @return string Mode of the file (the last 3 digits).
    214238     */
    215239    public function getchmod( $file ) {
     
    218242
    219243    /**
    220      * @param string $file
    221      * @return string|false
     244     * Gets the file's group.
     245     *
     246     * @since 2.5.0
     247     *
     248     * @param string $file Path to the file.
     249     * @return string|false The group on success, false on failure.
    222250     */
    223251    public function group( $file ) {
     
    234262
    235263    /**
    236      * @param string $source
    237      * @param string $destination
    238      * @param bool   $overwrite
    239      * @param int    $mode
    240      * @return bool
     264     * Copies a file.
     265     *
     266     * @since 2.5.0
     267     *
     268     * @param string    $source      Path to the source file.
     269     * @param string    $destination Path to the destination file.
     270     * @param bool      $overwrite   Optional. Whether to overwrite the destination file if it exists.
     271     *                               Default false.
     272     * @param int|false $mode        Optional. The permissions as octal number, usually 0644 for files,
     273     *                               0755 for dirs. Default false.
     274     * @return bool True on success, false on failure.
    241275     */
    242276    public function copy( $source, $destination, $overwrite = false, $mode = false ) {
     
    253287
    254288    /**
    255      * @param string $source
    256      * @param string $destination
    257      * @param bool $overwrite
    258      * @return bool
     289     * Moves a file.
     290     *
     291     * @since 2.5.0
     292     *
     293     * @param string $source      Path to the source file.
     294     * @param string $destination Path to the destination file.
     295     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
     296     *                            Default false.
     297     * @return bool True on success, false on failure.
    259298     */
    260299    public function move( $source, $destination, $overwrite = false ) {
     
    277316
    278317    /**
    279      * @param string $file
    280      * @param bool $recursive
    281      * @param string $type
    282      * @return bool
     318     * Deletes a file or directory.
     319     *
     320     * @since 2.5.0
     321     *
     322     * @param string       $file      Path to the file or directory.
     323     * @param bool         $recursive Optional. If set to true, changes file group recursively.
     324     *                                Default false.
     325     * @param string|false $type      Type of resource. 'f' for file, 'd' for directory.
     326     *                                Default false.
     327     * @return bool True on success, false on failure.
    283328     */
    284329    public function delete( $file, $recursive = false, $type = false ) {
     
    314359        return $retval;
    315360    }
    316     /**
    317      * @param string $file
    318      * @return bool
     361
     362    /**
     363     * Checks if a file or directory exists.
     364     *
     365     * @since 2.5.0
     366     *
     367     * @param string $file Path to file or directory.
     368     * @return bool Whether $file exists or not.
    319369     */
    320370    public function exists( $file ) {
    321371        return @file_exists( $file );
    322372    }
    323     /**
    324      * @param string $file
    325      * @return bool
     373
     374    /**
     375     * Checks if resource is a file.
     376     *
     377     * @since 2.5.0
     378     *
     379     * @param string $file File path.
     380     * @return bool Whether $file is a file.
    326381     */
    327382    public function is_file( $file ) {
    328383        return @is_file( $file );
    329384    }
    330     /**
    331      * @param string $path
    332      * @return bool
     385
     386    /**
     387     * Checks if resource is a directory.
     388     *
     389     * @since 2.5.0
     390     *
     391     * @param string $path Directory path.
     392     * @return bool Whether $path is a directory.
    333393     */
    334394    public function is_dir( $path ) {
     
    337397
    338398    /**
    339      * @param string $file
    340      * @return bool
     399     * Checks if a file is readable.
     400     *
     401     * @since 2.5.0
     402     *
     403     * @param string $file Path to file.
     404     * @return bool Whether $file is readable.
    341405     */
    342406    public function is_readable( $file ) {
     
    345409
    346410    /**
    347      * @param string $file
    348      * @return bool
     411     * Checks if a file or directory is writable.
     412     *
     413     * @since 2.5.0
     414     *
     415     * @param string $file Path to file or directory.
     416     * @return bool Whether $file is writable.
    349417     */
    350418    public function is_writable( $file ) {
     
    353421
    354422    /**
    355      * @param string $file
    356      * @return int
     423     * Gets the file's last access time.
     424     *
     425     * @since 2.5.0
     426     *
     427     * @param string $file Path to file.
     428     * @return int|false Unix timestamp representing last access time, false on failure.
    357429     */
    358430    public function atime( $file ) {
     
    361433
    362434    /**
    363      * @param string $file
    364      * @return int
     435     * Gets the file modification time.
     436     *
     437     * @since 2.5.0
     438     *
     439     * @param string $file Path to file.
     440     * @return int|false Unix timestamp representing modification time, false on failure.
    365441     */
    366442    public function mtime( $file ) {
     
    369445
    370446    /**
    371      * @param string $file
    372      * @return int
     447     * Gets the file size (in bytes).
     448     *
     449     * @since 2.5.0
     450     *
     451     * @param string $file Path to file.
     452     * @return int|false Size of the file in bytes on success, false on failure.
    373453     */
    374454    public function size( $file ) {
     
    377457
    378458    /**
    379      * @param string $file
    380      * @param int $time
    381      * @param int $atime
    382      * @return bool
     459     * Sets the access and modification times of a file.
     460     *
     461     * Note: If $file doesn't exist, it will be created.
     462     *
     463     * @since 2.5.0
     464     *
     465     * @param string $file  Path to file.
     466     * @param int    $time  Optional. Modified time to set for file.
     467     *                      Default 0.
     468     * @param int    $atime Optional. Access time to set for file.
     469     *                      Default 0.
     470     * @return bool True on success, false on failure.
    383471     */
    384472    public function touch( $file, $time = 0, $atime = 0 ) {
     
    393481
    394482    /**
    395      * @param string $path
    396      * @param mixed  $chmod
    397      * @param mixed  $chown
    398      * @param mixed  $chgrp
    399      * @return bool
     483     * Creates a directory.
     484     *
     485     * @since 2.5.0
     486     *
     487     * @param string     $path  Path for new directory.
     488     * @param int|false  $chmod Optional. The permissions as octal number (or false to skip chmod).
     489     *                          Default false.
     490     * @param string|int $chown Optional. A user name or number (or false to skip chown).
     491     *                          Default false.
     492     * @param string|int $chgrp Optional. A group name or number (or false to skip chgrp).
     493     *                          Default false.
     494     * @return bool True on success, false on failure.
    400495     */
    401496    public function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     
    424519
    425520    /**
    426      * @param string $path
    427      * @param bool $recursive
    428      * @return bool
     521     * Deletes a directory.
     522     *
     523     * @since 2.5.0
     524     *
     525     * @param string $path      Path to directory.
     526     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
     527     *                          Default false.
     528     * @return bool True on success, false on failure.
    429529     */
    430530    public function rmdir( $path, $recursive = false ) {
     
    433533
    434534    /**
    435      * @param string $path
    436      * @param bool $include_hidden
    437      * @param bool $recursive
    438      * @return bool|array
     535     * Gets details for files in a directory or a specific file.
     536     *
     537     * @since 2.5.0
     538     *
     539     * @param string $path           Path to directory or file.
     540     * @param bool   $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
     541     *                               Default true.
     542     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
     543     *                               Default false.
     544     * @return array|false {
     545     *     Array of files. False if unable to list directory contents.
     546     *
     547     *     @type string $name        Name of the file or directory.
     548     *     @type string $perms       *nix representation of permissions.
     549     *     @type int    $permsn      Octal representation of permissions.
     550     *     @type string $owner       Owner name or ID.
     551     *     @type int    $size        Size of file in bytes.
     552     *     @type int    $lastmodunix Last modified unix timestamp.
     553     *     @type mixed  $lastmod     Last modified month (3 letter) and day (without leading 0).
     554     *     @type int    $time        Last modified time.
     555     *     @type string $type        Type of resource. 'f' for file, 'd' for directory.
     556     *     @type mixed  $files       If a directory and $recursive is true, contains another array of files.
     557     * }
    439558     */
    440559    public function dirlist( $path, $include_hidden = true, $recursive = false ) {
  • trunk/src/wp-admin/includes/class-wp-filesystem-ftpext.php

    r42343 r45226  
    1515 */
    1616class WP_Filesystem_FTPext extends WP_Filesystem_Base {
     17
     18    /**
     19     * @since 2.5.0
     20     * @var resource
     21     */
    1722    public $link;
    1823
    1924    /**
     25     * Constructor.
     26     *
     27     * @since 2.5.0
     28     *
    2029     * @param array $opt
    2130     */
     
    6877
    6978    /**
    70      * @return bool
     79     * Connects filesystem.
     80     *
     81     * @since 2.5.0
     82     *
     83     * @return bool True on success, false on failure.
    7184     */
    7285    public function connect() {
     
    111124
    112125    /**
    113      * Retrieves the file contents.
    114      *
    115      * @since 2.5.0
    116      *
    117      * @param string $file Filename.
    118      * @return string|false File contents on success, false if no temp file could be opened,
     126     * Reads entire file into a string.
     127     *
     128     * @since 2.5.0
     129     *
     130     * @param string $file Name of the file to read.
     131     * @return string|false Read data on success, false if no temporary file could be opened,
    119132     *                      or if the file couldn't be retrieved.
    120133     */
     
    138151
    139152        while ( ! feof( $temp ) ) {
    140             $contents .= fread( $temp, 8192 );
     153            $contents .= fread( $temp, 8 * KB_IN_BYTES );
    141154        }
    142155
     
    147160
    148161    /**
    149      * @param string $file
    150      * @return array
     162     * Reads entire file into an array.
     163     *
     164     * @since 2.5.0
     165     *
     166     * @param string $file Path to the file.
     167     * @return array|false File contents in an array on success, false on failure.
    151168     */
    152169    public function get_contents_array( $file ) {
     
    155172
    156173    /**
    157      * @param string $file
    158      * @param string $contents
    159      * @param bool|int $mode
    160      * @return bool
     174     * Writes a string to a file.
     175     *
     176     * @since 2.5.0
     177     *
     178     * @param string    $file     Remote path to the file where to write the data.
     179     * @param string    $contents The data to write.
     180     * @param int|false $mode     Optional. The file permissions as octal number, usually 0644.
     181     *                            Default false.
     182     * @return bool True on success, false on failure.
    161183     */
    162184    public function put_contents( $file, $contents, $mode = false ) {
     
    195217
    196218    /**
    197      * @return string
     219     * Gets the current working directory.
     220     *
     221     * @since 2.5.0
     222     *
     223     * @return string|false The current working directory on success, false on failure.
    198224     */
    199225    public function cwd() {
     
    206232
    207233    /**
    208      * @param string $dir
    209      * @return bool
     234     * Changes current directory.
     235     *
     236     * @since 2.5.0
     237     *
     238     * @param string $dir The new current directory.
     239     * @return bool True on success, false on failure.
    210240     */
    211241    public function chdir( $dir ) {
     
    214244
    215245    /**
    216      * @param string $file
    217      * @param int $mode
    218      * @param bool $recursive
    219      * @return bool
     246     * Changes filesystem permissions.
     247     *
     248     * @since 2.5.0
     249     *
     250     * @param string    $file      Path to the file.
     251     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
     252     *                             0755 for directories. Default false.
     253     * @param bool      $recursive Optional. If set to true, changes file group recursively.
     254     *                             Default false.
     255     * @return bool True on success, false on failure.
    220256     */
    221257    public function chmod( $file, $mode = false, $recursive = false ) {
     
    246282
    247283    /**
    248      * @param string $file
    249      * @return string
     284     * Gets the file owner.
     285     *
     286     * @since 2.5.0
     287     *
     288     * @param string $file Path to the file.
     289     * @return string|false Username of the owner on success, false on failure.
    250290     */
    251291    public function owner( $file ) {
     
    253293        return $dir[ $file ]['owner'];
    254294    }
    255     /**
    256      * @param string $file
    257      * @return string
     295
     296    /**
     297     * Gets the permissions of the specified file or filepath in their octal format.
     298     *
     299     * @since 2.5.0
     300     *
     301     * @param string $file Path to the file.
     302     * @return string Mode of the file (the last 3 digits).
    258303     */
    259304    public function getchmod( $file ) {
     
    263308
    264309    /**
    265      * @param string $file
    266      * @return string
     310     * Gets the file's group.
     311     *
     312     * @since 2.5.0
     313     *
     314     * @param string $file Path to the file.
     315     * @return string|false The group on success, false on failure.
    267316     */
    268317    public function group( $file ) {
     
    272321
    273322    /**
    274      * @param string $source
    275      * @param string $destination
    276      * @param bool   $overwrite
    277      * @param string|bool $mode
    278      * @return bool
     323     * Copies a file.
     324     *
     325     * @since 2.5.0
     326     *
     327     * @param string    $source      Path to the source file.
     328     * @param string    $destination Path to the destination file.
     329     * @param bool      $overwrite   Optional. Whether to overwrite the destination file if it exists.
     330     *                               Default false.
     331     * @param int|false $mode        Optional. The permissions as octal number, usually 0644 for files,
     332     *                               0755 for dirs. Default false.
     333     * @return bool True on success, false on failure.
    279334     */
    280335    public function copy( $source, $destination, $overwrite = false, $mode = false ) {
     
    290345
    291346    /**
    292      * @param string $source
    293      * @param string $destination
    294      * @param bool $overwrite
    295      * @return bool
     347     * Moves a file.
     348     *
     349     * @since 2.5.0
     350     *
     351     * @param string $source      Path to the source file.
     352     * @param string $destination Path to the destination file.
     353     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
     354     *                            Default false.
     355     * @return bool True on success, false on failure.
    296356     */
    297357    public function move( $source, $destination, $overwrite = false ) {
     
    300360
    301361    /**
    302      * @param string $file
    303      * @param bool $recursive
    304      * @param string $type
    305      * @return bool
     362     * Deletes a file or directory.
     363     *
     364     * @since 2.5.0
     365     *
     366     * @param string       $file      Path to the file or directory.
     367     * @param bool         $recursive Optional. If set to true, changes file group recursively.
     368     *                                Default false.
     369     * @param string|false $type      Type of resource. 'f' for file, 'd' for directory.
     370     *                                Default false.
     371     * @return bool True on success, false on failure.
    306372     */
    307373    public function delete( $file, $recursive = false, $type = false ) {
     
    326392
    327393    /**
    328      * @param string $file
    329      * @return bool
     394     * Checks if a file or directory exists.
     395     *
     396     * @since 2.5.0
     397     *
     398     * @param string $file Path to file or directory.
     399     * @return bool Whether $file exists or not.
    330400     */
    331401    public function exists( $file ) {
     
    340410
    341411    /**
    342      * @param string $file
    343      * @return bool
     412     * Checks if resource is a file.
     413     *
     414     * @since 2.5.0
     415     *
     416     * @param string $file File path.
     417     * @return bool Whether $file is a file.
    344418     */
    345419    public function is_file( $file ) {
     
    348422
    349423    /**
    350      * @param string $path
    351      * @return bool
     424     * Checks if resource is a directory.
     425     *
     426     * @since 2.5.0
     427     *
     428     * @param string $path Directory path.
     429     * @return bool Whether $path is a directory.
    352430     */
    353431    public function is_dir( $path ) {
     
    362440
    363441    /**
    364      * @param string $file
    365      * @return bool
     442     * Checks if a file is readable.
     443     *
     444     * @since 2.5.0
     445     *
     446     * @param string $file Path to file.
     447     * @return bool Whether $file is readable.
    366448     */
    367449    public function is_readable( $file ) {
     
    370452
    371453    /**
    372      * @param string $file
    373      * @return bool
     454     * Checks if a file or directory is writable.
     455     *
     456     * @since 2.5.0
     457     *
     458     * @param string $file Path to file or directory.
     459     * @return bool Whether $file is writable.
    374460     */
    375461    public function is_writable( $file ) {
     
    378464
    379465    /**
    380      * @param string $file
    381      * @return bool
     466     * Gets the file's last access time.
     467     *
     468     * @since 2.5.0
     469     *
     470     * @param string $file Path to file.
     471     * @return int|false Unix timestamp representing last access time, false on failure.
    382472     */
    383473    public function atime( $file ) {
     
    386476
    387477    /**
    388      * @param string $file
    389      * @return int
     478     * Gets the file modification time.
     479     *
     480     * @since 2.5.0
     481     *
     482     * @param string $file Path to file.
     483     * @return int|false Unix timestamp representing modification time, false on failure.
    390484     */
    391485    public function mtime( $file ) {
     
    394488
    395489    /**
    396      * @param string $file
    397      * @return int
     490     * Gets the file size (in bytes).
     491     *
     492     * @since 2.5.0
     493     *
     494     * @param string $file Path to file.
     495     * @return int|false Size of the file in bytes on success, false on failure.
    398496     */
    399497    public function size( $file ) {
     
    402500
    403501    /**
    404      * @param string $file
    405      * @return bool
     502     * Sets the access and modification times of a file.
     503     *
     504     * Note: If $file doesn't exist, it will be created.
     505     *
     506     * @since 2.5.0
     507     *
     508     * @param string $file  Path to file.
     509     * @param int    $time  Optional. Modified time to set for file.
     510     *                      Default 0.
     511     * @param int    $atime Optional. Access time to set for file.
     512     *                      Default 0.
     513     * @return bool True on success, false on failure.
    406514     */
    407515    public function touch( $file, $time = 0, $atime = 0 ) {
     
    410518
    411519    /**
    412      * @param string $path
    413      * @param mixed $chmod
    414      * @param mixed $chown
    415      * @param mixed $chgrp
    416      * @return bool
     520     * Creates a directory.
     521     *
     522     * @since 2.5.0
     523     *
     524     * @param string     $path  Path for new directory.
     525     * @param int|false  $chmod Optional. The permissions as octal number (or false to skip chmod).
     526     *                          Default false.
     527     * @param string|int $chown Optional. A user name or number (or false to skip chown).
     528     *                          Default false.
     529     * @param string|int $chgrp Optional. A group name or number (or false to skip chgrp).
     530     *                          Default false.
     531     * @return bool True on success, false on failure.
    417532     */
    418533    public function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     
    430545
    431546    /**
    432      * @param string $path
    433      * @param bool $recursive
    434      * @return bool
     547     * Deletes a directory.
     548     *
     549     * @since 2.5.0
     550     *
     551     * @param string $path      Path to directory.
     552     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
     553     *                          Default false.
     554     * @return bool True on success, false on failure.
    435555     */
    436556    public function rmdir( $path, $recursive = false ) {
     
    524644
    525645    /**
    526      * @param string $path
    527      * @param bool $include_hidden
    528      * @param bool $recursive
    529      * @return bool|array
     646     * Gets details for files in a directory or a specific file.
     647     *
     648     * @since 2.5.0
     649     *
     650     * @param string $path           Path to directory or file.
     651     * @param bool   $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
     652     *                               Default true.
     653     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
     654     *                               Default false.
     655     * @return array|false {
     656     *     Array of files. False if unable to list directory contents.
     657     *
     658     *     @type string $name        Name of the file or directory.
     659     *     @type string $perms       *nix representation of permissions.
     660     *     @type int    $permsn      Octal representation of permissions.
     661     *     @type string $owner       Owner name or ID.
     662     *     @type int    $size        Size of file in bytes.
     663     *     @type int    $lastmodunix Last modified unix timestamp.
     664     *     @type mixed  $lastmod     Last modified month (3 letter) and day (without leading 0).
     665     *     @type int    $time        Last modified time.
     666     *     @type string $type        Type of resource. 'f' for file, 'd' for directory.
     667     *     @type mixed  $files       If a directory and $recursive is true, contains another array of files.
     668     * }
    530669     */
    531670    public function dirlist( $path = '.', $include_hidden = true, $recursive = false ) {
     
    538677
    539678        $pwd = @ftp_pwd( $this->link );
    540         if ( ! @ftp_chdir( $this->link, $path ) ) { // Cant change to folder = folder doesn't exist
     679        if ( ! @ftp_chdir( $this->link, $path ) ) { // Can't change to folder = folder doesn't exist.
    541680            return false;
    542681        }
     
    544683        @ftp_chdir( $this->link, $pwd );
    545684
    546         if ( empty( $list ) ) { // Empty array = non-existent folder (real folder will show . at least)
     685        if ( empty( $list ) ) { // Empty array = non-existent folder (real folder will show . at least).
    547686            return false;
    548687        }
     
    586725
    587726    /**
     727     * Destructor.
     728     *
     729     * @since 2.5.0
    588730     */
    589731    public function __destruct() {
  • trunk/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php

    r42343 r45226  
    1515 */
    1616class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
    17     /**
     17
     18    /**
     19     * @since 2.5.0
    1820     * @var ftp
    1921     */
     
    2123
    2224    /**
     25     * Constructor.
     26     *
     27     * @since 2.5.0
     28     *
    2329     * @param array $opt
    2430     */
     
    6066
    6167    /**
    62      * @return bool
     68     * Connects filesystem.
     69     *
     70     * @since 2.5.0
     71     *
     72     * @return bool True on success, false on failure.
    6373     */
    6474    public function connect() {
     
    112122
    113123    /**
    114      * Retrieves the file contents.
    115      *
    116      * @since 2.5.0
    117      *
    118      * @param string $file Filename.
    119      * @return string|false File contents on success, false if no temp file could be opened,
    120      *                      or if the file doesn't exist.
     124     * Reads entire file into a string.
     125     *
     126     * @since 2.5.0
     127     *
     128     * @param string $file Name of the file to read.
     129     * @return string|false Read data on success, false if no temporary file could be opened,
     130     *                      or if the file couldn't be retrieved.
    121131     */
    122132    public function get_contents( $file ) {
     
    149159
    150160        while ( ! feof( $temphandle ) ) {
    151             $contents .= fread( $temphandle, 8192 );
     161            $contents .= fread( $temphandle, 8 * KB_IN_BYTES );
    152162        }
    153163
     
    158168
    159169    /**
    160      * @param string $file
    161      * @return array
     170     * Reads entire file into an array.
     171     *
     172     * @since 2.5.0
     173     *
     174     * @param string $file Path to the file.
     175     * @return array|false File contents in an array on success, false on failure.
    162176     */
    163177    public function get_contents_array( $file ) {
     
    166180
    167181    /**
    168      * @param string $file
    169      * @param string $contents
    170      * @param int|bool $mode
    171      * @return bool
     182     * Writes a string to a file.
     183     *
     184     * @since 2.5.0
     185     *
     186     * @param string    $file     Remote path to the file where to write the data.
     187     * @param string    $contents The data to write.
     188     * @param int|false $mode     Optional. The file permissions as octal number, usually 0644.
     189     *                            Default false.
     190     * @return bool True on success, false on failure.
    172191     */
    173192    public function put_contents( $file, $contents, $mode = false ) {
     
    206225
    207226    /**
    208      * @return string
     227     * Gets the current working directory.
     228     *
     229     * @since 2.5.0
     230     *
     231     * @return string|false The current working directory on success, false on failure.
    209232     */
    210233    public function cwd() {
     
    217240
    218241    /**
    219      * @param string $file
    220      * @return bool
    221      */
    222     public function chdir( $file ) {
    223         return $this->ftp->chdir( $file );
    224     }
    225 
    226     /**
    227      * @param string $file
    228      * @param int|bool $mode
    229      * @param bool $recursive
    230      * @return bool
     242     * Changes current directory.
     243     *
     244     * @since 2.5.0
     245     *
     246     * @param string $dir The new current directory.
     247     * @return bool True on success, false on failure.
     248     */
     249    public function chdir( $dir ) {
     250        return $this->ftp->chdir( $dir );
     251    }
     252
     253    /**
     254     * Changes filesystem permissions.
     255     *
     256     * @since 2.5.0
     257     *
     258     * @param string    $file      Path to the file.
     259     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
     260     *                             0755 for directories. Default false.
     261     * @param bool      $recursive Optional. If set to true, changes file group recursively.
     262     *                             Default false.
     263     * @return bool True on success, false on failure.
    231264     */
    232265    public function chmod( $file, $mode = false, $recursive = false ) {
     
    254287
    255288    /**
    256      * @param string $file
    257      * @return string
     289     * Gets the file owner.
     290     *
     291     * @since 2.5.0
     292     *
     293     * @param string $file Path to the file.
     294     * @return string|false Username of the owner on success, false on failure.
    258295     */
    259296    public function owner( $file ) {
     
    263300
    264301    /**
    265      * @param string $file
    266      * @return string
     302     * Gets the permissions of the specified file or filepath in their octal format.
     303     *
     304     * @since 2.5.0
     305     *
     306     * @param string $file Path to the file.
     307     * @return string Mode of the file (the last 3 digits).
    267308     */
    268309    public function getchmod( $file ) {
     
    272313
    273314    /**
    274      * @param string $file
    275      * @return string
     315     * Gets the file's group.
     316     *
     317     * @since 2.5.0
     318     *
     319     * @param string $file Path to the file.
     320     * @return string|false The group on success, false on failure.
    276321     */
    277322    public function group( $file ) {
     
    281326
    282327    /**
    283      * @param string   $source
    284      * @param string   $destination
    285      * @param bool     $overwrite
    286      * @param int|bool $mode
    287      * @return bool
     328     * Copies a file.
     329     *
     330     * @since 2.5.0
     331     *
     332     * @param string    $source      Path to the source file.
     333     * @param string    $destination Path to the destination file.
     334     * @param bool      $overwrite   Optional. Whether to overwrite the destination file if it exists.
     335     *                               Default false.
     336     * @param int|false $mode        Optional. The permissions as octal number, usually 0644 for files,
     337     *                               0755 for dirs. Default false.
     338     * @return bool True on success, false on failure.
    288339     */
    289340    public function copy( $source, $destination, $overwrite = false, $mode = false ) {
     
    301352
    302353    /**
    303      * @param string $source
    304      * @param string $destination
    305      * @param bool   $overwrite
    306      * @return bool
     354     * Moves a file.
     355     *
     356     * @since 2.5.0
     357     *
     358     * @param string $source      Path to the source file.
     359     * @param string $destination Path to the destination file.
     360     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
     361     *                            Default false.
     362     * @return bool True on success, false on failure.
    307363     */
    308364    public function move( $source, $destination, $overwrite = false ) {
     
    311367
    312368    /**
    313      * @param string $file
    314      * @param bool   $recursive
    315      * @param string $type
    316      * @return bool
     369     * Deletes a file or directory.
     370     *
     371     * @since 2.5.0
     372     *
     373     * @param string       $file      Path to the file or directory.
     374     * @param bool         $recursive Optional. If set to true, changes file group recursively.
     375     *                                Default false.
     376     * @param string|false $type      Type of resource. 'f' for file, 'd' for directory.
     377     *                                Default false.
     378     * @return bool True on success, false on failure.
    317379     */
    318380    public function delete( $file, $recursive = false, $type = false ) {
     
    331393
    332394    /**
    333      * @param string $file
    334      * @return bool
     395     * Checks if a file or directory exists.
     396     *
     397     * @since 2.5.0
     398     *
     399     * @param string $file Path to file or directory.
     400     * @return bool Whether $file exists or not.
    335401     */
    336402    public function exists( $file ) {
     
    346412
    347413    /**
    348      * @param string $file
    349      * @return bool
     414     * Checks if resource is a file.
     415     *
     416     * @since 2.5.0
     417     *
     418     * @param string $file File path.
     419     * @return bool Whether $file is a file.
    350420     */
    351421    public function is_file( $file ) {
     
    360430
    361431    /**
    362      * @param string $path
    363      * @return bool
     432     * Checks if resource is a directory.
     433     *
     434     * @since 2.5.0
     435     *
     436     * @param string $path Directory path.
     437     * @return bool Whether $path is a directory.
    364438     */
    365439    public function is_dir( $path ) {
     
    373447
    374448    /**
    375      * @param string $file
    376      * @return bool
     449     * Checks if a file is readable.
     450     *
     451     * @since 2.5.0
     452     *
     453     * @param string $file Path to file.
     454     * @return bool Whether $file is readable.
    377455     */
    378456    public function is_readable( $file ) {
     
    381459
    382460    /**
    383      * @param string $file
    384      * @return bool
     461     * Checks if a file or directory is writable.
     462     *
     463     * @since 2.5.0
     464     *
     465     * @param string $file Path to file or directory.
     466     * @return bool Whether $file is writable.
    385467     */
    386468    public function is_writable( $file ) {
     
    389471
    390472    /**
    391      * @param string $file
    392      * @return bool
     473     * Gets the file's last access time.
     474     *
     475     * @since 2.5.0
     476     *
     477     * @param string $file Path to file.
     478     * @return int|false Unix timestamp representing last access time, false on failure.
    393479     */
    394480    public function atime( $file ) {
     
    397483
    398484    /**
    399      * @param string $file
    400      * @return int
     485     * Gets the file modification time.
     486     *
     487     * @since 2.5.0
     488     *
     489     * @param string $file Path to file.
     490     * @return int|false Unix timestamp representing modification time, false on failure.
    401491     */
    402492    public function mtime( $file ) {
     
    405495
    406496    /**
    407      * @param string $file
    408      * @return int
     497     * Gets the file size (in bytes).
     498     *
     499     * @since 2.5.0
     500     *
     501     * @param string $file Path to file.
     502     * @return int|false Size of the file in bytes on success, false on failure.
    409503     */
    410504    public function size( $file ) {
     
    413507
    414508    /**
    415      * @param string $file
    416      * @param int $time
    417      * @param int $atime
    418      * @return bool
     509     * Sets the access and modification times of a file.
     510     *
     511     * Note: If $file doesn't exist, it will be created.
     512     *
     513     * @since 2.5.0
     514     *
     515     * @param string $file  Path to file.
     516     * @param int    $time  Optional. Modified time to set for file.
     517     *                      Default 0.
     518     * @param int    $atime Optional. Access time to set for file.
     519     *                      Default 0.
     520     * @return bool True on success, false on failure.
    419521     */
    420522    public function touch( $file, $time = 0, $atime = 0 ) {
     
    423525
    424526    /**
    425      * @param string $path
    426      * @param mixed  $chmod
    427      * @param mixed  $chown
    428      * @param mixed  $chgrp
    429      * @return bool
     527     * Creates a directory.
     528     *
     529     * @since 2.5.0
     530     *
     531     * @param string     $path  Path for new directory.
     532     * @param int|false  $chmod Optional. The permissions as octal number (or false to skip chmod).
     533     *                          Default false.
     534     * @param string|int $chown Optional. A user name or number (or false to skip chown).
     535     *                          Default false.
     536     * @param string|int $chgrp Optional. A group name or number (or false to skip chgrp).
     537     *                          Default false.
     538     * @return bool True on success, false on failure.
    430539     */
    431540    public function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     
    446555
    447556    /**
    448      * @param string $path
    449      * @param bool $recursive
    450      * @return bool
     557     * Deletes a directory.
     558     *
     559     * @since 2.5.0
     560     *
     561     * @param string $path      Path to directory.
     562     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
     563     *                          Default false.
     564     * @return bool True on success, false on failure.
    451565     */
    452566    public function rmdir( $path, $recursive = false ) {
     
    455569
    456570    /**
    457      * @param string $path
    458      * @param bool   $include_hidden
    459      * @param bool   $recursive
    460      * @return bool|array
     571     * Gets details for files in a directory or a specific file.
     572     *
     573     * @since 2.5.0
     574     *
     575     * @param string $path           Path to directory or file.
     576     * @param bool   $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
     577     *                               Default true.
     578     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
     579     *                               Default false.
     580     * @return array|false {
     581     *     Array of files. False if unable to list directory contents.
     582     *
     583     *     @type string $name        Name of the file or directory.
     584     *     @type string $perms       *nix representation of permissions.
     585     *     @type int    $permsn      Octal representation of permissions.
     586     *     @type string $owner       Owner name or ID.
     587     *     @type int    $size        Size of file in bytes.
     588     *     @type int    $lastmodunix Last modified unix timestamp.
     589     *     @type mixed  $lastmod     Last modified month (3 letter) and day (without leading 0).
     590     *     @type int    $time        Last modified time.
     591     *     @type string $type        Type of resource. 'f' for file, 'd' for directory.
     592     *     @type mixed  $files       If a directory and $recursive is true, contains another array of files.
     593     * }
    461594     */
    462595    public function dirlist( $path = '.', $include_hidden = true, $recursive = false ) {
     
    518651
    519652    /**
     653     * Destructor.
     654     *
     655     * @since 2.5.0
    520656     */
    521657    public function __destruct() {
  • trunk/src/wp-admin/includes/class-wp-filesystem-ssh2.php

    r42343 r45226  
    3737
    3838    /**
     39     * @since 2.7.0
     40     * @var resource
    3941     */
    4042    public $link = false;
    4143
    4244    /**
     45     * @since 2.7.0
    4346     * @var resource
    4447     */
    4548    public $sftp_link;
     49
     50    /**
     51     * @since 2.7.0
     52     * @var bool
     53     */
    4654    public $keys = false;
    4755
    4856    /**
     57     * Constructor.
     58     *
     59     * @since 2.7.0
     60     *
    4961     * @param array $opt
    5062     */
     
    110122
    111123    /**
    112      * @return bool
     124     * Connects filesystem.
     125     *
     126     * @since 2.7.0
     127     *
     128     * @return bool True on success, false on failure.
    113129     */
    114130    public function connect() {
     
    194210
    195211    /**
     212     * @since 2.7.0
     213     *
    196214     * @param string $command
    197215     * @param bool $returnbool
     
    229247
    230248    /**
    231      * @param string $file
    232      * @return string|false
     249     * Reads entire file into a string.
     250     *
     251     * @since 2.7.0
     252     *
     253     * @param string $file Name of the file to read.
     254     * @return string|false Read data on success, false if no temporary file could be opened,
     255     *                      or if the file couldn't be retrieved.
    233256     */
    234257    public function get_contents( $file ) {
     
    237260
    238261    /**
    239      * @param string $file
    240      * @return array
     262     * Reads entire file into an array.
     263     *
     264     * @since 2.7.0
     265     *
     266     * @param string $file Path to the file.
     267     * @return array|false File contents in an array on success, false on failure.
    241268     */
    242269    public function get_contents_array( $file ) {
     
    245272
    246273    /**
    247      * @param string   $file
    248      * @param string   $contents
    249      * @param bool|int $mode
    250      * @return bool
     274     * Writes a string to a file.
     275     *
     276     * @since 2.7.0
     277     *
     278     * @param string    $file     Remote path to the file where to write the data.
     279     * @param string    $contents The data to write.
     280     * @param int|false $mode     Optional. The file permissions as octal number, usually 0644.
     281     *                            Default false.
     282     * @return bool True on success, false on failure.
    251283     */
    252284    public function put_contents( $file, $contents, $mode = false ) {
     
    263295
    264296    /**
    265      * @return bool
     297     * Gets the current working directory.
     298     *
     299     * @since 2.7.0
     300     *
     301     * @return string|false The current working directory on success, false on failure.
    266302     */
    267303    public function cwd() {
     
    274310
    275311    /**
    276      * @param string $dir
    277      * @return bool|string
     312     * Changes current directory.
     313     *
     314     * @since 2.7.0
     315     *
     316     * @param string $dir The new current directory.
     317     * @return bool True on success, false on failure.
    278318     */
    279319    public function chdir( $dir ) {
     
    282322
    283323    /**
    284      * @param string $file
    285      * @param string $group
    286      * @param bool   $recursive
    287      *
    288      * @return bool
     324     * Changes the file group.
     325     *
     326     * @since 2.7.0
     327     *
     328     * @param string     $file      Path to the file.
     329     * @param string|int $group     A group name or number.
     330     * @param bool       $recursive Optional. If set to true, changes file group recursively.
     331     *                              Default false.
     332     * @return bool True on success, false on failure.
    289333     */
    290334    public function chgrp( $file, $group, $recursive = false ) {
     
    299343
    300344    /**
    301      * @param string $file
    302      * @param int    $mode
    303      * @param bool   $recursive
    304      * @return bool|string
     345     * Changes filesystem permissions.
     346     *
     347     * @since 2.7.0
     348     *
     349     * @param string    $file      Path to the file.
     350     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
     351     *                             0755 for directories. Default false.
     352     * @param bool      $recursive Optional. If set to true, changes file group recursively.
     353     *                             Default false.
     354     * @return bool True on success, false on failure.
    305355     */
    306356    public function chmod( $file, $mode = false, $recursive = false ) {
     
    326376
    327377    /**
    328      * Change the ownership of a file / folder.
    329      *
    330      * @param string     $file      Path to the file.
     378     * Changes the owner of a file or directory.
     379     *
     380     * @since 2.7.0
     381     *
     382     * @param string     $file      Path to the file or directory.
    331383     * @param string|int $owner     A user name or number.
    332      * @param bool       $recursive Optional. If set True changes file owner recursivly. Default False.
    333      * @return bool True on success or false on failure.
     384     * @param bool       $recursive Optional. If set to true, changes file owner recursively.
     385     *                              Default false.
     386     * @return bool True on success, false on failure.
    334387     */
    335388    public function chown( $file, $owner, $recursive = false ) {
     
    344397
    345398    /**
    346      * @param string $file
    347      * @return string|false
     399     * Gets the file owner.
     400     *
     401     * @since 2.7.0
     402     *
     403     * @param string $file Path to the file.
     404     * @return string|false Username of the owner on success, false on failure.
    348405     */
    349406    public function owner( $file ) {
     
    360417
    361418    /**
    362      * @param string $file
    363      * @return string
     419     * Gets the permissions of the specified file or filepath in their octal format.
     420     *
     421     * @since 2.7.0
     422     *
     423     * @param string $file Path to the file.
     424     * @return string Mode of the file (the last 3 digits).
    364425     */
    365426    public function getchmod( $file ) {
     
    368429
    369430    /**
    370      * @param string $file
    371      * @return string|false
     431     * Gets the file's group.
     432     *
     433     * @since 2.7.0
     434     *
     435     * @param string $file Path to the file.
     436     * @return string|false The group on success, false on failure.
    372437     */
    373438    public function group( $file ) {
     
    384449
    385450    /**
    386      * @param string   $source
    387      * @param string   $destination
    388      * @param bool     $overwrite
    389      * @param int|bool $mode
    390      * @return bool
     451     * Copies a file.
     452     *
     453     * @since 2.7.0
     454     *
     455     * @param string    $source      Path to the source file.
     456     * @param string    $destination Path to the destination file.
     457     * @param bool      $overwrite   Optional. Whether to overwrite the destination file if it exists.
     458     *                               Default false.
     459     * @param int|false $mode        Optional. The permissions as octal number, usually 0644 for files,
     460     *                               0755 for dirs. Default false.
     461     * @return bool True on success, false on failure.
    391462     */
    392463    public function copy( $source, $destination, $overwrite = false, $mode = false ) {
     
    402473
    403474    /**
    404      * @param string $source
    405      * @param string $destination
    406      * @param bool   $overwrite
    407      * @return bool
     475     * Moves a file.
     476     *
     477     * @since 2.7.0
     478     *
     479     * @param string $source      Path to the source file.
     480     * @param string $destination Path to the destination file.
     481     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
     482     *                            Default false.
     483     * @return bool True on success, false on failure.
    408484     */
    409485    public function move( $source, $destination, $overwrite = false ) {
     
    412488
    413489    /**
    414      * @param string      $file
    415      * @param bool        $recursive
    416      * @param string|bool $type
    417      * @return bool
     490     * Deletes a file or directory.
     491     *
     492     * @since 2.7.0
     493     *
     494     * @param string       $file      Path to the file or directory.
     495     * @param bool         $recursive Optional. If set to true, changes file group recursively.
     496     *                                Default false.
     497     * @param string|false $type      Type of resource. 'f' for file, 'd' for directory.
     498     *                                Default false.
     499     * @return bool True on success, false on failure.
    418500     */
    419501    public function delete( $file, $recursive = false, $type = false ) {
     
    434516
    435517    /**
    436      * @param string $file
    437      * @return bool
     518     * Checks if a file or directory exists.
     519     *
     520     * @since 2.7.0
     521     *
     522     * @param string $file Path to file or directory.
     523     * @return bool Whether $file exists or not.
    438524     */
    439525    public function exists( $file ) {
     
    442528
    443529    /**
    444      * @param string $file
    445      * @return bool
     530     * Checks if resource is a file.
     531     *
     532     * @since 2.7.0
     533     *
     534     * @param string $file File path.
     535     * @return bool Whether $file is a file.
    446536     */
    447537    public function is_file( $file ) {
     
    450540
    451541    /**
    452      * @param string $path
    453      * @return bool
     542     * Checks if resource is a directory.
     543     *
     544     * @since 2.7.0
     545     *
     546     * @param string $path Directory path.
     547     * @return bool Whether $path is a directory.
    454548     */
    455549    public function is_dir( $path ) {
     
    458552
    459553    /**
    460      * @param string $file
    461      * @return bool
     554     * Checks if a file is readable.
     555     *
     556     * @since 2.7.0
     557     *
     558     * @param string $file Path to file.
     559     * @return bool Whether $file is readable.
    462560     */
    463561    public function is_readable( $file ) {
     
    466564
    467565    /**
    468      * @param string $file
    469      * @return bool
     566     * Checks if a file or directory is writable.
     567     *
     568     * @since 2.7.0
     569     *
     570     * @param string $file Path to file or directory.
     571     * @return bool Whether $file is writable.
    470572     */
    471573    public function is_writable( $file ) {
     
    475577
    476578    /**
    477      * @param string $file
    478      * @return int
     579     * Gets the file's last access time.
     580     *
     581     * @since 2.7.0
     582     *
     583     * @param string $file Path to file.
     584     * @return int|false Unix timestamp representing last access time, false on failure.
    479585     */
    480586    public function atime( $file ) {
     
    483589
    484590    /**
    485      * @param string $file
    486      * @return int
     591     * Gets the file modification time.
     592     *
     593     * @since 2.7.0
     594     *
     595     * @param string $file Path to file.
     596     * @return int|false Unix timestamp representing modification time, false on failure.
    487597     */
    488598    public function mtime( $file ) {
     
    491601
    492602    /**
    493      * @param string $file
    494      * @return int
     603     * Gets the file size (in bytes).
     604     *
     605     * @since 2.7.0
     606     *
     607     * @param string $file Path to file.
     608     * @return int|false Size of the file in bytes on success, false on failure.
    495609     */
    496610    public function size( $file ) {
     
    499613
    500614    /**
    501      * @param string $file
    502      * @param int    $time
    503      * @param int    $atime
     615     * Sets the access and modification times of a file.
     616     *
     617     * Note: Not implemented.
     618     *
     619     * @since 2.7.0
     620     *
     621     * @param string $file  Path to file.
     622     * @param int    $time  Optional. Modified time to set for file.
     623     *                      Default 0.
     624     * @param int    $atime Optional. Access time to set for file.
     625     *                      Default 0.
    504626     */
    505627    public function touch( $file, $time = 0, $atime = 0 ) {
    506         //Not implemented.
    507     }
    508 
    509     /**
    510      * @param string $path
    511      * @param mixed  $chmod
    512      * @param mixed  $chown
    513      * @param mixed  $chgrp
    514      * @return bool
     628        // Not implemented.
     629    }
     630
     631    /**
     632     * Creates a directory.
     633     *
     634     * @since 2.7.0
     635     *
     636     * @param string     $path  Path for new directory.
     637     * @param int|false  $chmod Optional. The permissions as octal number (or false to skip chmod).
     638     *                          Default false.
     639     * @param string|int $chown Optional. A user name or number (or false to skip chown).
     640     *                          Default false.
     641     * @param string|int $chgrp Optional. A group name or number (or false to skip chgrp).
     642     *                          Default false.
     643     * @return bool True on success, false on failure.
    515644     */
    516645    public function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     
    536665
    537666    /**
    538      * @param string $path
    539      * @param bool   $recursive
    540      * @return bool
     667     * Deletes a directory.
     668     *
     669     * @since 2.7.0
     670     *
     671     * @param string $path      Path to directory.
     672     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
     673     *                          Default false.
     674     * @return bool True on success, false on failure.
    541675     */
    542676    public function rmdir( $path, $recursive = false ) {
     
    545679
    546680    /**
    547      * @param string $path
    548      * @param bool   $include_hidden
    549      * @param bool   $recursive
    550      * @return bool|array
     681     * Gets details for files in a directory or a specific file.
     682     *
     683     * @since 2.7.0
     684     *
     685     * @param string $path           Path to directory or file.
     686     * @param bool   $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
     687     *                               Default true.
     688     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
     689     *                               Default false.
     690     * @return array|false {
     691     *     Array of files. False if unable to list directory contents.
     692     *
     693     *     @type string $name        Name of the file or directory.
     694     *     @type string $perms       *nix representation of permissions.
     695     *     @type int    $permsn      Octal representation of permissions.
     696     *     @type string $owner       Owner name or ID.
     697     *     @type int    $size        Size of file in bytes.
     698     *     @type int    $lastmodunix Last modified unix timestamp.
     699     *     @type mixed  $lastmod     Last modified month (3 letter) and day (without leading 0).
     700     *     @type int    $time        Last modified time.
     701     *     @type string $type        Type of resource. 'f' for file, 'd' for directory.
     702     *     @type mixed  $files       If a directory and $recursive is true, contains another array of files.
     703     * }
    551704     */
    552705    public function dirlist( $path, $include_hidden = true, $recursive = false ) {
Note: See TracChangeset for help on using the changeset viewer.