skip to content

PHP: File Listing Class

This PHP class builds on our earlier directory listing functions and examples. The class is small and simple allowing us to extract specific file information from a single directory, or by recursing through a directory tree.

Basic usage

Our FileList PHP class comes with the following public methods:

void set_keys( ...$keys );
specify which values to return for each file
void add_filter( $key, Array );
return only files where $key matches one of the Array values
void recurse(); or recurse( $depth );
whether to recurse, and how far
array scan( $directory );
scan $directory returning an array of file details

For example, if we want to find all the XML and PDF files in the files/ directory, we use:

<?PHP $filelist = new \Chirp\FileList(); $filelist->add_filter('mime_type', ['application/xml', 'application/pdf']); $files = $filelist->scan("files/"); ?>

This populates the $files array with details of any matching files:

Array ( [0] => Array ( [mime_type] => application/xml [type] => file [pathname] => files/ajax1.xml [size] => 155 ) [1] => Array ( [mime_type] => application/xml [type] => file [pathname] => files/ajax2.xml [size] => 190 ) )

The list of support $key values is given below.

The FileList class

<?PHP namespace Chirp; // Original PHP code by Chirp Internet: // Please acknowledge use of this code by including this header. class FileList { private $keys = ['type', 'pathname', 'mime_type', 'size']; // default values to extract private $filters = []; private $recurse = FALSE; private $depth = 0; public function set_keys(...$keys) { $this->keys = $keys; } public function add_filter($key, Array $values) { $this->filters[$key] = $values; } public function recurse($depth = 0) { $this->recurse = TRUE; $this->depth = $depth; } private function extract(\SplFileInfo $finfo, $key) { switch($key) { case 'basename': return $finfo->getBasename("." . $finfo->getExtension()); case 'ext': return $finfo->getExtension(); case 'filename': return $finfo->getFilename(); case 'imagesize': return getimagesize($finfo->getRealpath()); case 'mime_type': return mime_content_type($finfo->getRealpath()); case 'mtime': return $finfo->getMTime(); case 'path': return $finfo->getPath(); case 'pathname': return $finfo->getPathname(); case 'realpath': return $finfo->getRealPath(); case 'size': return $finfo->getSize(); case 'type': return $finfo->getType(); default: error_log(__METHOD__ . ": unsupported key: '{$key}'"); $this->keys = array_diff($this->keys, [$key]); unset($this->filters[$key]); return FALSE; } } public function scan($dir, $depth = 0) { $retval = []; if($this->recurse && $this->depth && ($depth > $this->depth)) { return $retval; } if(substr($dir, -1) != "/") { // add trailing slash if missing $dir .= "/"; } try { // open directory for reading $d = new \DirectoryIterator($dir); } catch(\UnexpectedValueException $e) { error_log(__METHOD__ . ": " . $e->getMessage()); return $retval; } foreach($d as $fileinfo) { if($fileinfo->isDot()) { // skip hidden files continue; } if($this->recurse && ('dir' === $this->extract($fileinfo, 'type'))) { $dir_contents = $this->scan($this->extract($fileinfo, 'pathname'), $depth + 1); if($dir_contents) { $retval = array_merge($retval, $dir_contents); continue; } } $file_struct = []; foreach(array_unique(array_merge(array_keys($this->filters), $this->keys)) as $key) { $file_struct[$key] = $this->extract($fileinfo, $key); if(isset($this->filters[$key]) && !in_array($file_struct[$key], $this->filters[$key])) { continue 2; } } $retval[] = $file_struct; } return $retval; } } ?>

expand code box

As you can see most of the work is done by the DirectoryIterator SPL class which returns a list (iterator) of SplFileInfo objects which we can query as we want.

For each file encountered we first check the filters values, and then the keys values. The array returned for each file will include all values specified in either list.

Coding-wise, the most interesting feature is the new ... token which indicates a variable-length argument list. This is only available in PHP5.6+ and in earlier versions would need to be replaced by either an Array or a call to func_get_args.

Enabling Recursion

By default the FileList class will scan only a single directory, but enabling recursion is as simple as:

$filelist = new \Chirp\FileList(); $filelist->recurse();

Or, if you only want to go down one directory level:

$filelist = new \Chirp\FileList(); $filelist->recurse(1);

For example, to recursively search for PDF files by mime type:

<?PHP $filelist = new \Chirp\FileList(); $filelist->recurse(); $filelist->add_filter('mime_type', ['application/pdf']); $files = $filelist->scan("."); ?>

Or by filename extension:

<?PHP $filelist = new \Chirp\FileList(); $filelist->recurse(); $filelist->add_filter('ext', ['pdf']); $files = $filelist->scan("."); ?>

Where . represents the current working directory.

Supported key values

The version of the class presented above supports the following keys:

file name without suffix
file name suffix
file name with suffix
array returned by getimagesize
file mime type as returned by mime_content_type
last modified time
relative directory path
relative file path
full path to the file
file size in bytes
dir, file or link

You can add support for more values by extending the extract method. There are a few generic SplFileInfo methods we've left out for brevity, and you may have other requirements.


User Comments

Post your comment or question

20 May, 2022

One thing I found, in php 7.4: your
case 'mime_type':
return mime_content_type($finfo->getRealpath());
Was giving me an error...
may need to be:
case 'mime_type':
return $finfo->getRealpath();

19 May, 2022

I am upgrading my server to use PHP 7.4
It seems to be having an issue with the backslash in the \ Chirp \ FileList(
Any suggestions? It's odd, because I use 7.4 on my local machine, and it gives me no issues. I did try to upgrade to PHP 8 and got similar error messages

23 March, 2022

Good and useful class - much appreciated!
There seems to be just one small problem... very large files may return incorrect (negative) file size values. Any idea?

Unfortunately this is a known bug with PHP not properly supporting files larger than 2Gb