WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
04/17/2019 04:12:27 AM (6 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-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() {
Note: See TracChangeset for help on using the changeset viewer.