云策 WordPress 开发者社区

函数文档

list_files()

查看官方原文 ↗
💡 云策文档标注

概述

list_files() 函数用于递归列出指定文件夹及其子目录中的所有文件，深度默认可达100层。该函数支持参数控制递归深度、排除项和是否包含隐藏文件。

关键要点

  • 函数返回文件路径数组或失败时返回 false
  • 参数包括 $folder（文件夹路径）、$levels（递归深度，默认100）、$exclusions（排除项数组）和 $include_hidden（是否包含隐藏文件）
  • 递归处理子目录，跳过当前目录、上级目录、隐藏文件和排除项
  • 空文件夹会以路径加斜杠形式返回，非空文件夹仅返回文件

代码示例

$upload_dir = wp_upload_dir();
$folder = $upload_dir['basedir'];
$files = list_files( $folder, 2 );
foreach ( $files as $file ) {
    if ( is_file( $file ) ) {
        $filesize = size_format( filesize( $file ) );
        $filename = basename( $file );
    }
    echo esc_html( $filename . "-" . $filesize );
}

注意事项

  • 函数返回绝对路径，而非仅文件名
  • 空文件夹会以路径加斜杠形式列出，非空文件夹仅列出文件
  • 使用 trailingslashit() 确保路径末尾有斜杠
  • 在 WordPress 6.3.0 版本添加了 $include_hidden 参数
📄 原文内容

Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep.

Description

The depth of the recursiveness can be controlled by the $levels param.

Parameters

$folderstringoptional
Full path to folder. Default empty.
$levelsintoptional
Levels of folders to follow, Default 100 (PHP Loop limit).

Default:100

$exclusionsstring[]optional
List of folders and files to skip.

Default:array()

$include_hiddenbooloptional
Whether to include details of hidden (“.” prefixed) files.

Default:false

Return

string[]|false Array of files on success, false on failure.

Source

function list_files( $folder = '', $levels = 100, $exclusions = array(), $include_hidden = false ) {
	if ( empty( $folder ) ) {
		return false;
	}

	$folder = trailingslashit( $folder );

	if ( ! $levels ) {
		return false;
	}

	$files = array();

	$dir = @opendir( $folder );

	if ( $dir ) {
		while ( ( $file = readdir( $dir ) ) !== false ) {
			// Skip current and parent folder links.
			if ( in_array( $file, array( '.', '..' ), true ) ) {
				continue;
			}

			// Skip hidden and excluded files.
			if ( ( ! $include_hidden && '.' === $file[0] ) || in_array( $file, $exclusions, true ) ) {
				continue;
			}

			if ( is_dir( $folder . $file ) ) {
				$files2 = list_files( $folder . $file, $levels - 1, array(), $include_hidden );
				if ( $files2 ) {
					$files = array_merge( $files, $files2 );
				} else {
					$files[] = $folder . $file . '/';
				}
			} else {
				$files[] = $folder . $file;
			}
		}

		closedir( $dir );
	}

	return $files;
}

View all references View on Trac View on GitHub

Uses Description
list_files()wp-admin/includes/file.php

Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep.
trailingslashit()wp-includes/formatting.php

Appends a trailing slash.
Used by Description
wp_privacy_delete_old_export_files()wp-includes/functions.php

Cleans up export files older than three days old.
get_plugin_files()wp-admin/includes/plugin.php

Gets a list of a plugin’s files.
list_files()wp-admin/includes/file.php

Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep.

Changelog

Version Description
6.3.0 Added the $include_hidden parameter.
4.9.0 Added the $exclusions parameter.
2.6.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Sarankumar


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Example for listing all files in the upload directory

    $upload_dir = wp_upload_dir();
$folder = $upload_dir['basedir']
$files = list_files( $folder, 2 );
foreach ( $files as $file ) {
	if ( is_file( $file ) ) {
		$filesize = size_format( filesize( $file ) );
		$filename = basename( $file ); 
	}
	echo esc_html( $filename . "-" . $filesize );
}

  2. Skip to note 5 content


    Philipp Stracker


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    This function returns a list of absolute paths (not file names!)

    print_r( list_files( __DIR__ ) );

/*
Output:

Array (
    [0] => /Users/philipp/Sites/public/dev-site/wp-content/plugins/test/test.php
    [1] => /Users/philipp/Sites/public/dev-site/wp-content/plugins/test/readme.txt
    [2] => /Users/philipp/Sites/public/dev-site/wp-content/plugins/test/license.txt
)
*/

  3. Skip to note 6 content


    vee


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Please note that this function seems to list only files but it is not.
    Some folder is empty, it’s showing in the list. Some folder is not empty, it’s showing only files.

    For example I have folders & files:
    wp-content/my/a
    wp-content/my/a/a.txt
    wp-content/my/b

    list_files() showing..
    wp-content/my/a/a.txt
    wp-content/my/b/

    Testing in WordPress 6.9-alpha-60636.