WordPress.org
Get WordPress

Make WordPress Core


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