directoryList

List the contents of a directory. Returns either an array, or a query. NOTE: Ensure that you have the required permissions to run this function.

directoryList(path [, recurse] [, listInfo] [, filter] [, sort] [, type]) → returns any

directoryList Argument Reference

path string
Required

The absolute path of the directory for which to list the contents. Alternatively, you can specify IP address as in the following example: DirectoryList("//12.3.123.123/c_drive/test");.

recurse boolean
Default: false

If true directoryList traverses the directory tree.
Values:
  • true
  • false

listInfo string
Default: path

Sets the return type. name returns an array with only the file names, path returns an array with the full path names and query returns a query containing the following fields: Attributes, DateLastModified, Directory, Link, Mode, Name, Size, Type.
Values:
  • name
  • path
  • query

filter string

File extension filter applied to the listed files, for example, *.jpg. Multiple filters can be applied by using a pipe delimiter. For example: *.doc|*.xls. You can also pass a function. The arguments of the passed function must have: path :the file path, type: The values (file or dir), extension: The file extension, if any, otherwise and empty string. This argument can also accept the instances of Java FileFilter Objects. In Lucee 4.5+ it can be a closure as well.

sort string

Columns by which to sort. e.g. Directory, Size DESC, DateLastModified. To qualify a column, use asc (ascending sort a-z) or dec (descending sort z-a).

type string
Default: all

CF 11+ Lucee 5+ Filter the result to only include files, directories, or both.
Values:
  • file
  • dir
  • all

Compatibility

ColdFusion:

Version 9+ Only CF11+ supports the type argument.

Lucee:

In Lucee the filter param can be a closure as well where the path is passed in. The sort argument only works when listInfo="query".

Railo:

If a directory returns false in recursive mode the contained files are processed anyways

Links more information about directoryList

Examples sample code invoking the directoryList function

arrayOfLocalFiles = directoryList( expandPath( "./" ), false, "name" );

queryOfFiles = directoryList( expandPath( "./" ), false, "query", "", "DateLastModified DESC" );

Including sub-directories and as an array containing full paths

arrayOfTempFiles = directoryList( "./", true );

Lucee 4.5+ Pass a closure instead of a string as filter param

arrayOfFilteredFiles = directoryList(".", false, "name", function(path) {
	return ListFindNoCase("Application.cfc,robots.txt,server.json,favicon.ico,.htaccess,README.md", path);
});

Fork me on GitHub