Skip to main content

Configuration

On first visit from browser, _files/config/config.php will get created with default options commented out. You can edit the config file directly or enable allow_settings or use install mode to edit settings from the interface. In many cases, you may not need to change any options.

_files/config/config.php
<?php

// Uncomment the parameters you want to edit.
return [
  //'root' => '',
  //'root_url_path' => NULL,
  //'root_lock' => NULL,
  //'start_path' => false,
  //'username' => '',
  //'password' => '',
  //'load_images' => true,
  //'load_files_proxy_php' => false,
  //'load_images_max_filesize' => 1000000,
  //'image_resize_enabled' => true,
  //'image_resize_use_imagemagick' => false,
  //'image_resize_cache' => true,
  //'image_resize_cache_use_dir' => false,
  //'image_resize_dimensions' => 320,
  //'image_resize_dimensions_retina' => 480,
  //'image_resize_dimensions_allowed' => '',
  //'image_resize_quality' => 85,
  //'image_resize_function' => 'imagecopyresampled',
  //'image_resize_sharpen' => true,
  //'image_resize_memory_limit' => 256,
  //'image_resize_max_pixels' => 60000000,
  //'image_resize_min_ratio' => 1.5,
  //'image_resize_cache_direct' => false,
  //'folder_preview_image' => true,
  //'folder_preview_default' => '_filespreview.jpg',
  //'menu_enabled' => true,
  //'menu_max_depth' => 5,
  //'menu_sort' => 'name_asc',
  //'menu_cache_validate' => true,
  //'menu_load_all' => false,
  //'menu_recursive_symlinks' => true,
  //'layout' => 'rows',
  //'cache' => true,
  //'cache_key' => 0,
  //'clean_cache_interval' => 7,
  //'clean_cache_allow_manual' => false,
  //'image_cache_file' => 'cache.txt',
  //'image_cache_max_last_access_time' => 90,
  //'image_cache_validate_time' => true,
  //'storage_path' => '_files',
  //'files_include' => '',
  //'files_exclude' => '',
  //'dirs_include' => '',
  //'dirs_exclude' => '',
  //'allow_symlinks' => true,
  //'get_mime_type' => false,
  //'license_key' => '',
  //'download_dir' => 'browser',
  //'download_dir_cache' => 'dir',
  //'assets' => '',
  //'allow_all' => false,
  //'allow_upload' => false,
  //'allow_delete' => false,
  //'allow_rename' => false,
  //'allow_new_folder' => false,
  //'allow_new_file' => false,
  //'allow_duplicate' => false,
  //'allow_text_edit' => false,
  //'allow_zip' => false,
  //'allow_unzip' => false,
  //'allow_move' => false,
  //'allow_copy' => false,
  //'allow_download' => true,
  //'allow_mass_download' => false,
  //'allow_mass_copy_links' => false,
  //'allow_settings' => false,
  //'allow_check_updates' => false,
  //'allow_tests' => true,
  //'allow_tasks' => false,
  //'demo_mode' => false,
  //'upload_allowed_file_types' => '',
  //'upload_max_filesize' => 0,
  //'upload_exists' => 'increment',
  //'ffmpeg_path' => 'ffmpeg',
  //'imagemagick_path' => 'convert',
  //'imagemagick_prefer_imagick' => true,
  //'imagemagick_image_types' => 'heif, heic, tiff, tif, psd, dng',
  //'use_google_docs_viewer' => false,
  //'lang_default' => 'en',
  //'lang_auto' => true,
  //'index_cache' => false,
];

Editing config​

To edit options, 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 when you upgrade Files Gallery. Therefore, you should only do this if your Files Gallery is temporary.

Config options​

root​

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

'root' => '', // default current directory, same as './', where index.php is dropped
'root' => './content', // sub-directory 'content' relative to application index.php
'root' => '../', // parent directory relative to application index.php
'root' => '/var/user/eddie', // absolute path from server root

root_url_path​

