Skip to content

Connector configuration options 2.1

Jump to bottom Edit New page
OSWorX edited this page Jan 8, 2020 · 74 revisions

This is a list of the available options for elFinder 2.1 connector (PHP part), along with their default values. Options are specified by passing an array with certain keys as first argument to elFinder() class constructor. Example:

<?php

$opts = array(
    'roots'  => array(
        array(
            'driver' => 'LocalFileSystem',
            'path'   => '/path/to/files/',
            'URL'    => 'http://localhost/to/files/'
        )
    )
);

// run elFinder
$connector = new elFinderConnector(new elFinder($opts));
$connector->run();

In the example above we run elFinder using default wrapper elFinderConnector.

Main options

locale

Set locale. Currently only UTF-8 locales are supported. Passed to setLocale PHP function.

Warning: Setting the locale correctly is very important. Especially if you do not match the character encoding to that of the server file system, it will create a security vulnerability.

Data type: string
Default value: 'en_US.UTF-8'

defaultMimefile (>=2.1.8)

elFinderVolumeDriver mime.type file path as defaults. This can be overridden in each of the volume by setting the volume root mimefile. The default value '' meaning uses a file 'php/mime.type'.

Data type: string
Default value: ''

session (>=2.1.8)

Session handling wrapper class object. It must be implement elFinderSessionInterface.

Data type: elFinderSessionInterface
Default value: elFinderSession

sessionCacheKey (for elFinderSession Class)

Set sessionCacheKey. PHP $_SESSION array key of elFinder caches.

Data type: string
Default value: 'elFinderCaches'

base64encodeSessionData (for elFinderSession Class)

elFinder save session data as UTF-8. If the session storage mechanism of the system does not allow UTF-8, and it must be set true.

Data type: bool
Default value: false

uploadTempPath

Temp directory path for Upload. Default uses sys_get_temp_dir()

Data type: string
Default value: ''

commonTempPath (>=2.1.7)

Temp directory path for temporally working files. Default uses ./.tmp if it writable.

Data type: string Default value: './.tmp' or sys_get_temp_dir()

connectionFlagsPath (>=2.1.29)

Connection flag files path that connection check of current request. A file is created every time an access is made to this location and it is deleted at the end of the request. It is recommended to specify RAM disk such as "/dev/shm".

Data type: string Default value: commonTempPath or ''

maxArcFilesSize (>=2.1.7)

Max allowed archive files size (0 - no limit)

Data type: integer
Default value: 0

optionsNetVolumes (>=2.1.13)

Root options of the network mounting volume

Data type: array
Default value: array() e.g.

'optionsNetVolumes' => array(
    // key '*' is common additional volume root options
    '*'   => array(),
    // key of elFinder::$netDrivers is each protocol volumes
    'ftp' => array()
)

maxTargets (>=2.1.17)

Max number of limits of selectable items (0 - no limit)

Data type: integer
Default value: 1000

throwErrorOnExec (>=2.1.43)

Throw Error on exec()
true need try{} block for $connector->run();

Data type: boolean
Default value: false

debug

Send debug to client.

Data type: boolean
Default value: false

bind

Bind callbacks for user actions, similar to jQuery .bind(). Accepts array(key => value) pairs where:
key is a space separated list of actions to bind to;
value is an array of callable functions

Actions

  • ls, tree, parents, tmb, file, zipdl, size, mkdir, mkfile, rm, rename, duplicate, paste, upload, get, put, archive, extract, search, info, dim, resize, netmount, url, callback and chmod
    • These actions will be called after each command is executed. The parameters to be passed is $cmd, &$result, $args, $elfinder, $volume(only $args has target). In the callback can modify $result.
  • [above any command].pre (e.g. ls.pre)
    • These actions will be called before each command is executed. The parameters to be passed is $cmd, &$args, $this, $volume. In the callback can modify $args.
  • upload.presave
    • This action is called just before the file is saved at the time of upload. The parameters to be passed is &$path, &$name, $tmpname, $this, $volume. $path is relative path from the upload target.(It will be assigned at the time of the folder upload) In the callback can modify the $path and $name.

