Skip to main content

Configuration

Optional config

Although there are many config options, it is not necessary to make changes unless you really need to. In most cases, you can just drop Files app into any folder and use with default options.

config.php

After you run files app for the first time, config file _files/config/config.php will get created with all default configuration options commented out.

_files/config/config.php
<?php 

// Uncomment the parameters you want to edit.
return array (
//'root' => '',
//'start_path' => false,
//'username' => '',
//'password' => '',
//'load_images' => true,
//'load_files_proxy_php' => false,
//'load_images_max_filesize' => 1000000,
//'load_svg_max_filesize' => 100000,
//'image_resize_enabled' => true,
//'image_resize_cache' => true,
//'image_resize_dimensions' => 320,
//'image_resize_dimensions_retina' => 480,
//'image_resize_dimensions_allowed' => '',
//'image_resize_types' => 'jpeg, png, gif, webp, bmp',
//'image_resize_quality' => 85,
//'image_resize_function' => 'imagecopyresampled',
//'image_resize_sharpen' => true,
//'image_resize_memory_limit' => 128,
//'image_resize_max_pixels' => 30000000,
//'image_resize_min_ratio' => 1.5,
//'image_resize_cache_direct' => false,
//'folder_preview_image' => true,
//'folder_preview_default' => '_filespreview.jpg',
//'menu_enabled' => true,
//'menu_show' => true,
//'menu_max_depth' => 5,
//'menu_sort' => 'name_asc',
//'menu_cache_validate' => true,
//'menu_load_all' => false,
//'menu_recursive_symlinks' => true,
//'layout' => 'rows',
//'sort' => 'name_asc',
//'sort_dirs_first' => true,
//'cache' => true,
//'cache_key' => 0,
//'storage_path' => '_files',
//'files_exclude' => '',
//'dirs_exclude' => '',
//'allow_symlinks' => true,
//'history' => true,
//'breadcrumbs' => true,
//'transitions' => true,
//'click' => 'popup',
//'click_window' => '',
//'click_window_popup' => true,
//'code_max_load' => 100000,
//'topbar_sticky' => 'scroll',
//'check_updates' => false,
//'allow_tasks' => false,
//'get_mime_type' => false,
//'context_menu' => true,
//'prevent_right_click' => false,
//'license_key' => '',
//'filter_live' => true,
//'filter_props' => 'name, filetype, mime, features, title',
//'download_dir' => 'zip',
//'download_dir_cache' => 'dir',
//'allow_upload' => false,
//'allow_delete' => false,
//'allow_rename' => false,
//'allow_new_folder' => false,
//'allow_new_file' => false,
//'allow_duplicate' => false,
//'allow_text_edit' => false,
//'demo_mode' => false,
//'upload_allowed_file_types' => '',
//'upload_max_filesize' => 0,
//'upload_note' => '',
//'upload_exists' => 'increment',
//'popup_video' => true,
//'popup_transition' => 'glide',
//'popup_transition_play' => 'inherit',
//'popup_interval' => 5000,
//'popup_caption' => true,
//'popup_caption_hide' => true,
//'popup_caption_style' => 'block',
//'popup_caption_align' => 'center-left',
//'video_thumbs' => true,
//'video_ffmpeg_path' => 'ffmpeg',
//'video_autoplay' => true,
//'lang_default' => 'en',
//'lang_auto' => true,
//'lang_menu' => false,
);

Editing config

To edit options, open the config.php file in any editor and locate the property you want to change.

//'root' => '',

Un-comment the option by removing the //, change the value and save:

'root' => '../different/path',
Can I edit configuration options directly in index.php?

You can edit config options directly in index.php, but changes will be lost if/when you upgrade Files app. Only do this if your Files app is temporary / non-persistent.

Config options

root

Assign the root path from where files and directories are loaded. With default empty '' value, root is current directory. Path can be relative or absolute. Examples:

'root' => '' // default current directory, same as './'
'root' => 'content' // sub-directory 'content', same as './content'
'root' => '../' // parent directory
'root' => '/var/user/eddie/' // absolute path from server root

start_path

Assign the first directory that loads into view, by default root dir. It can be a relative or absolute path, but the dir must be inside the root dir.