Assign the url path for your root from where files are loaded from. Normally, this should remain at default value NULL as this is detected automatically. If you are using symlinks, special Nginx config or pointing root to a folder for another domain, you might want to assign this manually.

'root_url_path' => NULL, // default value, root url path will be detected automatically
'root_url_path' => '/path/to/root', // will attempt to load files relative to assigned root path
'root_url_path' => 'https://www.anotherdomain.com/path/', // will attempt to load files relative to another domain root path

root_lock​

The root_lock option can be assigned to make sure all user root dirs are within the root_lock dir. This option should be used with _filesconfig.php so that the option itself is locked for all users who can edit settings or create new users. *This option is just a layer of security.

'root_lock' => NULL, // default value, root is not locked
'root_lock' => '/absolute/path', // all user 'root' dirs must be within /absolute/path
'root_lock' => './', // all user 'root' dirs must be within the application dir

start_path​

Assign the directory that displays when the application loads. When empty, the root dir will display. The path should be relative to the root dir, since start_path needs to be inside the root dir.

'start_path' => '', // start path is root dir (default)
'start_path' => 'galleries/birds', // start path 'galleries/birds' relative to the root dir

username​

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

'username' => 'myusername',

password​

Add username and password to protect your Files Gallery 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. Use this option for a light interface without resizing images or loading resized 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 direct URL for some reason.

'load_files_proxy_php' => false, // true | false

load_images_max_filesize​

Maximum image file size that can be loaded into gallery layouts. 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 when you have disabled image_resize_enabled.

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

image_resize_enabled​

Allows resizing of images loaded into galleries. The option should normally be used with image_resize_cache enabled. *If disabled, original source images will load as preview images.

'image_resize_enabled' => true, // true | false

image_resize_use_imagemagick​

Creates all resized images with ImageMagick, instead of the default PHP GD. Advantages may be better performance (especially with very large images) and better memory management (will not crash due to insufficient memory). *Requires ImageMagick.

'image_resize_use_imagemagick' => false, // 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_cache_use_dir​

Store resize image cache directly in the dir where the original is stored. This makes the cache portable if you want to migrate cache between servers, and allows the cache to remain valid when renaming or moving folders. When using this option, it's also easier to create your own resized images, as they simply exist in the subdir _files/filename.ext.jpg. When enabled, only one cache file will get created for each image, which keeps it simple and intuitive.

'image_resize_cache_use_dir' => false, // true | false

image_resize_dimensions​

Image resize dimensions. Default 320 is a good balance for most layout combinations.

'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 and use image_resize_dimensions for all screens.

'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 Gallery, but useful if you want to configure additional image sizes for other apps that use Files, like Embed. 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_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 increase PHP memory limit when resizing large images. Default value is set to 256 MB, which allows resizing images up to ~ 9000 px. If your default PHP memory_limit is already higher than the assigned value, it will have no effect.

'image_resize_memory_limit' => 256, // number

image_resize_max_pixels​

Sets the maximum allowed pixels (dimensions) when resizing images. Default value is 60000000 (60 megapixels), which allows resizing images up to approximately 10000 x 6000 px. This option is in place to protect server from attempting to resize extremely large images beyond server capabilities and to prevent errors and slow performance.

'image_resize_max_pixels' => 60000000, // 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 or slow servers.

'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.

'menu_enabled' => 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 unituitive for large directory structures. Users can still navigate to deeper folder levels directly from the view area.

'menu_max_depth' => 5,

Menu sort method, with options to sort by name or date, in ascending or descending order.

'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, 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 into the menu. When clicking items in the menu, pages will then display instantaneously without loading. This feature is useful for persistent galleries or simple root folder structures that you want to display without loading.

'menu_load_all' => false,

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

'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

cache​

When enabled, JSON cache files will be created for menu and folders, which allows the menu and folders to load much faster after creation. You can disable this option if you don't want Files Gallery to create and cache files. The cache is normally created in _files/cache/*.

'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,

clean_cache_interval​

Attemps to clean up the _files/cache dirs every 7 days from a background process. It doesn't really matter how often this process runs, as long as it runs once in a while, keeping your cache dirs nice and tidy. Set 0 to disable automated cache cleaning.

