WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
04/17/2019 04:12:27 AM (5 years 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.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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 ) {
Note: See TracChangeset for help on using the changeset viewer.