WP_Filesystem_Direct::dirlist( string $path, bool $include_hidden = true, bool $recursive = false ): array|false

Parameters

$pathstring

Path to directory or file.

$include_hiddenbooloptional

Whether to include details of hidden ("." prefixed) files.
Default true.Default: true

$recursivebooloptional

Whether to recursively include file details in nested directories.
Default false.Default: false

Return

array|false

Array of arrays containing file information. False if unable to list directory contents.

• ...$0array

  Array of file information. Note that some elements may not be available on all filesystems.

  • $namestring

    Name of the file or directory.

  • $permsstring

    *nix representation of permissions.

  • $permsnstring

    Octal representation of permissions.

  • $numberfalse

    File number. Always false in this context.

  • $ownerstring|false

    Owner name or ID, or false if not available.

  • $groupstring|false

    File permissions group, or false if not available.

  • $sizeint|string|false

    Size of file in bytes. May be a numeric string. False if not available.

  • $lastmodunixint|string|false

    Last modified unix timestamp. May be a numeric string. False if not available.

  • $lastmodstring|false

    Last modified month (3 letters) and day (without leading 0), or false if not available.

  • $timestring|false

    Last modified time, or false if not available.

  • $typestring

    Type of resource. 'f' for file, 'd' for directory, 'l' for link.

  • $filesarray|false

    If a directory and $recursive is true, contains another array of files. False if unable to list directory contents.

Cost profile

Measured from the compiled opcodes, not from a stopwatch. Every number here is identical on any machine that runs the same PHP version, and every function in core is ranked by these figures.

Cost class

Light

Touches nothing outside its own arguments.

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

13–42

Executed per call on PHP 8.4, depending on the branch taken. The body compiles to 145.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

5

5 places in core call this, so the cost is paid more often than your own code shows.

What one call costs · 8 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Filesystem_Direct::dirlist() can have, taken from its control-flow graph on PHP 8.4.

Across PHP versions

Oldest PHP that compiles this body: 7.4. An instruction is not a fixed amount of time, so a version with the same count is not necessarily the same speed; what the count rules out is a difference in the work itself.

Uses · 11

• trailingslashit()Appends a trailing slash.
• WP_Filesystem_Direct::is_file()Checks if resource is a file.
• WP_Filesystem_Direct::is_dir()Checks if resource is a directory.
• WP_Filesystem_Direct::is_readable()Checks if a file is readable.
• WP_Filesystem_Direct::gethchmod()
• WP_Filesystem_Direct::getnumchmodfromh()
• WP_Filesystem_Direct::owner()Gets the file owner.
• WP_Filesystem_Direct::group()Gets the file's group.
• WP_Filesystem_Direct::size()Gets the file size (in bytes).
• WP_Filesystem_Direct::mtime()Gets the file modification time.
• WP_Filesystem_Direct::dirlist()Gets details for files in a directory or a specific file.

Used by · 5

• WP_Filesystem_Direct::chgrp()Changes the file group.
• WP_Filesystem_Direct::chmod()Changes filesystem permissions.
• WP_Filesystem_Direct::chown()Changes the owner of a file or directory.
• WP_Filesystem_Direct::delete()Deletes a file or directory.
• WP_Filesystem_Direct::dirlist()Gets details for files in a directory or a specific file.

Source

View on Trac ↗View on GitHub ↗

624	public function dirlist( $path, $include_hidden = true, $recursive = false ) {625		if ( $this->is_file( $path ) ) {626			$limit_file = basename( $path );627			$path       = dirname( $path );628		} else {629			$limit_file = false;630		}631 632		if ( ! $this->is_dir( $path ) || ! $this->is_readable( $path ) ) {633			return false;634		}635 636		$dir = dir( $path );637 638		if ( ! $dir ) {639			return false;640		}641 642		$path = trailingslashit( $path );643		$ret  = array();644 645		while ( false !== ( $entry = $dir->read() ) ) {646			$struc         = array();647			$struc['name'] = $entry;648 649			if ( '.' === $struc['name'] || '..' === $struc['name'] ) {650				continue;651			}652 653			if ( ! $include_hidden && '.' === $struc['name'][0] ) {654				continue;655			}656 657			if ( $limit_file && $struc['name'] !== $limit_file ) {658				continue;659			}660 661			$struc['perms']       = $this->gethchmod( $path . $entry );662			$struc['permsn']      = $this->getnumchmodfromh( $struc['perms'] );663			$struc['number']      = false;664			$struc['owner']       = $this->owner( $path . $entry );665			$struc['group']       = $this->group( $path . $entry );666			$struc['size']        = $this->size( $path . $entry );667			$struc['lastmodunix'] = $this->mtime( $path . $entry );668			$struc['lastmod']     = gmdate( 'M j', $struc['lastmodunix'] );669			$struc['time']        = gmdate( 'h:i:s', $struc['lastmodunix'] );670			$struc['type']        = $this->is_dir( $path . $entry ) ? 'd' : 'f';671 672			if ( 'd' === $struc['type'] ) {673				if ( $recursive ) {674					$struc['files'] = $this->dirlist( $path . $struc['name'], $include_hidden, $recursive );675				} else {676					$struc['files'] = array();677				}678			}679 680			$ret[ $struc['name'] ] = $struc;681		}682 683		$dir->close();684		unset( $dir );685 686		return $ret;687	}

History

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.7.7 tag, from src/wp-admin/includes/class-wp-filesystem-direct.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.