'clean_cache_interval' => 7, // days

clean_cache_allow_manual​

Allow cleaning cache manually from browser with ?action=clean_cache[&test=1], useful if you want to see what's going on and how many cache files get deleted. This option should probably only be allowed for specific users, if your gallery is public.

'clean_cache_allow_manual' => false, // true | false

image_cache_file​

Name of the cache index file that stores image cache entries for cache management. Since this file contains absolute server paths, you might want to rename it to obscure it from public view. You can disable image cache file indexing by assigning value false.

'image_cache_file' => 'cache.txt',

image_cache_max_last_access_time​

Allows the clean cache process to delete image cache files that have not been accessed for more than 90 days. This is useful for deleting cache files that were created before the image_cache_file option existed, or if image_cache_file is disabled. It's also useful for deleting image cache files that seem like they are almost never accessed. This option can be disabled by assigning value 0.

'image_cache_max_last_access_time' => 90, // days

image_cache_validate_time​

Makes sure that image resize cache files are newer than the original they were created for, in case the original image gets updated or replaced. This should normally always be enabled, unless you are using image_resize_cache_use_dir and plan on migrating cache between servers, in which case file dates may change.

'image_cache_validate_time' => true, // true | false

storage_path​

Defines where Files Gallery 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 Gallery instances that share the same storage. Storage path can be absolute or relative to the app.

'storage_path' => '_files',

files_include​

PHP regex to include and display only certain file names and extensions. When populated, only files that match the regex will display. The regex is tested on the file name (basename) without the full path. You can test regular expressions at phpliveregex.com.

'files_include' => '', // empty (default) all files are included
'files_include' => '/\.(pdf|jpe?g)$/i', // include only file extensions pdf, jpg and jpeg (hide all other files) / case insensitive
'files_include' => '/show|visible/', // include only file names that contain "show" and "visible"

files_exclude​

PHP regex to exclude certain file names or extensions. The regex is tested 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', // exclude file extensions pdf, jpg and jpeg / case insensitive
'files_exclude' => '/^[@.]/', // exclude all files that start with characters @ and .

dirs_include​

PHP regex to include and display only certain directories. When populated, only dirs that match the regex will display. The regex is tested on the folder path relative to the root. You can test regular expressions at phpliveregex.com.

'dirs_include' => '', // empty (default) all dirs are included
'dirs_include' => '/^(public|photos|documents)(\/|$)/', // include only public, photos and documents dirs in the root folder

dirs_exclude​

PHP regex to exclude cirectories. The regex is tested on the folder path relative to the root. You can test regular expressions at phpliveregex.com.

'dirs_exclude' => '', // empty (default) no folders are excluded
'dirs_exclude' => '/(\/|^)[@.]/', // exclude dirs that start with @ or .
'dirs_exclude' => '/(\/|^)(abc|xyz)(\/|$)/i', // exclude dirs with exact names "abc" and "xyz"

Allows Files Gallery to display and follow symlinks. Mostly works fine, but you may face problems if you have symlinks that point to locations on disk with different file permissions.

'allow_symlinks' => true,

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,

license_key​

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

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

download_dir​

Download all files in a directory.

'download_dir' => 'browser', // Download and zip from browser [default]
'download_dir' => 'zip', // Serve zip file from server / PHP
'download_dir' => 'files', // Non-zip multi-file download in browser, desktop only.
'download_dir' => '', // Disable download dir option

download_dir_cache​

Enables caching of server-created zip files when download_dir option is set to zip.

'download_dir_cache' => 'dir', // Store _files.zip in each dir [default]
'download_dir_cache' => 'storage', // Store in _files/zip/*
'download_dir_cache' => '', // disable server zip caching

assets​

Load Javascript and CSS assets from a different path. See self-hosted assets.

'assets' => '', // default empty, loads all assets from JSDelivr CDN
'assets' => '_files/assets', // Load all assets from self-hosted _files/assets dir

allow_all​