'start_path' => '' // start path is same as root
'start_path' => 'galleries/birds' // custom start path relative to app

username

Add username and password to protect your Files app by login.

'username' => 'myusername'

password

Add username and password to protect your Files app by login. You can encrypt your password by using our md5() hash tool if you don't want the password to be exposed in the PHP file.

'password' => 'mypassword' // non-encrypted
'password' => '$2y$10$KGVfb/j9GyxQYha6bQtYEuredsqfEMs7FQEyuoEFEgIRQAdb9gQES' // encrypted

load_images

Load preview images. If disabled, icons will display in place of images.

'load_images' => true // true | false

load_files_proxy_php

Force images and files to load via PHP proxy if they can't be accessed by URL.

'load_files_proxy_php' => false // true | false

load_images_max_filesize

Maximum image file size to load directly into galleries. If image file size exceeds this value, file icon will display instead. This option is useful to prevent massive images from loading directly into the layout, and only if you have disabled image_resize_enabled.

'load_images_max_filesize' => 1000000 // 1000000 bytes ~ 1mb

load_svg_max_filesize

Maximum SVG file size to load directly into galleries. If file exceeds this value, file icon will display instead. This option is useful to prevent complex SVG shapes from causing slow rendering and a sluggish interface.

'load_images_max_filesize' => 100000 // 100000 bytes ~ 100kb

image_resize_enabled

Allows resizing of images loaded into galleries, which is strongly recommended. Should normally be used with image_resize_cache enabled. If disabled, original source images will load, which can be very slow

'image_resize_enabled' => true // true | false

image_resize_cache

