WordPress.org

Make WordPress Core


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

File:
1 edited

Legend:

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