Enables all file manager allow_* actions from a single override option, which is useful when creating users without restrictions. *This option does not enable the allow_settings option, which should be limited to only trusted admin users.

'allow_all' => false, // true | false

allow_upload​

Allow uploading files.

'allow_upload' => false, // true | false

allow_delete​

Allow deleting files and folders.

'allow_delete' => false, // true | false

allow_rename​

Allow renaming files and folders.

'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 and directories.

'allow_duplicate' => false, // true | false

allow_text_edit​

Allow editing text and code files.

'allow_text_edit' => false, // true | false

allow_zip​

Allow compressing selected files into a zip archive. Requires PHP ZipArchive.

'allow_zip' => false, // true | false

allow_unzip​

Allow extracting selected zip files. Requires PHP ZipArchive.

'allow_unzip' => false, // true | false

allow_move​

Allow moving files and folders between directories.

'allow_move' => false, // true | false

allow_copy​

Allow copying files and dirs between directories.

'allow_copy' => false, // true | false

allow_download​

Allow various download features. When disabled, PHP download functions will also be blocked.

'allow_download' => true, // true | false

allow_mass_download​

Allows mass downloading files and folders recursively. This option needs to be enabled if you want to be able to download directories or multiple selected files. When disabled, PHP multi-file download functions are disabled also.

'allow_mass_download' => false, // true | false

Allow mass-copy links for selected files.

'allow_mass_copy_links' => false, // true | false

allow_settings​

Allows editing config options and creating users. When enabled, a settings button will appear in the topbar, which allows the user to edit config options and create users directly from the interface.

'allow_settings' => false, // true | false

allow_check_updates​

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

'allow_check_updates' => false,

allow_tests​

Allow url ?action=tests to disagnose server, PHP and config for Files Gallery compatibility.

'allow_tests' => true,

allow_tasks​

Tasks add-on to manage cache. * Not yet documented.

'allow_tasks' => false,

demo_mode​

When enabled, all filemanager operations will be blocked. Mainly used for the Files Gallery 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, although 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_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

ffmpeg_path​

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

'ffmpeg_path' => 'ffmpeg', // command path

imagemagick_path​

Path to ImageMagick command-line tool for PDF thumbnail creation. By default, we used convert because it's compatible with both ImageMagick version 6 and 7. If you know you are using ImageMagick version 7, you can change it to magick

'imagemagick_path' => 'convert', // ImageMagick version 6 and lower
'imagemagick_path' => 'magick', // default for ImageMagick version 7 and higher

imagemagick_prefer_imagick​

If installed and available, Files Gallery will prefer to use the PHP Imagick extension ahead of ImageMagick CLI.

'imagemagick_prefer_imagick' => true, // prefers PHP Imagick extension by default

imagemagick_image_types​

Image formats not supported in browsers, that we attempt to resize and convert with ImageMagick (when available)

'imagemagick_image_types' => 'heif, heic, tiff, tif, psd, dng',

use_google_docs_viewer​

Use Google document viewer to preview documents that otherwise can't be displayed in the browser. The viewer supports typical office document formats like doc, docx, xls, xlsx, ppt, pptx and csv and works by loading files through the external Google Docs Viewer.

'use_google_docs_viewer' => false, // false by default

lang_default​

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

'lang_default' => 'en', // language code

lang_auto​

Automatically assign interface language based on detected browser language. Disable if you want to force default browser language.

'lang_auto' => true, // true | false

index_cache​

Special option that allows caching the response from index.php as index.html. This will speed up response time on load, and may be useful for static galleries that don't change often.

'index_cache' => false,           // disabled by default
'index_cache' => 'mypassphrase',  // use index.php?create_index_cache=mypassphrase in browser to create index.html.

To publish index.html, trigger index.php?create_index_cache=mypassphrase from browser every time you make a change. This option should only be used if your default gallery is public (default config is non-login). You could use this option with users, but you will still need to re-publish index.html after any change is made to config or files in the public version. In this case, users would need to access and login from index.php since index.html is the published public version.