Allow caching of resized images to drastically improve loading speed on consecutive visits. Resized images will normally get cached in your storage_path at files/cache/images/*.

'image_resize_cache' => true // true | false

image_resize_dimensions

Default resized image dimensions. Default 320 is a good balance between visible quality and file size.

'image_resize_dimensions' => 320

image_resize_dimensions_retina

Resize image dimensions for high-density (retina) screens. This allows you to serve higher quality images for HiDPI screens, at the cost of slightly larger file size and more cache files in storage. Set this option to 0 if you want to disable it.

'image_resize_dimensions_retina' => 480

image_resize_dimensions_allowed

Comma-separated list of allowed resize dimensions, in addition to the two defaults. Not used directly in Files app, but useful if you want to configure additional image sizes for other apps that use Files, like Embed app. For example '640, 800, 1024'.

'image_resize_dimensions_allowed' => '' // empty, only image_resize_dimensions and image_resize_dimensions allowed
'image_resize_dimensions_allowed' => '640, 800, 1024' // additional resize dimensions [640, 800, 1024] allowed

image_resize_types

Commma-separated list of image types to resize. Useful for example if you want to exclude PNG/GIF images to retain transparency and animations.

'image_resize_types' => 'jpeg, png, gif, webp, bmp'

image_resize_quality

JPG compression level for resized images.

'image_resize_quality' => 85

image_resize_function

Choose between imagecopyresampled (smoother) and imagecopyresized (faster). Difference is minimal, but you could use imagecopyresized for example if you want faster resizing when not using image resize cache.

'image_resize_function' => 'imagecopyresampled'

image_resize_sharpen

Creates sharper (less blurry) preview images.

'image_resize_sharpen' => true

image_resize_memory_limit

Temporarily increases PHP memory limit (if required) when resizing large images. Default value is set to 128 MB, which allows resizing images up to ~ 6000 px. If your default PHP memory_limit is already higher than the assigned value, it will have no effect.

'image_resize_memory_limit' => 128 // number

image_resize_max_pixels

Sets the maximum allowed pixels (dimensions) when resizing images. Default value is 30000000 (30 megapixels), which allows resizing images up to approximately 6000 x 5000 px. This option is in place to protect server from attempting to resize image sizes beyond capabilities and/or to prevent slow performance.

'image_resize_max_pixels' => 30000000 // number

image_resize_min_ratio

Minimum ratio difference between image resize target dimensions and source image dimensions. If the source image is only X times larger than the resize target, the source image will be used. It's pointless to create resized images if the source is only slightly larger than the resize target.

'image_resize_min_ratio' => 1.5 // number

image_resize_cache_direct

Will attempt to load direct path of cached resized images into the gallery, bypassing PHP proxy. May cause faster image loading and browser caching. However, if this option is enabled and you delete image cache, you may end up with missing image files because you are bypassing the PHP proxy that checks if cached resized images exist. If this option is enabled and you delete the image cache, you may need to increase cache_key.

'image_resize_cache_direct' => false

folder_preview_image

Attempts to load preview images for all folders. This could be slow on large folders and/or slow server.

'folder_preview_image' => true

folder_preview_default

Always prioritize this filename as folder preview image if it exists in folder. Useful if you want to assign a specific image for some folders, or if you want to assign hidden preview images or if you simply want to avoid the performance hit of scanning each dir for first image to use as preview.

'folder_preview_default' => '_filespreview.jpg'

Toggle the left folder menu on or off. You can still navigate folders from within the main view area. * If the root dir doesn't contain any folders, the menu will always be disabled.

'menu_enabled' => true

Toggle the left folder menu expanded or collapsed by default. This option has no effect on small screens (mobile), where the menu is always collapsed by default. The value is remembered by the browser on toggle and will always default to the last state the menu was in.

'menu_show' => true

Assign the maximum depth of recursive folders to load into the left menu. This is a precaution to prevent loading unlimited levels of folders into the menu, which may be slow and unproductive for large directory structures. Users can still navigate to deeper folder levels directly from the view area.

'menu_max_depth' => 5

Decides how the left folders menu is sorted, with options name_asc, name_desc, date_asc and date_desc.

'menu_sort' => 'name_asc' // name_asc, name_desc, date_asc, date_desc

When enabled, menu cache will be validated to make sure it matches the actual folder structure. This mechanism is normally necessary to make sure any changes you make (new folders etc) are validated vs the menu cache file. If disabled, menu will load faster, but the cache is only validated against root and root child-folders. This feature may be useful if you have a heavy but persistent (non-changing) folder structure, and want the menu to load fast. IF enabled and you make changes in subfolders (new folder), you will need to either delete the menu cache _files/cache/menu/* or increase option cache_key.

'menu_cache_validate' => true

When enabled, all folders in the menu will preload. When clicking items in the menu, pages will then display instantaneously without loading. This feature is useful for persistent galleries and/or simple root folder structures.

'menu_load_all' => false

List sub-directories of symlinks in the main menu. May cause harmless menu loops or duplicate items in the menu.

'menu_recursive_symlinks' => true

layout

Default gallery layout from options list, imagelist, blocks, grid, rows or columns. Layout is additionally controlled from the topbar layout dropdown menu, in which case it will override default layout.

'layout' => 'rows' // list, imagelist, blocks, grid, rows, columns

sort

Default sorting for files from options name, date, filesize and kind (file type), in ascending or descending order. Sorting is additionally controlled from the topbar sort dropdown menu, in which case it will override default sort.

'sort' => 'name_asc' // name_asc, name_desc, date_asc, date_desc, filesize_asc, filesize_desc, kind_asc, kind_desc

sort_dirs_first

When enabled, folders will always display first when mixed with files.

'sort_dirs_first' => true

cache

When enabled, JSON cache files will be created for menu and folders. This is strongly recommended, as it allows the menu and folders to load much faster after first visit. The cache is normally created in _files/cache/*. You can disable this option if you don't want Files app to create and cache files.

'cache' => true

cache_key

Cache data is validated vs a cache_key. Although cache will normally update automatically, if you want to force the cache to refresh, you can increase the cache_key number.

'cache_key' => 0

storage_path

Defines where Files app will store cache, config and other application data. Set to _files by default, which means all data will be stored inside folder _files/* relative to the application. You won't normally need to change this value, unless you want to store data in a different location, or if you have multiple Files applications that share the same storage. Storage path can be absolute or relative to the app.

'storage_path' => '_files'

files_exclude

PHP regex normally used to exclude or include only certain file types and folders. The regex is applied on the file name (basename) without the path. You can test regular expressions at phpliveregex.com.

'files_exclude' => '' // empty default, no files are excluded
'files_exclude' => '/\.(pdf|jpe?g)$/i' // excludes all files that end with .pdf, .jpeg and .jpg / case insensitive

dirs_exclude

A PHP regex to exclude certain paths and folders. The regex is applied on the folder path relative to root.

'dirs_exclude' => '' // empty default, no folders are excluded
'dirs_exclude' => '/\/eleph|\/football(\/|$)/i' // exclude dirs that start with "eleph" and dirs that match /football/*

Allows Files app to display and follow symlinks. Mostly works fine, but you may face issues if you have symlinks that point to locations on disk with different permissions or to locations that are not within the website document root.

'allow_symlinks' => true

history

When enabled, browser will change URL ?path/to/folder as you navigate folders. This also allows deep-linking directly to files and folders when sharing an URL.

'history' => true

Allows "breadcrumbs" navigation to display in the topbar.

'breadcrumbs' => true

transitions

Enables transitions when navigating between pages.

'transitions' => true

click

Choose what method to trigger when clicking items in the list. Default value "popup" will apply for all image/video files, falling back to "modal" for non-image files.

'click' => 'popup' // popup, modal, download, window or menu

click_window

Comma-separated list of file extensions that you want to open directly in new window on click. Useful for easy viewing of PDF, HTML and text files, instead of opening a preview in Files app first.

'click' => '' // empty, all file types open in click default
'click' => 'pdf, html' // Opens PDF and html in new browser window, allowing them to be previewed

click_window_popup

Opens browser windows from click_window in a popup-style browser window, overlaying current window. Useful when previewing PDF, html and text-type documents. * Does not apply for mobile devices, where new window will open as normal.

'click_window_popup' => true

code_max_load

Maximum file size for text/code files to load and preview in the code viewer/editor. The purpose of this is to prevent massive text files from causing a sluggish interface in the code syntax highlighter.

'click_window_popup' => 100000 // default 100000 ~ 100kb

topbar_sticky

Choose how the topbar attaches itself to screen. Default value scroll will attach the topbar to top of screen on scroll up, true will cause the topbar to always remain fixed, while false will disable fixed topbar and revert to normal behavior.

'topbar_sticky' => 'scroll' // 'scroll', true, false

check_updates

Checks for Files app updates and displays a bell icon in topbar if there is an update available, allowing user to "update", "download" or "read more".

'check_updates' => false

allow_tasks

Tasks plugin to manage cache. * Not yet documented.

'allow_tasks' => null

get_mime_type

Set to true to detect file mime type from server/PHP (slow) instead of from file extension (faster). This should not be necessary, unless you have file types with incorrect file extensions or if you want to validate file types on server for security reasons.

'get_mime_type' => false

context_menu

Enables context-menu button and right-click menu with options.

'context_menu' => true

prevent_right_click

Enable to block browser right-click menu on sensitive items (images, list items, menu).

'prevent_right_click' => false

license_key

Insert license key here to unlock features and remove license popup.

'license_key' => 'XX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX'

filter_live

Live search filtering on keyboard input. If disabled, input filter requires keyboard-return or unfocus to trigger, which may be useful if you have 1000's of files in folders and want to prevent slow filtering from triggering unnecessarily * Does not apply for mobile devices, which allways triggers on "search" or keyboard-hide.

'filter_live' => true

filter_props

File properties to use when filtering, more properties will cause slower processing. Properties name, filetype and mime apply for all file types, while features, title, headline, description, creator, credit, copyright, keywords, city, sub-location and province-state are available to image files with IPTC meta.

'filter_props' => 'name, filetype, mime, features, title' // default
'filter_props' => 'name, filetype, mime, features, title, headline, description, creator, credit, copyright, keywords, city, sub-location, province-state' // all

download_dir

Set to zip to add a button to download all files in folder as a zip file. This option requires PHP ZipArchive, and requires the server to first compress all files into the zip before serving it, which could be slow. Optionally, set to files for multi-file download directly in browser. This works nicely on desktop without having to zip files on server first, but it does not work on mobile devices.

'download_dir' => 'zip' // 'zip', 'files', '' (disabled)

download_dir_cache

Enables caching of created zip files when download_dir option is set to zip. This is recommended for performance, so that zip files don't need to get created every time any visitor clicks to download. Set to dir to store the _files.zip directly in the current folder or set to storage to store inside _files/zip/*. Default dir option is most effective, because it allows files app to check if the zip-cache is valid and updated, even if you change folder name.

'download_dir_cache' => 'dir' // 'dir' / 'storage' / '' /

allow_upload

Allow uploading files.

'allow_upload' => false // true | false

allow_delete

Allow deleting files.

'allow_delete' => false // true | false

allow_rename

Allow renaming files.

'allow_rename' => false // true | false

allow_new_folder

Allow creating new folders.

'allow_new_folder' => false // true | false

allow_new_file

Allow creating new files.

'allow_new_file' => false // true | false

allow_duplicate

Allow duplicating files.

'allow_duplicate' => false // true | false

allow_text_edit

Allow editing text and code files.

'allow_text_edit' => false // true | false

demo_mode

When enabled, all filemanager operations will be blocked. Mainly used for the Files app demo.

'demo_mode' => false // true | false

upload_allowed_file_types

Comma-separated list of allowed upload file types. List may contain extensions or mime-types with partial match, for example pdf, doc, image/*. When empty (default), all file types are allowed.

'upload_allowed_file_types' => '' // default, all file types are allowed
'upload_allowed_file_types' => 'pdf, doc, image/*' // *.pdf, *.doc and all image types are allowed

upload_max_filesize

Sets the maximum file size (bytes) allowed for uploads. Default value 0 means no limit, but maximum file size will always be limited by your server's PHP upload_max_filesize value.

'upload_max_filesize' => 0 // default, no limit
'upload_max_filesize' => 1000000 // maximum file size 1000000 ~ 1MB

upload_note

Optional text note at bottom of uploader with info about upload details. By default, it will display the path and max file size for uploads.

'upload_note' => '' // empty, shows default
'upload_note' => 'Upload images only, maximum %upload_max_filesize%' // custom message

upload_exists

Decides what to do if uploaded filename already exists in upload target folder. Default 'increment' will rename uploaded files by appending a number, 'overwrite' will overwrite existing files while 'fail' will cause the upload to fail.

'upload_exists' => 'increment' // increment filename, for example filename.jpg => filename-2.jpg
'upload_exists' => 'overwrite' // overwrite existing file if filename exists
'upload_exists' => 'fail' // upload fail of filename exists

When enabled, opens video formats in the popup, allowing user to navigate between other popup items. If disabled, video will open in simple modal.

'popup_video' => true

Assign popup transition style from options none, slide, glide, fade, zoom, pop, elastic.

'popup_transition' => 'glide' // 'none', 'slide', 'glide', 'fade', 'zoom', 'pop', 'elastic'

Assign popup transition style when in slideshow autoplay mode. Default 'inherit' will use same transition as popup_transition option.

'popup_transition_play' => 'inherit' // 'inherit', 'none', 'slide', 'glide', 'fade', 'zoom', 'pop', 'elastic'

Set interval in milliseconds between slides in popup autoplay mode.

'popup_interval' => 5000

Display popup caption, created from several file properties.

'popup_caption' => true

Autohide popup caption after a few seconds without user interaction.

'popup_caption_hide' => true

Assign popup caption style from options block, box, gradient, topbar and none.

'popup_caption_style' => 'block' // 'block', 'box', 'gradient', 'topbar', 'none'

Popup caption alignment from options left, center-left, center or right.

'popup_caption_align' => 'center-left' // 'left', 'center-left', 'center', 'right'.

video_thumbs

Create thumbnails for video files. This option requires FFmpeg and PHP exec() enabled. Processing video thumbnails is slow, but they will get cached just like resized images

'video_thumbs' => true // true | false

video_ffmpeg_path

Path to FFmpeg command-line for video thumbnail creation. Normally just 'ffmpeg', but some servers require a full path to the FFmpeg application.

'video_ffmpeg_path' => 'ffmpeg'

video_autoplay

Autoplay videos when user clicks to open them in popup.

'video_autoplay' => true

lang_default

Default interface language if browser language is not supported or lang_auto is disabled.

'lang_default' => 'en'

lang_auto

Automatically assign interface language based on detected browser language.

'lang_auto' => true

lang_menu

Display a dropdown menu in the topbar for selecting interface language.

'lang_menu' => false