DirectoryLister/DirectoryLister — pull request #44 by alexander255 (2014-02-17 02:06:10+00:00)
Title: Basedir, Custom Date Format and Index File Support

This patch adds four new configuration options to the config.php:
* `base_directory`: BIG ONE! Allows DirectoryLister to list any directory instead of the current working directory. All internal paths within the DirectoryLister class now use absolute paths to account for this.
* `relative_paths`: This option allows the user to choose whether the file paths generated by the DirectoryLister class should be absolute (path relative to `$_SERVER['DOCUMENT_ROOT']`) or relative (path relative to the `index.php`/working directory). For compatibility reasons (see below) this option is by default set to `true`.
* `date_format`: Allows the user to specify his/her/its preferred way of displaying timestamps.
* `index_filenames`: If a directory contains a file with a name mentioned in this list, the listed directory URL will point directly towards the directory instead of a `?dir=...` URL.

Compatibility issues with existing themes:
Themes expect that each file entry in the $dirArray array contains an item called 'file_path' which is always a relative, existing file system path for file entries and always the `?dir=...` notation of a path for directories.
This becomes problematic in a number of scenarios:
* The path is absolute (relative to `$_SERVER['DOCUMENT_ROOT']`) and therefor is only valid in the client but not on the server. `relative_paths` is a workaround for this and basically fixes this issue for all setups where it can be left `true`.
* The file path is relative, but its a directory path detected by the `index_filenames` logic. If the theme engine uses `is_file()` to check whether it's looking at a file or directory, this is not a problem. However if the detection is done through the (poorly named) `file_exists()` function, then the theme engine will think that it's looking at a file while its actually looking at a directory and might do some stupid stuff.

The long term solution:
* Whenever a theme engine wants to probe a file it should use the new $dirArray entry item called 'real_path' which always contains the *the actual file path of any file or directory*. 'file_path' should only be used for the `href="..."` attributes of hyperlinks.
* When probing for a file a theme should use `is_file()` and `is_dir()` if it wants to know whether it's looking at a file or directory, respectively, and `file_exists()` only if wants to know whether an entry really exists.