Note

  • callable function is array($instance, 'method') where $instance is instance of your callback class and method if a name of a function to call (in call $instance->method(...)).
  • When the callback returns a value true is elFinder view will be refreshed.

OR (Plugin action on any hook point)
key is "Cmd.HookPoint"
"Cmd.HookPoint" is "[any command].pre" and "upload.presave".
value is "Domain.Name.Method Name"
Domain is "Plugin" only now;
Name is Plugin name
Method Name is Plugin class's method for calling on "Cmd.HookPoint".

Data type: array
Default value: array()
Example:

<?php

/**
 * Simple callback catcher
 *
 * @param  string   $cmd       command name
 * @param  array    $result    command result
 * @param  array    $args      command arguments from client
 * @param  object   $elfinder  elFinder instance
 * @param  object   $volume    current volume instance
 * @return void|true
 **/
public function mySimpleCallback($cmd, &$result, $args, $elfinder, $volume) {
    // do something here
    // You can modify value $result directly
    $result['_customData'] = 'Custom data';
    // $volume is false if cmd has `targets`(multi targets). You can get each $volume like this.
    if (! $volume && isset($arg['targets']) && is_array($arg['targets'])) {
        foreach($arg['targets'] as $target) {
            $volume = $elfinder->getVolume($target);
        }
    }
    // You can force refresh the elFinder view by returning a value `true`
    return true;
}

$opts = array(
    'bind' => array(
        'mkdir mkfile rename duplicate upload rm paste' => array('mySimpleCallback'),
        'upload.presave' => array(
            'Plugin.AutoResize.onUpLoadPreSave',
            'Plugin.Watermark.onUpLoadPreSave'
        )
    ),
    'roots' => array(...)
);

Logging example

See here for available bind commands.

plugin

Configure plugin options of All volumes default value. When this config is omitted, the default value which plugin has is applied.

Data type: array
Default value: array()
Example:

$opts = array(
    'plugin' => array(
        'Plugin Name' = array(
            'Option Name' => Option Value,
        ),
    ),
    'roots' => array(...)
);

roots

Array of arrays with per root settings. This is the only required option.
Multiple Roots

Data type: array
Default value: array()
Example:

<?php

$opts = array(
    'roots'  => array(
        array(
            // Group for local volume (elFinder >= 2.1.15)
            'alias'        => 'LocalVolumes',
            'driver'       => 'Group',
            'id'           => 'l',
            'rootCssClass' => 'elfinder-navbar-root-local'
        ),
        array(
            'phash'  => 'gl_Lw', // set parent to 'LocalVolumes'
            'driver' => 'LocalFileSystem',
            'path'   => '/path/to/files/',
            'URL'    => 'http://localhost/to/files/'
        ),
        array(
            'phash'  => 'gl_Lw', // set parent to 'LocalVolumes'
            'driver' => 'LocalFileSystem',
            'path'   => '/path/to/files2/',
            'URL'    => 'http://localhost/to/files2/'
        ),
        array(
            'driver' => 'MySQL',
            'host'   => 'localhost',
            'user'   => 'eluser',
            'pass'   => 'elpass',
            'db'     => 'elfinder'
            'path'   => 1,
        ),
        array(
            'driver' => 'FTP',
            'host'   => '192.168.1.1',
            'user'   => 'eluser',
            'pass'   => 'elpass',
            'path'   => '/'
        )
    )
);

See more options below

