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-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.