WordPress.org

Make WordPress Core


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

    r42343 r45226  
    88
    99/**
    10  * Base WordPress Filesystem class for which Filesystem implementations extend
     10 * Base WordPress Filesystem class which Filesystem implementations extend.
    1111 *
    1212 * @since 2.5.0
    1313 */
    1414class WP_Filesystem_Base {
     15
    1516    /**
    1617     * Whether to display debug data for the connection.
     
    4748
    4849    /**
    49      * Return the path on the remote filesystem of ABSPATH.
     50     * Returns the path on the remote filesystem of ABSPATH.
    5051     *
    5152     * @since 2.7.0
     
    6364
    6465    /**
    65      * Return the path on the remote filesystem of WP_CONTENT_DIR.
     66     * Returns the path on the remote filesystem of WP_CONTENT_DIR.
    6667     *
    6768     * @since 2.7.0
     
    7475
    7576    /**
    76      * Return the path on the remote filesystem of WP_PLUGIN_DIR.
     77     * Returns the path on the remote filesystem of WP_PLUGIN_DIR.
    7778     *
    7879     * @since 2.7.0
     
    8586
    8687    /**
    87      * Return the path on the remote filesystem of the Themes Directory.
     88     * Returns the path on the remote filesystem of the Themes Directory.
    8889     *
    8990     * @since 2.7.0
    9091     *
    91      * @param string $theme The Theme stylesheet or template for the directory.
     92     * @param string|false $theme Optional. The theme stylesheet or template for the directory.
     93     *                            Default false.
    9294     * @return string The location of the remote path.
    9395     */
     
    104106
    105107    /**
    106      * Return the path on the remote filesystem of WP_LANG_DIR.
     108     * Returns the path on the remote filesystem of WP_LANG_DIR.
    107109     *
    108110     * @since 3.2.0
     
    115117
    116118    /**
    117      * Locate a folder on the remote filesystem.
     119     * Locates a folder on the remote filesystem.
    118120     *
    119121     * @since 2.5.0
     
    137139
    138140    /**
    139      * Locate a folder on the remote filesystem.
     141     * Locates a folder on the remote filesystem.
    140142     *
    141143     * @since 2.5.0
     
    158160
    159161    /**
    160      * Locate a folder on the remote filesystem.
     162     * Locates a folder on the remote filesystem.
    161163     *
    162164     * Assumes that on Windows systems, Stripping off the Drive
    163      * letter is OK Sanitizes \\ to / in windows filepaths.
     165     * letter is OK Sanitizes \\ to / in Windows filepaths.
    164166     *
    165167     * @since 2.7.0
     
    230232
    231233    /**
    232      * Locate a folder on the remote filesystem.
     234     * Locates a folder on the remote filesystem.
    233235     *
    234236     * Expects Windows sanitized path.
     
    268270             * Working from /home/ to /user/ to /wordpress/ see if that file exists within
    269271             * the current folder, If it's found, change into it and follow through looking
    270              * for it. If it cant find WordPress down that route, it'll continue onto the next
     272             * for it. If it can't find WordPress down that route, it'll continue onto the next
    271273             * folder level, and see if that matches, and so on. If it reaches the end, and still
    272              * cant find it, it'll return false for the entire function.
     274             * can't find it, it'll return false for the entire function.
    273275             */
    274276            if ( isset( $files[ $key ] ) ) {
     
    312314
    313315    /**
    314      * Return the *nix-style file permissions for a file.
     316     * Returns the *nix-style file permissions for a file.
    315317     *
    316318     * From the PHP documentation page for fileperms().
     
    367369
    368370    /**
    369      * Gets the permissions of the specified file or filepath in their octal format
    370      *
    371      * @since 2.5.0
    372      * @param string $file
    373      * @return string the last 3 characters of the octal number
     371     * Gets the permissions of the specified file or filepath in their octal format.
     372     *
     373     * @since 2.5.0
     374     *
     375     * @param string $file Path to the file.
     376     * @return string Mode of the file (the last 3 digits).
    374377     */
    375378    public function getchmod( $file ) {
     
    378381
    379382    /**
    380      * Convert *nix-style file permissions to a octal number.
     383     * Converts *nix-style file permissions to a octal number.
    381384     *
    382385     * Converts '-rw-r--r--' to 0644
     
    418421
    419422    /**
    420      * Determine if the string provided contains binary characters.
     423     * Determines if the string provided contains binary characters.
    421424     *
    422425     * @since 2.7.0
    423426     *
    424427     * @param string $text String to test against.
    425      * @return bool true if string is binary, false otherwise.
     428     * @return bool True if string is binary, false otherwise.
    426429     */
    427430    public function is_binary( $text ) {
     
    430433
    431434    /**
    432      * Change the ownership of a file / folder.
     435     * Changes the owner of a file or directory.
    433436     *
    434437     * Default behavior is to do nothing, override this in your subclass, if desired.
     
    436439     * @since 2.5.0
    437440     *
    438      * @param string $file      Path to the file.
    439      * @param mixed  $owner     A user name or number.
    440      * @param bool   $recursive Optional. If set True changes file owner recursivly. Defaults to False.
    441      * @return bool Returns true on success or false on failure.
     441     * @param string     $file      Path to the file or directory.
     442     * @param string|int $owner     A user name or number.
     443     * @param bool       $recursive Optional. If set to true, changes file owner recursively.
     444     *                              Default false.
     445     * @return bool True on success, false on failure.
    442446     */
    443447    public function chown( $file, $owner, $recursive = false ) {
     
    446450
    447451    /**
    448      * Connect filesystem.
    449      *
    450      * @since 2.5.0
    451      * @abstract
    452      *
    453      * @return bool True on success or false on failure (always true for WP_Filesystem_Direct).
     452     * Connects filesystem.
     453     *
     454     * @since 2.5.0
     455     * @abstract
     456     *
     457     * @return bool True on success, false on failure (always true for WP_Filesystem_Direct).
    454458     */
    455459    public function connect() {
     
    458462
    459463    /**
    460      * Read entire file into a string.
     464     * Reads entire file into a string.
    461465     *
    462466     * @since 2.5.0
     
    464468     *
    465469     * @param string $file Name of the file to read.
    466      * @return mixed|bool Returns the read data or false on failure.
     470     * @return string|false Read data on success, false on failure.
    467471     */
    468472    public function get_contents( $file ) {
     
    471475
    472476    /**
    473      * Read entire file into an array.
     477     * Reads entire file into an array.
    474478     *
    475479     * @since 2.5.0
     
    477481     *
    478482     * @param string $file Path to the file.
    479      * @return array|bool the file contents in an array or false on failure.
     483     * @return array|false File contents in an array on success, false on failure.
    480484     */
    481485    public function get_contents_array( $file ) {
     
    484488
    485489    /**
    486      * Write a string to a file.
    487      *
    488      * @since 2.5.0
    489      * @abstract
    490      *
    491      * @param string $file     Remote path to the file where to write the data.
    492      * @param string $contents The data to write.
    493      * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
    494      * @return bool False on failure.
     490     * Writes a string to a file.
     491     *
     492     * @since 2.5.0
     493     * @abstract
     494     *
     495     * @param string    $file     Remote path to the file where to write the data.
     496     * @param string    $contents The data to write.
     497     * @param int|false $mode     Optional. The file permissions as octal number, usually 0644.
     498     *                            Default false.
     499     * @return bool True on success, false on failure.
    495500     */
    496501    public function put_contents( $file, $contents, $mode = false ) {
     
    499504
    500505    /**
    501      * Get the current working directory.
    502      *
    503      * @since 2.5.0
    504      * @abstract
    505      *
    506      * @return string|bool The current working directory on success, or false on failure.
     506     * Gets the current working directory.
     507     *
     508     * @since 2.5.0
     509     * @abstract
     510     *
     511     * @return string|false The current working directory on success, false on failure.
    507512     */
    508513    public function cwd() {
     
    511516
    512517    /**
    513      * Change current directory.
     518     * Changes current directory.
    514519     *
    515520     * @since 2.5.0
     
    517522     *
    518523     * @param string $dir The new current directory.
    519      * @return bool|string
     524     * @return bool True on success, false on failure.
    520525     */
    521526    public function chdir( $dir ) {
     
    524529
    525530    /**
    526      * Change the file group.
    527      *
    528      * @since 2.5.0
    529      * @abstract
    530      *
    531      * @param string $file      Path to the file.
    532      * @param mixed  $group     A group name or number.
    533      * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
    534      * @return bool|string
     531     * Changes the file group.
     532     *
     533     * @since 2.5.0
     534     * @abstract
     535     *
     536     * @param string     $file      Path to the file.
     537     * @param string|int $group     A group name or number.
     538     * @param bool       $recursive Optional. If set to true, changes file group recursively.
     539     *                              Default false.
     540     * @return bool True on success, false on failure.
    535541     */
    536542    public function chgrp( $file, $group, $recursive = false ) {
     
    539545
    540546    /**
    541      * Change filesystem permissions.
    542      *
    543      * @since 2.5.0
    544      * @abstract
    545      *
    546      * @param string $file      Path to the file.
    547      * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
    548      * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
    549      * @return bool|string
     547     * Changes filesystem permissions.
     548     *
     549     * @since 2.5.0
     550     * @abstract
     551     *
     552     * @param string    $file      Path to the file.
     553     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
     554     *                             0755 for directories. Default false.
     555     * @param bool      $recursive Optional. If set to true, changes file group recursively.
     556     *                             Default false.
     557     * @return bool True on success, false on failure.
    550558     */
    551559    public function chmod( $file, $mode = false, $recursive = false ) {
     
    554562
    555563    /**
    556      * Get the file owner.
     564     * Gets the file owner.
    557565     *
    558566     * @since 2.5.0
     
    560568     *
    561569     * @param string $file Path to the file.
    562      * @return string|bool Username of the user or false on error.
     570     * @return string|false Username of the owner on success, false on failure.
    563571     */
    564572    public function owner( $file ) {
     
    567575
    568576    /**
    569      * Get the file's group.
     577     * Gets the file's group.
    570578     *
    571579     * @since 2.5.0
     
    573581     *
    574582     * @param string $file Path to the file.
    575      * @return string|bool The group or false on error.
     583     * @return string|false The group on success, false on failure.
    576584     */
    577585    public function group( $file ) {
     
    580588
    581589    /**
    582      * Copy a file.
     590     * Copies a file.
     591     *
     592     * @since 2.5.0
     593     * @abstract
     594     *
     595     * @param string    $source      Path to the source file.
     596     * @param string    $destination Path to the destination file.
     597     * @param bool      $overwrite   Optional. Whether to overwrite the destination file if it exists.
     598     *                               Default false.
     599     * @param int|false $mode        Optional. The permissions as octal number, usually 0644 for files,
     600     *                               0755 for dirs. Default false.
     601     * @return bool True on success, false on failure.
     602     */
     603    public function copy( $source, $destination, $overwrite = false, $mode = false ) {
     604        return false;
     605    }
     606
     607    /**
     608     * Moves a file.
    583609     *
    584610     * @since 2.5.0
     
    589615     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
    590616     *                            Default false.
    591      * @param int    $mode        Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
    592      *                            Default false.
    593      * @return bool True if file copied successfully, False otherwise.
    594      */
    595     public function copy( $source, $destination, $overwrite = false, $mode = false ) {
    596         return false;
    597     }
    598 
    599     /**
    600      * Move a file.
    601      *
    602      * @since 2.5.0
    603      * @abstract
    604      *
    605      * @param string $source      Path to the source file.
    606      * @param string $destination Path to the destination file.
    607      * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
    608      *                            Default false.
    609      * @return bool True if file copied successfully, False otherwise.
     617     * @return bool True on success, false on failure.
    610618     */
    611619    public function move( $source, $destination, $overwrite = false ) {
     
    614622
    615623    /**
    616      * Delete a file or directory.
    617      *
    618      * @since 2.5.0
    619      * @abstract
    620      *
    621      * @param string $file      Path to the file.
    622      * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
    623      *                          Default false.
    624      * @param bool  $type      Type of resource. 'f' for file, 'd' for directory.
    625      *                          Default false.
    626      * @return bool True if the file or directory was deleted, false on failure.
     624     * Deletes a file or directory.
     625     *
     626     * @since 2.5.0
     627     * @abstract
     628     *
     629     * @param string       $file      Path to the file or directory.
     630     * @param bool         $recursive Optional. If set to true, changes file group recursively.
     631     *                                Default false.
     632     * @param string|false $type      Type of resource. 'f' for file, 'd' for directory.
     633     *                                Default false.
     634     * @return bool True on success, false on failure.
    627635     */
    628636    public function delete( $file, $recursive = false, $type = false ) {
     
    631639
    632640    /**
    633      * Check if a file or directory exists.
    634      *
    635      * @since 2.5.0
    636      * @abstract
    637      *
    638      * @param string $file Path to file/directory.
     641     * Checks if a file or directory exists.
     642     *
     643     * @since 2.5.0
     644     * @abstract
     645     *
     646     * @param string $file Path to file or directory.
    639647     * @return bool Whether $file exists or not.
    640648     */
     
    644652
    645653    /**
    646      * Check if resource is a file.
     654     * Checks if resource is a file.
    647655     *
    648656     * @since 2.5.0
     
    657665
    658666    /**
    659      * Check if resource is a directory.
     667     * Checks if resource is a directory.
    660668     *
    661669     * @since 2.5.0
     
    670678
    671679    /**
    672      * Check if a file is readable.
     680     * Checks if a file is readable.
    673681     *
    674682     * @since 2.5.0
     
    683691
    684692    /**
    685      * Check if a file or directory is writable.
     693     * Checks if a file or directory is writable.
     694     *
     695     * @since 2.5.0
     696     * @abstract
     697     *
     698     * @param string $file Path to file or directory.
     699     * @return bool Whether $file is writable.
     700     */
     701    public function is_writable( $file ) {
     702        return false;
     703    }
     704
     705    /**
     706     * Gets the file's last access time.
    686707     *
    687708     * @since 2.5.0
     
    689710     *
    690711     * @param string $file Path to file.
    691      * @return bool Whether $file is writable.
    692      */
    693     public function is_writable( $file ) {
    694         return false;
    695     }
    696 
    697     /**
    698      * Gets the file's last access time.
     712     * @return int|false Unix timestamp representing last access time, false on failure.
     713     */
     714    public function atime( $file ) {
     715        return false;
     716    }
     717
     718    /**
     719     * Gets the file modification time.
    699720     *
    700721     * @since 2.5.0
     
    702723     *
    703724     * @param string $file Path to file.
    704      * @return int|bool Unix timestamp representing last access time.
    705      */
    706     public function atime( $file ) {
    707         return false;
    708     }
    709 
    710     /**
    711      * Gets the file modification time.
     725     * @return int|false Unix timestamp representing modification time, false on failure.
     726     */
     727    public function mtime( $file ) {
     728        return false;
     729    }
     730
     731    /**
     732     * Gets the file size (in bytes).
    712733     *
    713734     * @since 2.5.0
     
    715736     *
    716737     * @param string $file Path to file.
    717      * @return int|bool Unix timestamp representing modification time.
    718      */
    719     public function mtime( $file ) {
    720         return false;
    721     }
    722 
    723     /**
    724      * Gets the file size (in bytes).
    725      *
    726      * @since 2.5.0
    727      * @abstract
    728      *
    729      * @param string $file Path to file.
    730      * @return int|bool Size of the file in bytes.
     738     * @return int|false Size of the file in bytes on success, false on failure.
    731739     */
    732740    public function size( $file ) {
     
    735743
    736744    /**
    737      * Set the access and modification times of a file.
     745     * Sets the access and modification times of a file.
    738746     *
    739747     * Note: If $file doesn't exist, it will be created.
     
    747755     * @param int    $atime Optional. Access time to set for file.
    748756     *                      Default 0.
    749      * @return bool Whether operation was successful or not.
     757     * @return bool True on success, false on failure.
    750758     */
    751759    public function touch( $file, $time = 0, $atime = 0 ) {
     
    754762
    755763    /**
    756      * Create a directory.
    757      *
    758      * @since 2.5.0
    759      * @abstract
    760      *
    761      * @param string $path  Path for new directory.
    762      * @param mixed  $chmod Optional. The permissions as octal number, (or False to skip chmod)
    763      *                      Default false.
    764      * @param mixed  $chown Optional. A user name or number (or False to skip chown)
    765      *                      Default false.
    766      * @param mixed  $chgrp Optional. A group name or number (or False to skip chgrp).
    767      *                      Default false.
    768      * @return bool False if directory cannot be created, true otherwise.
     764     * Creates a directory.
     765     *
     766     * @since 2.5.0
     767     * @abstract
     768     *
     769     * @param string     $path  Path for new directory.
     770     * @param int|false  $chmod Optional. The permissions as octal number (or false to skip chmod).
     771     *                          Default false.
     772     * @param string|int $chown Optional. A user name or number (or false to skip chown).
     773     *                          Default false.
     774     * @param string|int $chgrp Optional. A group name or number (or false to skip chgrp).
     775     *                          Default false.
     776     * @return bool True on success, false on failure.
    769777     */
    770778    public function mkdir( $path, $chmod = false, $chown = false, $chgrp = false ) {
     
    773781
    774782    /**
    775      * Delete a directory.
     783     * Deletes a directory.
    776784     *
    777785     * @since 2.5.0
     
    781789     * @param bool   $recursive Optional. Whether to recursively remove files/directories.
    782790     *                          Default false.
    783      * @return bool Whether directory is deleted successfully or not.
     791     * @return bool True on success, false on failure.
    784792     */
    785793    public function rmdir( $path, $recursive = false ) {
     
    788796
    789797    /**
    790      * Get details for files in a directory or a specific file.
     798     * Gets details for files in a directory or a specific file.
    791799     *
    792800     * @since 2.5.0
     
    798806     * @param bool   $recursive      Optional. Whether to recursively include file details in nested directories.
    799807     *                               Default false.
    800      * @return array|bool {
     808     * @return array|false {
    801809     *     Array of files. False if unable to list directory contents.
    802810     *
    803      *     @type string $name        Name of the file/directory.
     811     *     @type string $name        Name of the file or directory.
    804812     *     @type string $perms       *nix representation of permissions.
    805813     *     @type int    $permsn      Octal representation of permissions.
Note: See TracChangeset for help on using the changeset viewer.