Configuration Reference

Bootstrap Configuration

These configuration options are special configuration options only configurable through environment variables (e.g. through the .env file).

There are no corresponding configuration options for these values in the app/config definitions because they are applied before the application container (and configuration) is loaded.

FILES_PATH

A path (relative or absolute) to the directory in which you would like to list. This may even be a path outside of the application directory. When left unset, the root application directory (i.e. the folder where index.php is located) will be listed.

Possible Values

An absolute or relative file path (string)

Default Value

<unset>

COMPILE_CONTAINER

Whether or not the application container will be compiled. When set to false the container will not be compiled and cached. If left unset the container will be compiled and cached on first run and the cached container will be reused on subsequent requests. Disabling this comes with a (likely negligible) performance hit. Generally this should not be changed but might be necessary to modify when running Directory Lister on a read-only filesystem.

Possible Values

false or <unset>

Default Value

<unset>

Runtime Configuration

General application runtime configuration can be controlled through environment variables. This can be accomplished via an .env file located in the root of your application. An example file is provided as .env.example.

Advanced configuration can be accomplished via the app config located at app/config/app.php. However, changes to this fill will need to be manually re-applied between upgrades. It is highly recommended to stick to environment variables for controlling app configuration unless absolutely necessary.

ANALYTICS_FILE

File containing analytics scripts that will be included in the HTML output of your directory listing.

Possible Values

A (string) file name

Default Value

.analytics

APP_DEBUG

Enable application debugging and display error messages.

It is recommended that debug remains OFF unless troubleshooting an issue. Leaving this enabled WILL cause leakage of sensitive server information.

Possible Values

true or false

Default Value

false

APP_LANGUAGE

The application's interface language.

Possible Values

See the app/translations folder for available translations.

Default Value

en (English)

DATE_FORMAT

The format used for rendering dates in the application views.

Possible Values

See the PHP date format documentation for possible values.

Default Value

Y-m-d H:i:s

DIRECT_LINKS

Comma separated list of file matching patterns to be directly linked. Directly linked files will not be served by Directory Lister but handled by the web server directly.

This setting has no effect when FILES_PATH is set or when used in the Docker container.

DISPLAY_READMES

Parse and render README files on the page.

Possible Values

true or false

Default Value

true

Example

To directly link all .htm, .html and .php files in all folders and sub-folders.