Root options

  • driver - Volume driver
  • autoload - Is support autoload
  • phash - Folder hash value on elFinder to be the parent of this volume (elFinder >= 2.1.15)
  • trashHash - Folder hash value on elFinder to trash bin of this volume (elFinder >= 2.1.24)
  • path - Root directory path
  • startPath - Open this path on initial request instead of root path
  • URL - URL that points to path directory (also called 'root URL')
  • encoding - This volume's local encoding
  • locale - This volume's local locale
  • alias - Root path alias for volume root
  • i18nFolderName - Enable i18n folder name
  • mimeDetect - Method to detect files mimetypes
  • mimefile - Path to alternative mime types file
  • additionalMimeMap - Additional MIME type normalize map
  • dispInlineRegex - MIME regex of send HTTP header "Content-Disposition: inline"
  • imgLib - Image manipulations library
  • tmbPath - Directory for thumbnails
  • tmbPathMode - Umask for thumbnails dir creation
  • tmbURL - URL for thumbnails directory set in tmbPath
  • tmbSize - Thumbnails size in pixels
  • tmbCrop - Crop thumbnails to fit tmbSize
  • tmbBgColor - Thumbnails background color (hex #rrggbb or transparent)
  • bgColorFb - Image rotate fallback background color (hex #rrggbb)
  • tmbFbSelf - Fallback self image to thumbnail (nothing imgLib)
  • copyOverwrite - Replace files on paste or give new names to pasted files
  • copyJoin - Merge new and old content on paste
  • copyFrom - Allow to copy from this volume to other ones
  • copyTo - Allow to copy from other volumes to this one
  • tmpPath - (temporary) Directory for extracts etc.
  • uploadOverwrite - Replace files with the same name on upload or give them new names
  • uploadAllow - Mimetypes allowed to upload
  • uploadDeny - Mimetypes not allowed to upload
  • uploadOrder - Order to proccess uploadAllow and uploadDeny options
  • uploadMaxSize - Maximum upload file size
  • uploadMaxConn - Maximum number of chunked upload connection, -1 to disable chunked upload
  • defaults - Default file/directory permissions
  • attributes - File permission attributes
  • acceptedName - Validate new file name regex or function
  • accessControl - Function or class instance method to control files permissions
  • accessControlData - Data that will be passet to access control method
  • disabled - List of commands disabled on this root
  • statOwner - Include file owner, group & mode in stat results
  • allowChmodReadOnly - Allow exec chmod of read-only files
  • treeDeep - How many subdir levels return per request
  • checkSubfolders - Check children directories for other directories in it
  • separator - Directory separator
  • dateFormat - File modification date format
  • timeFormat - File modification time format
  • cryptLib - Library to crypt/uncrypt files names (not implemented yet)
  • archiveMimes - Allowed archive's mimetypes to create
  • archivers - Manual config for archivers
  • quarantine - Temporary directory for extracting archives (LocalFileSystem volume only)
  • plugin - Configure plugin options of each volume

General usage example

<?php

$opts = array(
    'roots'  => array(
        array(
            'driver'     => 'LocalFileSystem',
            'path'       => '/path/to/files/',
            'startPath'  => '/path/to/files/test',
            'URL'        => 'http://localhost/to/files/',
            'alias'      => 'Home',
            'mimeDetect' => 'internal',
            'imgLib'     => 'auto',
            'tmbPath'    => 'thumbnails',
            'tmbCrop'    => false,
            'defaults'   => array('read' => false, 'write' => true),
            'attributes' => array(
                array( // hide readmes
                    'pattern' => '/README/',
                    'read' => false,
                    'write' => false,
                    'hidden' => true,
                    'locked' => false
                ),
                array( // restrict access to png files
                    'pattern' => '/\.png$/',
                    'write' => false,
                    'locked' => true
                )
            ),
        ),
        array( // another root
            'driver' => 'MySQL',
            'host'   => 'localhost',
            'user'   => 'eluser',
            'pass'   => 'elpass',
            'db'     => 'elfinder'
            'path'   => 1,
        )
    )
);

driver

Volume driver. Set storage engine for current root, can be one of LocalFileSystem, MySQL, FTP

Data type: string
Default value: 'LocalFileSystem'

autoload

It must set true If volume driver supports autoload function.

Data type: boolean
Default value: false

phash (elFinder >= 2.1.15)

Folder hash value on elFinder to be the parent of this volume

Data type: string
Default value: ''

Example: you want to group local and net drives. Define 2 arrays like:

$roots[] = [
	// Group for local drives
	'alias'		=> 'Local Drives',
	'driver'	=> 'Group',
	'id'		=> 'l',
	'rootCssClass'	=> 'elfinder-navbar-root-local'
];

and:

$roots[] = [
	// Group for local drives
	'alias'	=> 'Net Drives',
	'driver'	=> 'Group',
	'id'		=> '2',
	'rootCssClass'	=> 'elfinder-navbar-root-network'
];

Now in your further drive definitions, add the phash value (depending if local or net) to the array. Example net drive:

$roots[] = [
	// set parent to 'Net Drives'
	'phash'		=> 'g2_Lw',
	'driver'		=> 'Dropbox2',
	// same as app_key
	'consumerKey'		=> 'j18xxxxxxx',
	// same as app_secret
	'consumerSecret'	=> 'g5xxxxxxxx',
	// optional (if created) - use this to establish a permanent connection
	'access_token'		=> 'hT_wOxxxxxxxxxxxx',
	'path'			=> '/'
];

phash start always with a letter (a-z) followed by the id of the group (here 2), then _ (underscore) and Lw For local drives the phash value would be g1_Lw

trashHash (elFinder >= 2.1.24)

Folder hash value on elFinder to trash bin of this volume, it require 'copyJoin' to true

Data type: string
Default value: ''

path

Root directory path

Data type: string
Default value: ''

startPath

Open this path on initial request instead of root path

Notice: In order to validate this option by a multi-route, you have to set a value only to the volume which applies this option.

Data type: string
Default value: ''

URL

URL that points to path directory (also called 'root URL'). If not set client will not see full path to files (replacement for old fileURL option), also all files downloads will be handled by connector.
Disable real file path from being shown

Data type: string
Default value: ''

encoding

This volume's local encoding. (server's file system encoding) It's necessary to be valid value to iconv. (Iconv List of Encodings)

Data type: string
Default value: '' (it mean is UTF-8)

locale

This volume's local locale. It's important for encoding setting. It's necessary to be valid value in your server.　(It can be checked by showlocale.php or typing locale -a on your server shell.)

Warning: Setting the locale correctly is very important. Especially if you do not match the character encoding to that of the server file system, it will create a security vulnerability.

Data type: string
Default value: '' (Use main options locale with empty value)

alias

Root path alias for volume root. If not set will use directory name of path. Warning: when this option is set it will also rewrite return path for getFileCallback

Data type: string
Default value: ''

i18nFolderName (elFinder >= 2.1.14)

Enable i18n folder name that convert name to elFinderInstance.messages['folder_'+name]

Data type: boolean Default value: false

mimeDetect

Method to detect files mimetypes. Can be auto, internal, finfo, mime_content_type

Data type: string
Default value: 'auto'

mimefile

Path to alternative mime types file. Only used when mimeDetect set to internal. If not set will use default mime.types

Data type: string
Default value: ''

additionalMimeMap (elFinder >= 2.1.22)

Additional Mime type normalization map

Example

array(
    'tpl:application/vnd.groove-tool-template' => 'text/plain' // '[ext]:[Detected MIME Type]' => '[Normalized MIME Type]'
)

Data type: array
Default value: array()

dispInlineRegex

MIME regex of send HTTP header "Content-Disposition: inline" on file open command.
'.*' is allow inline of all of MIME types
'$^' is not allow inline of all of MIME types
'^(?:image|text/plain$)' is recommended for safety on public elFinder

Data type: string
Default value: '^(?:(?:video|audio)|image/(?!.+\+xml)|application/(?:ogg|x-mpegURL|dash\+xml)|(?:text/plain|application/pdf)$)'

imgLib

Image manipulations library. Can be auto, imagick, gd or convert

Data type: string
Default value: 'auto'

tmbPath

Directory for thumbnails. If this is a simple filename, it will be prefixed with the root directory path. If you choose to use a location outside of the root directory, you should use a full pathname as a relative path using ellipses will get mangled and may not work (create thumbnails because tmbPath is NOT writable) on some server OS's.

Data type: string
Default value: '.tmb'

tmbPathMode

Umask for thumbnails dir creation. Will be removed in future

Data type: octal
Default value: 0777

tmbURL

URL for thumbnails directory set in tmbPath. Set it only if you want to store thumbnails outside root directory.

If you want chose original image as thumbnail it is able to set 'self'. (elFinder >= 2.1.12)

Data type: string
Default value: ''

tmbSize

Thumbnails size in pixels. Thumbnails are square

Data type: integer
Default value: 48

tmbCrop

Crop thumbnails to fit tmbSize. true - resize and crop, false - scale image to fit thumbnail size

Data type: boolean
Default value: true

tmbBgColor

Thumbnails background color (hex #rrggbb or transparent)

Data type: string
Default value: 'transparent' (elFinder < 2.1.12: '#ffffff')

bgColorFb (elFinder >= 2.1.12)

Image rotate fallback background color (hex #rrggbb). Uses this color if it can not specify to transparent.

Data type: string
Default value: '#ffffff'

tmbFbSelf (elFinder >= 2.1.12)

Fallback self image to thumbnail (nothing imgLib).

Data type: boolean
Default value: true

copyOverwrite

Replace files on paste or give new names to pasted files. true - old file will be replaced with new one, false - new file get name - original_name-number.ext

Data type: boolean
Default value: true

copyJoin

Merge new and old content on paste. true - join new and old directories content, false - replace old directories with new ones

Data type: boolean
Default value: true

copyFrom

Allow to copy from this volume to other ones

Data type: boolean
Default value: true

copyTo

Allow to copy from other volumes to this one

Data type: boolean
Default value: true

tmpPath

Temporary directory used for extracts etc. The default tmpPath is to use 'tmbPath'. If you choose to use another location, set 'tmpPath' to a full pathname.

Data type: string
Default value: '' // defaults to 'tmbPath'

uploadOverwrite

Replace files with the same name on upload or give them new names. true - replace old files, false give new names like original_name-number.ext

Data type: boolean
Default value: true

uploadAllow

Mimetypes allowed to upload

Data type: array
Default value: array()
Example:

'uploadAllow' => array('image') # allow any images
'uploadAllow' => array('image/png', 'application/x-shockwave-flash') # allow png and flash

uploadDeny

Mimetypes not allowed to upload. Same values accepted as in uploadAllow

Data type: array
Default value: array() Example:

'uploadDeny' => array('all') # deny of all types

uploadOrder

Order to proccess uploadAllow and uploadDeny options. Logic is the same as Apache web server options Allow, Deny, Order http://httpd.apache.org/docs/2.2/mod/mod_authz_host.html#order

Data type: array
Default value: array('deny', 'allow')

uploadMaxSize

Maximum upload file size. This size is per files. Can be set as number or string with unit 10M, 500K, 1G. Note: elFinder 2.1+ support chunked file uploading. 0 means unlimited upload.

Data type: integer|string
Default value: 0

uploadMaxConn (elFinder >= 2.1.12)

Maximum number of connection of chunked file uploading. -1 to disable chunked file upload.

Data type: integer Default value: 3

defaults

Default file/directory permissions. Setting hidden, locked here - take no effect

Data type: array
Default value: 'defaults' => array('read' => true, 'write' => true)

attributes

File (folder) permission attributes. Simple file permissions control

Data type: array
Default value: array()

Note: attributes is not for files only, also folders (when defined in pattern) can have permissions

acceptedName

Validate new file name regex or function

Data type: string
Default value: '/^[^\.].*/'
Example:

function validName($name) {
    return strpos($name, '.') !== 0;
}

// later in root options
'acceptedName' => 'validName'

accessControl

Function or class instance method to control files permissions. This works similar to bind option

Data type: callable(string|array)|null
Default value: null
Simple example:

/**
 * Simple function to demonstrate how to control file access using "accessControl" callback.
 * This method will disable accessing files/folders starting from '.' (dot)
 *
 * @param  string    $attr    attribute name (read|write|locked|hidden)
 * @param  string    $path    absolute file path
 * @param  string    $data    value of volume option `accessControlData`
 * @param  object    $volume  elFinder volume driver object
 * @param  bool|null $isDir   path is directory (true: directory, false: file, null: unknown)
 * @param  string    $relpath file path relative to volume root directory started with directory separator
 * @return bool|null
 **/
function access($attr, $path, $data, $volume, $isDir, $relpath) {
	$basename = basename($path);
	return $basename[0] === '.'                  // if file/folder begins with '.' (dot)
			 && strlen($relpath) !== 1           // but with out volume root
		? !($attr == 'read' || $attr == 'write') // set read+write to false, other (locked+hidden) set to true
		:  null;                                 // else elFinder decide it itself
}

accessControlData

Data that will be passet to access control method

Data type: undefined
Default value: null

disabled

List of commands disabled on this root (commands list)

Data type: array
Default value: array()

statOwner

Include file owner, group & mode in stat results on supported volume driver (LocalFileSystem(require POSIX in PHP), FTP on UNIX system-like). false to inactivate "chmod" command.

Data type: bool
Default value: false

allowChmodReadOnly

Allow exec chmod of read-only( on elFinder permission ) files.

Data type: bool
Default value: false

treeDeep

How many subdirs levels return per request

Data type: integer
Default value: 1

checkSubfolders

Check children directories for other directories in it. true every folder will be check for children folders, -1 every folder will be check asynchronously, false all folders will be marked as having subfolders

Data type: boolean | Integer
Default value: true
Note: Use -1 require the elFinder 2.1.23 or higher

separator

Directory separator. Required by client to show correct file paths

Data type: string
Default value: DIRECTORY_SEPARATOR

dateFormat

File modification date format. This value is passed to PHP date() function

Data type: string
Default value: 'j M Y H:i'

timeFormat

File modification time format

Data type: string
Default value: 'H:i'

cryptLib

Library to crypt/uncrypt files names (not implemented yet)

Data type: undefined
Default value: undefined

archiveMimes

Allowed archive's mimetypes to create. Leave empty for all available types

Data type: array
Default value: array()

archivers

Manual config for archivers. Leave empty for auto detect

Data type: array
Default value: array()

quarantine

Temporary directory for archive file extracting. This option only uses the LocalFileSystem volume driver.

We recommend to set a path outside the document root.

Data type: string
Default value: path/.quarantine

plugin

Configure plugin options of each volume

Data type: array
Default value: array()

Volume driver specific options

LocalFileSystem

array(
    'driver'         => 'LocalFileSystem',
    'path'           => 'PathToTargetDirectory',
    'dirMode'        => 0755,            // new dirs mode (default 0755)
    'fileMode'       => 0644,            // new files mode (default 0644)
    'quarantine'     => '.quarantine',   // quarantine folder name. Absolute path is also possible. (default '.quarantine') - required to check archive (must be hidden)
    'followSymLinks' => true,            // follow symbolic links (default true) (elFinder >= 2.1.8)
    'detectDirIcon'  => '',              // File to be detected as a folder icon image (elFinder >= 2.1.10) e.g. '.favicon.png'
    'keepTimestamp'  => 'array('copy', 'move')', // Keep timestamp at inner filesystem (elFinder >= 2.1.12) It allowed 'copy', 'move' and 'upload'.
)

MySQL

array(
    'driver'        => 'MySQL',
    'host'          => 'localhost',
    'socket'        => '/tmp/mysql.sock',
    'user'          => 'eluser',
    'pass'          => 'elpass',
    'db'            => 'elfinder',
    'files_table'   => 'elfinder_file',
    'path'          => 1,
    'tmpPath'       => '/tmp'
)

FTP

array(
    'driver'        => 'FTP',
    'host'          => 'localhost',
    'user'          => 'eluser',
    'pass'          => 'elpass',
    'port'          => 21,
    'mode'          => 'passive',
    'path'          => '/',
    'timeout'       => 10,
    'owner'         => true,
    'tmbPath'       => '',
    'tmpPath'       => '',
    'dirMode'       => 0755,
    'fileMode'      => 0644
)
Add a custom sidebar
Clone this wiki locally