DIRECT_LINKS=**/index.{htm,html},**/*.php

Possible Values

A comma separated list of file matching patterns.

Default Value

null

GOOGLE_ANALYTICS_ID

Your Google analytics tracking ID.

This configuration option has been deprecated and will stop working in a future release. See the Analytics Script Injection section for instructions on configuring analytics tracking.

Possible Values

A string in the format of UA-123456789-0 or false to disable

Default Value

false

HIDDEN_FILES_LIST

File containing hidden file definitions. Will be merged with definitions from the 'hidden_files' configuration option.

See the Hiding Files page for additional info on hiding files.

Possible Values

A path (string) to a file

Default Value

.hidden

HIDE_APP_FILES

Hide application specific files/directories (i.e. index.php and the app folder).

Possible Values

true or false

Default Value

true

HIDE_DOT_FILES

Hide dot files/directories from the listing.

Possible Values

true or false

Default Value

true

HIDE_VCS_FILES

Hide the files Version Control Systems (i.e. Git and Mercurial) use to store their metadata.

Possible Values

true or false

Default Value

true

HOME_TEXT

Text of the home link in the navigation breadcrumbs. If undefined or null will use the translated form of "home" from your selected language.

Possible Values

Any string

Default Value

null

MATOMO_ANALYTICS_SITE_ID

Your Matomo analytics site ID.

This configuration option has been deprecated and will stop working in a future release. See the Analytics Script Injection section for instructions on configuring analytics tracking.

Possible Values

A Matomo analytics site ID (string)

Default Value

false

MATOMO_ANALYTICS_URL

Your Matomo analytics URL.

This configuration option has been deprecated and will stop working in a future release. See the Analytics Script Injection section for instructions on configuring analytics tracking.

Possible Values

A Matomo analytics URL (string)

Default Value

false

MAX_HASH_SIZE

The maximum file size (in bytes) that can be hashed. This helps to prevent timeouts for excessively large files.

The larger a file is the longer it will take to calculate hashes for that file.

Possible Values

Any positive integer 0 - 9223372036854775807 (PHP_INT_MAX)

Default Value

1000000000 (1 GB)

META_DESCRIPTION

Meta tag description (i.e. <meta name="description">) text.

Possible Values

Any string

Default Value

Yet another directory listing, powered by Directory Lister.

READMES_FIRST

Show READMEs before the file listing.

Possible Values

true or false

Default Value

false

REVERSE_SORT

When enabled, reverses the order of files (after sorting is applied).

Possible Values

true or false

Default Value

false

SITE_TITLE

The title of your directory listing. This will be displayed in the browser tab/title bar along with the current path.

Possible Values

Any string

Default Value

Directory Lister

SORT_ORDER

Sorting order of files and folders. Can be one of several predefined values. Advanced sorting configuration can be achieved by using an anonymous function. See the sort_order configuration option documentation for more information.

Possible Values

type, natural, name, accessed, changed, modified, <anonymous function>

Default Value

type

TIMEZONE

Time zone used for date formatting.

Possible Values

For a list of supported time zones see: https://www.php.net/manual/en/timezones.php.

Default Value

The server's timezone

ZIP_DOWNLOADS

Enable downloading of directories as a zip archive.

Possible Values

true or false

Default Value

true

ZIP_COMPRESS

Compress Zip using Deflate. Enabling this option prevents file size estimation and it may prevent zip download resuming when paused.

Possible Values

true or false

Default Value

false

Cache Configuration

Application cache configuration is also controlled through environment variables. This can be accomplished via an .env file located in the root of your application. An example file is provided as .env.example.

Advanced configuration can be accomplished via the cache config located at app/config/cache.php. However, changes to this fill will need to be manually re-applied between upgrades. It is highly recommended to stick to environment variables for controlling cache configuration unless absolutely necessary.

CACHE_DRIVER

The application cache driver. Setting this value to array will disable the cache across requests. Additional driver-specific options may be required with certain values.

Possible Values

apcu, array, file, memcached, redis, php-file, valkey

Default Value

file

CACHE_LIFETIME

The app cache lifetime (in seconds). Setting this value to 0 will cache indefinitely.

Possible values

Any positive integer

Default Value

60 (one hour)

CACHE_LOTTERY

Some cache drivers require manually pruning the cache periodically to remove expired items. This is the percentage chance (out of 100) of a request "winning" the lottery causing the cache to be pruned.

Possible Values

Any integer betweeen 1 and 100

Default Value

2

MEMCACHED_HOST

The Memcached server hostname or IP address.

Possible Values

Any string

Default Value

localhost

Advanced Memcached configuration is possible via the memcached_config option in app/config/cache.php

MEMCACHED_PORT

The Memcached server port.

Possible Values

Any valid port as an integer (0 to 65353)

Default Value

11211

Advanced Memcached configuration is possible via the memcached_config option in app/config/cache.php

REDIS_HOST

The Redis server hostname or IP address.

Possible Values

Any string

Default Value

localhost

Advanced Reds configuration is possible via the redis_config option in app/config/cache.php

REDIS_PORT

The Redis server port.

Possible Values

Any valid port as an integer (0 to 65353)

Defualt Value

6379

Advanced Reds configuration is possible via the redis_config option in app/config/cache.php

VIEW_CACHE

Path to the view cache directory. Set to false to disable view caching entirely.

Possible Values

A directory path as a string or false to disable the view cache entirely

Default Value

app/cache/views

Icon Configuration

The icon config is located at app/config/icons.php. Here is were file types are mapped to their respective icons. The mapping is a PHP array where the array key is the file extension (without a preceding dot) and the array value is the desired Font Awesome class names.

icons.php

return [
    'icons' => [
        '7z' => 'fas fa-file-archive',
        'aac' => 'fas fa-music',
        'accdb' => 'fas fa-database',
        'ai' => 'fas fa-image',
        'aif' => 'fas fa-music',
        'apk' => 'fab fa-android',
        'app' => 'fas fa-window',
        'avi' => 'fas fa-video',
        'bak' => 'fas fa-save',
        'bat' => 'fas fa-terminal',
        // etc...
    ],
];

Advanced Configuration

Some configuration values do not have a direct corresponding environment variable. These values can only be controlled through their corresponding entries in the app/config files.

hidden_files

Array of hidden file definitions. Will be merged with definitions in the file defined in the hidden_files_list configuration option. Supports glob patterns (e.g. *.txt, file.{yml,yaml}, etc.).

See the Hiding Files page for additional info on hiding files.

Possible Values

An array of paths (strings)

Default Value

[] (an empty array)

Example

'hidden_files' => [
    'somefile.txt', // Matches 'somefile.txt' exactly
    'README.*', // Matches files named 'README' with any file extension
    'foo/*', // Matches all files in the 'foo' directory
    'schema.{ya?ml}', // Matches 'schema.yml' or 'schema.yaml'
]

memcached_config

The Memcached configuration anonymous function (closure). This option is used when the cache_driver configuration option is set to memcached. The closure receives a Memcached object as it's only parameter. You can use this object to configure the Memcached connection. At a minimum you must connect to one or more Memcached servers via the addServer() or addServers() methods.

Reference the PHP Memcached documentation for Memcached configuration options.

Possible Values

An anonymous function that receives a Memcached object

function (Memcached $memcached): void {
    // Configure the $memcached object
}

Default Value

DI\value(function (Memcached $memcached, Config $config): void {
    $memcached->addServer(
        $config->get('memcached_host'),
        $config->get('memcached_port')
    );
})

This closure adds a single connection to a server at the host defined by memcached_host on the port defined by memcached_port.

Environment Variables

Uses the MEMCACHED_HOST and MEMCACHED_PORT variables by default

redis_config

The Redis configuration anonymous function (closure). This option is used when the cache_driver configuration option is set to redis. The closure receives a Redis object as it's only parameter. You can use this object to configure the Redis connection. At a minimum you must connect to one or more Redis servers via the connect() or pconnect() methods.

Reference the phpredis documentation for Redis configuration options.

Possible Values

An anonymous function that receives a Redis object

function (Redis $redis): void {
    // Configure the $redis object
}

Default Value

DI\value(function (Redis $redis, Config $config): void {
    $redis->pconnect(
        $config->get('redis_host'),
        $config->get('redis_port')
    );
})

This closure adds a single connection to a server at the host defined by redis_host on the port defined by redis_port.

Environment Variables

Uses the REDIS_HOST and REDIS_PORT variables by default

http_cache

HTTP cache values for controlling browser page cache duration. An array of mime types mapped to their cache duration in seconds.

Possible Values

An array of mime types mapped to their cache duration as a seconds (integers).

Defualt Value

[
    'application/json' => 300,
    'application/zip' => 300,
]

sort_order

An anonymous function can be used to customize the sort order of files and folders in your directory listing. The anonymous function receives two SplFileInfo objects as arguments and must return an integer less than, equal to, or greater than zero to represent the first argument being respectively less than, equal to, or greater than the second.

'sort_order' => \DI\value(
    function (SplFileInfo $file1, SplFileInfo $file2): int {
        return strcmp($file1->getRealPath(), $file2->getRealPath());
    })
);

The anonymous function must be wrapped in a \DI\value() function.