-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Client Server API 2.1
API version: 2.1
Client - JavaScript application which runs in the client's browser.
Connector - application which runs on the server (server-side). Connector executes commands initiated by the client and returns result to the client.
Volume - One of the root folders (can be just one or multiple). Each volume mounted using driver (class) which implements logic of data storage (local filesystem, remote filesystem, database, etc.). If volume is not available for reading, but available for writing, then it will be mounted as "drop box". If volume is neither readable nor writable, then it will not be mounted.
Default volume - First volume available for reading.
Request ID - A client with elFinder 2.1.29 or later sends a request including the HTTP header "X-elFinderReqid" or the request parameter "reqid" as the request ID. In addition, the client sends abort command when aborting the request. When the connector receives this "abort" command, it can interrupt the operation of that request.
The initiator of the connection is always the client, there is no long polling between client and server.
Client and connector work over HTTP(S) protocol and use JSON format for data exchange.
Connector must always return correct header Content-Type: application/json
, except for file and upload commands.
Client passes commands to connector using HTTP GET or POST methods.
Connector always expects cmd argument (name of the command) from client, example: http://localhost/connector.php?cmd=open
.
Name of commands on the client side doesn't always match with the connector side:
- client commands reload, back, forward, home - implemented in connector using open command
- client command open calls connector's open command for directory and file command for a file (if URL option is missing in client options)
- client command cut, copy, paste - implemented in connector using copy
- client commands which change the look of the file manager and display detailed info do not require a request to the connector.
For executing most of the commands, passing files path is required to determine which files/directories to act upon.
Paths are NEVER passed in clear text format. Passing paths in clear text format will lead to unwanted disclosure of information and can stop client side from working at all.
All paths between client and connector are passed in encrypted format called hash.
Old 1.0 API used MD5 for encryption - it made connector more complicated and caused problems with performance, so it's not recommended to use it anymore.
New 2.x PHP connector uses the following algorithm to create hash from file path:
- remove root path from file path
- encrypt resulting path so it could be later decrypted (not implemented yet, but stub is present)
- encode already encrypted path using base64 with replacement
+/=
->-_.
- remove trailing dots
- add prefix - unique volume id (must start with
[a-z]
) - resulting string must be valid HTML
id
attribute (that is why base64 is used).
Using this algorithm even without encryption, client cannot get real file paths on the server only relative to root paths. This hash algorithm is recommended but you can use your own implementation so long as it matches these 2 rules:
- hash must be valid for storage in the
id
attribute of an HTML tag - hash must be reversible by connector
In case of a fatal error (unable to give client correct information), the connector must return a JSON response with error key. error value can be of type string or array.
Error messages are passed as keys, which will be translated by the client. List of available keys can be found in /js/i18n/elfinder.en.js
starting with err
.
Examples:
{"error" : ["errConf", "errJSON"]} // "Invalid backend configuration. PHP JSON module not installed"
{"error" : "Invalid backend configuration"}
{"error" : ["errLocked", "Some_folder"]} // 'Folder "Some_folder" can’t be opened because you don’t have permission to see its contents.'
In case if command not found return:
{"error" : "errUnknownCmd"} // "Unknown command"
If some required parameter is missing:
{"error" : ["errCmdParams", "command_name"]} // "Invalid parameters for command "command_name"."
Any other data sent with error
parameter will be ignored on client side.
In most cases the connector returns information about files and/or directories. Info about each file/directory is represented as an object with parameters. This is called the object format.
Example:
{
"name" : "Images", // (String) name of file/dir. Required
"hash" : "l0_SW1hZ2Vz", // (String) hash of current file/dir path, first symbol must be letter, symbols before _underline_ - volume id, Required.
"phash" : "l0_Lw", // (String) hash of parent directory. Required except roots dirs.
"mime" : "directory", // (String) mime type. Required.
"ts" : 1334163643, // (Number) file modification time in unix timestamp. Required.
"date" : "30 Jan 2010 14:25", // (String) last modification time (mime). Depricated but yet supported. Use ts instead.
"size" : 12345, // (Number) file size in bytes
"dirs" : 1, // (Number) Only for directories. Marks if directory has child directories inside it. 0 (or not set) - no, 1 - yes. Do not need to calculate amount.
"read" : 1, // (Number) is readable
"write" : 1, // (Number) is writable
"locked" : 0, // (Number) is file locked. If locked that object cannot be deleted, renamed or moved
"tmb" : 'bac0d45b625f8d4633435ffbd52ca495.png' // (String) Only for images. Thumbnail file name, if file do not have thumbnail yet, but it can be generated than it must have value "1"
"alias" : "files/images", // (String) For symlinks only. Symlink target path.
"thash" : "l1_c2NhbnMy", // (String) For symlinks only. Symlink target hash.
"dim" : "640x480", // (String) For images - file dimensions. Optionally.
"isowner": true, // (Bool) has ownership. Optionally.
"csscls" : "custom-icon", // (String) CSS class name for holder icon. Optionally. It can include to options.
"volumeid" : "l1_", // (String) Volume id. For directory only. It can include to options.
"netkey" : "", // (String) Netmount volume unique key, Required for netmount volume. It can include to options.
"options" : {} // (Object) For volume root only. This value is same to cwd.options.
}
Client sends request with open command, init parameter.
Example: http://localhost/connector.php?cmd=open&init=1
- abort - abort the specified request (API >= 2.1029)
- archive - create archive
- callback - Output callback result
- chmod - chmod items
- dim - return image dimensions
- duplicate - create copy of files/directories
- editor - gateway to editor plugin (API >= 2.1030)
- extract - extract archive
- file - output file contents to the browser (download/preview)
- get - output plain/text file contents (preview)
- info - return info for files. (used by client "places" ui)
- ls - list of items name in directory
- mkdir - create directory
- mkfile - create text file
- netmount - mount network volume during user session. Only ftp now supported.
- open - open directory and initializes data when no directory is defined (first iteration)
- parents - return parent directories and its subdirectory childs
- paste - copy or move files
- ping - ping to keep current session
- put - save text file content
- rename - rename file
- resize - modify image file (resize/crop/rotate)
- rm - delete files/directories
- search - search for files
- size - return size for selected files or total folder(s) size infomation
- tmb - create thumbnails for selected files
- tree - return child directories
- upload - upload file
- url - return file url
- zipdl - download multiple items by archive (API >= 2.1012)
Abort the specified request
Arguments:
- cmd : abort
- id : request id to abort
Response: Empty content with HTTP respose code "204 No Content"
Packs directories / files into an archive.
- API >= 2.1029
Arguments:
- cmd : archive
- name : file name of the archive to create
- type : mime-type for the archive
- target : hash of the directory that are added to the archive directories / files
- targets[] : an array of hashes of the directories / files to archive
Response:
- added : (Array) Information about File/Directory of a new archive
Output callback result with JavaScript that control elFinder or HTTP redirect to callback URL. This is used for communication with the outside, such as OAuth of netmount.
Arguments:
-
node : elFinder node DOM id that accepted
/^[a-zA-Z0-9;._-]+$/
only - json : JSON data for output
- bind : bind command name (optional)
-
done :
1
or0
- 0: output redirect HTTP response, 1: output HTML included JavaScript for IFRAME/Child Window.
Response:
-
HTTP response
Location: [Redirect URL(Defined in the volume driver)]?node={node}&json={json}&bind={bind}&done=1*
- HTML included JavaScript for IFRAME/Child Window Must be replace {$node}, {$bind}, {$json} to each value.
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script>
var w = window.opener || window.parent || window;
try {
var node = '{$node}';
var bind = '{$bind}';
var data = {$json};
} catch(e) {
var data = {error: 'errDataNotJSON'};
}
try {
var elf = w.document.getElementById(node).elfinder;
if (elf) {
if (data.error) {
elf.error(data.error);
} else {
data.warning && elf.error(data.warning);
data.removed && data.removed.length && elf.remove(data);
data.added && data.added.length && elf.add(data);
data.changed && data.changed.length && elf.change(data);;
if (bind) {
elf.trigger(bind, data);
}
data.sync && elf.sync();
}
}
} catch(e) {
// for CORS but IE dose not support
w.postMessage && w.postMessage(JSON.stringify({bind: bind, data: data}), '*');
};
window.close();
</script>
</head>
<body>
<a href="#" onlick="window.close();return false;">Close this window</a>
</body>
</html>
chmod target items.
Arguments:
- targets[] : array of hashed paths of the nodes
- mode : Numeric notation file system permissions
Response: An array of successfully uploaded files if success, an error otherwise.
- changed : (Array) of files that were successfully done chmod. Information about File/Directory
Returns the dimensions of an image/video
Arguments:
- cmd : dim
- target : hash path of the node
- substitute : pixel that requests substitute image (optional) - API >= 2.1030
Response:
- dim: The dimensions of the media in the format {width}x{height} (e.g. "640x480").
- url: The URL of requested substitute image. (optional)
Creates a duplicate for directories / files. Copy name is generated as follows: basedir_name_filecopy+serialnumber.extension (if any)
Arguments:
- cmd : duplicate
- targets[] : An array of hashes for the directories or files to be duplicated
Response: added (Array) Information about File/Directory of the duplicate.
Commands for editor plug-ins. Used for communication between front-end plug-ins and back-end plug-ins.
- API >= 2.1030
Arguments:
- cmd : editor
- name : editor plugin name
- method : The name of the method to call with the editor plugin. The editor plugin should accept only the method names allowed on the client side.
- args : An associative array of arguments to be passed to the editor plugin.
Response: (Any)
Unpacks an archive.
Arguments:
- cmd : extract
- target : hash of the archive file
- makedir : "1" to extract to new directory
Response:
- added : (Array) Information about File/Directory of extracted items
Output file into browser. This command applies to download and preview actions.
Arguments:
- cmd : file
- target : file's hash,
- download : Send headers to force download file instead of opening it in the browser.
- cpath (API >= 2.1.39) : Cookie path that temporary cookie set up until download starts. If this parameter is specified, the connector must set the cookie name as "elfdl" + Request ID (The value is irrelevant, maybe "1") . This cookie is deleted by the client at the start of download.
May need to set Content-Disposition, Content-Location and Content-Transfer-Encoding. Content-Disposition should have 'inline' for preview action or 'attachments' for download.
Returns the content as String (As UTF-8)
Arguments:
- cmd : get
- current : hash of the directory where the file is stored
- target : hash of the file
-
conv : instructions for character encoding conversion of the text file
-
1 : auto detect encoding(Return
false
as content in response data when failed) -
0 : auto detect encoding(Return
{ "doconv" : "unknown" }
as response data when failed) - Original Character encoding : original character encoding as specified by the user
-
1 : auto detect encoding(Return
Response:
-
content - file contents (UTF-8 String or Data URI Scheme String) or
false
- encoding - (Optional) Detected original character encoding (Require when converting from encoding other than UTF-8)
-
doconv - (Optional)
"doconv":"unknown"
is returned to ask the user for the original encoding if automatic conversion to UTF-8 is not possible when requested withconv = 0
.
For files other than text files, content
must be returned as string data of Data URI Scheme.
{
"content": "Hello world!" // contents of the file
}
Returns information about places nodes
Arguments:
- cmd : info
- targets[] : array of hashed paths of the nodes
Response:
- files: (Array of data) places directories info data Information about File/Directory
Return a list of item names in the target directory. arguments:
- cmd : ls
- target : hash of directory,
- intersect[] : An array of the item names for presence check.
Response:
- list : (Object) item names list with hash as key. Return only duplicate files if the intersect[] is specified.
{
"list": {
"l1_Zm9sZGVy": "folder",
"l1_aW1hZ2UuanBn": "image.jpg",
"l1_dGV4dC50eHQ": "text.txt"
}
}
Create a new directory.
Arguments:
- cmd : mkdir
- target : hash of target directory,
- name : New directory name
- dirs[] : array of new directories path (requests at pre-flight of folder upload)
Response:
- added : (Array) Array with a single object - a new directory. Information about File/Directory
- hashes : (Object) Object of path in the dirs[] as a key to the corresponding hash value.
Create a new blank file.
Arguments:
- cmd : mkfile
- target : hash of target directory,
- name : New file name
Response:
- added : (Array) Array with a single object - a new file. Information about File/Directory
Mount network volume during user session.
Arguments:
- protocol : network protocol. Now only ftp supports. Required.
- host : host name. Required.
- path : root folder path.
- port : port.
- user : user name. Required.
- pass : password. Required.
- alias : mount point name. For future usage. Now not used on client side.
- options : additional options for driver. For future usage. Now not used on client side.
Returns information about requested directory and its content, optionally can return directory tree as files, and options for the current volume.
Arguments:
- init : (true|false|not set), optional parameter. If true indicates that this request is an initialization request and its response must include the value api (number or string >= 2) and should include the options object, but will still work without it. Also, this option affects the processing of parameter target hash value. If init == true and target is not set or that directory doesn't exist, then the data connector must return the root directory of the default volume. Otherwise it must return error "File not found".
- target : (string) Hash of directory to open. Required if init == false or init is not set
- tree : (true|false), optional. If true, response must contain the top-level object of other volumes.
Response:
- api : (Float) The version number of the protocol, must be >= 2.1, ATTENTION - return api ONLY for init request!
- cwd : (Object) Current Working Directory - information about the current directory. Information about File/Directory
- files : (Array) array of objects - files and directories in current directory. If parameter tree == true, then added to the root folder objects of other volumes. The order of files is not important. Information about File/Directory
- netDrivers : (Array) Network protocols list which can be mounted on the fly (using netmount command). Now only ftp supported.
- Optional
- uplMaxFile : (Number) Allowed upload max number of file per request. For example 20
- uplMaxSize : (String) Allowed upload max size per request. For example "32M"
- options : (Object) Further information about the folder and its volume
{
options : {
"path" : "files/folder42", // (String) Current folder path
"url" : "http://localhost/elfinder/files/", // (String) Current folder URL
"tmbURL" : "http://localhost/elfinder/files/.tmb/", // (String) Thumbnails folder URL
"separator" : "/", // (String) Path separator for the current volume
"disabled" : [], // (Array) List of commands not allowed (disabled) on this volume
"copyOverwrite" : 1, // (Number) Whether or not to overwrite files with the same name on the current volume when copy
"uploadOverwrite" : 1, // (Number) Whether or not to overwrite files with the same name on the current volume when upload
"uploadMaxSize" : 1073741824, // (Number) Upload max file size per file
"uploadMaxConn" : 3, // (Number) Maximum number of chunked upload connection. `-1` to disable chunked upload
"uploadMime": { // (Object) MIME type checker for upload
"allow": [ "image", "text/plain" ], // (Array) Allowed MIME type
"deny": [ "all" ], // (Array) Denied MIME type
"firstOrder": "deny" // (String) First order to check ("deny" or "allow")
},
"dispInlineRegex" : "^(?:image|text/plain$)", // (String) Regular expression of MIME types that can be displayed inline with the `file` command
"jpgQuality" : 100, // (Number) JPEG quality to image resize / crop / rotate (1-100)
"syncChkAsTs" : 1, // (Number) Whether or not to current volume can detect update by the time stamp of the directory
"syncMinMs" : 30000, // (Number) Minimum inteval Milliseconds for auto sync
"uiCmdMap" : { "chmod" : "perm" }, // (Object) Command conversion map for the current volume (e.g. chmod(ui) to perm(connector))
"i18nFolderName" : 1, // (Number) Is enabled i18n folder name that convert name to elFinderInstance.messages['folder_'+name]
"archivers" : { // (Object) Archive settings
"create" : [
"application/zip",
"application/x-tar",
"application/x-gzip"
], // (Array) List of the mime type of archives which can be created
"extract" : [
"application/zip",
"application/x-tar",
"application/x-gzip"
], // (Array) List of the mime types that can be extracted / unpacked
"createext": {
"application/zip": "zip",
"application/x-tar": "tar",
"application/x-gzip": "tgz"
} // (Object) Map list of { MimeType: FileExtention }
}
}
}
- debug : (Object) Debug information, if you specify the corresponding connector option.
{
"debug":{
"connector":"php", // (String) Connector type
"phpver" : "5.3.6", // (String) php version
"time" : 0.0749430656433, // (Number) Execution time
"memory" : "3348Kb / 2507Kb / 128M", // (String) Used / Free / Available Memory
"volumes" : [ // (Array) Debugging by volume
{
"id" : "l1_", // (String) ID of the Volume
"driver" : "localfilesystem", // (String) Driver type (class name)
"mimeDetect" : "internal", // (String) Method for determining mime type
"imgLib" : "gd" // (String) Library for working with images
}
],
"mountErrors" : [ // (Array) List of errors for not mounted volumes
0 : "Root folder has not read and write permissions."
]
}
}
Returns all parent folders and their's first level (at least) subfolders and own(target) stat. This command is invoked when a folder is reloaded or there is no data to display the tree of the target folder in the client. Data provided by 'parents' command should enable the correct drawing of tree hierarchy directories.
Arguments:
- cmd : parents
- target : folder's hash
-
until : until to hash, getting
parents
is enough for that (API >= 2.1024)
Response:
- tree : (Array) Folders list. Information about File/Directory
Example:
With the present hierarchy
/root1* /dir1* /dir11* /dir111* /dir12* /dir121 /dir2* /dir22 /dir23 /dir231 /root2
Should 'dir111' be reloaded, 'parents' data should return:
- 'dir111' parent directories
- for each parent directory, its subdirectories (no more depth is needed)
This way, client-side component will render the following reloaded hierarchy
/root1 /dir1 /dir11 /dir111 /dir12 /dir2 /root2
Copies or moves a directory / files
Arguments:
- cmd : paste
- dst : hash of the directory to which the files will be copied / moved (the destination)
- targets[] : An array of hashes for the files to be copied / moved
- cut : 1 if the files are moved, missing if the files are copied
- renames[] : Filename list of rename request
- suffix : Suffixes during rename (default is "~")
Response:
If the copy / move is successful:
- added : (Array) array of file and directory objects pasted. Information about File/Directory
- removed : (Array) array of file and directory 'hashes' that were successfully deleted
{
"added": [{
"mime": "text\/plain",
"ts": 1380910690,
"read": 1,
"write": 1,
"size": 51,
"hash": "l2_dW50aXRsZWQgZm9sZGVyL1JlYWQgVGhpcyBjb3B5IDEudHh0",
"name": "Read This copy 1.txt",
"phash": "l2_dW50aXRsZWQgZm9sZGVy"
}],
"removed": ["l2_UmVhZCBUaGlzIGNvcHkgMS50eHQ"]
}
Caution
- If the file name of the rename list exists in the directory, The command should rename the file to "filename + suffix"
- The command should stop copying at the first error. Is not allowed to overwrite files / directories with the same name. But the behavior of this command depends on some options on connector (if the user uses the default one). Please, take look the options:
Ping to keep current session.
Previously it was used to prevent bugs of uploading with Safari, but it is not currently used. http://www.webmasterworld.com/macintosh_webmaster/3300569.htm
Arguments:
- cmd : ping
Response: sends a blank response with the header @Connection: close@
Stores contents data in a file.
Arguments (passed in via HTTP POST):
- cmd : put
- target : hash of the file
- content : new contents of the file
- encoding : character encoding at the time of saving (Text data will be sent by UTF-8) or "scheme" for URL of contents or Data URI scheme
content
of file data other than text file is sent as string data of Data URI Scheme or URL of new contents with param encoding=scheme
.
Response: An array of successfully uploaded files if success, an error otherwise.
- changed : (Array) of files that were successfully uploaded. Information about File/Directory
Renaming a directory/file
Arguments:
- cmd : rename
- target : hash directory/file renaming
- name : New name of the directory/file
Response:
- added : (Array) array of file and directory objects renamed. Information about File/Directory
- removed : (Array) array of file and directory 'hashes' that were successfully remoevd
Change the size of an image.
Arguments:
- cmd : resize
- mode : 'resize' or 'crop' or 'rotate'
- target : hash of the image path
- width : new image width
- height : new image height
- x : x of crop (mode='crop')
- y : y of crop (mode='crop')
- degree : rotate degree (mode='rotate')
- quality
Response:
- changed : (Array) of files that were successfully resized. Information about File/Directory
Recursively removes files and directories.
Arguments:
- cmd : rm
- targets[] : (Array) array of file and directory hashes to delete
Response:
- removed : (Array) array of file and directory 'hashes' that were successfully deleted
Return a list of files and folders list, that match the search string. arguments:
- cmd : search
- q : search string
- target : search target hash (optional)
- mimes : Array of search target MIME-type (optional)
Response:
- files : (Array) array of objects - files and folders list, that match the search string. Information about File/Directory
Returns the size of a directory or file.
Arguments:
- cmd : size
- targets[] : hash paths of the nodes
Response:
- size: The total size for all the supplied targets.
- fileCnt: The total counts of the file for all the supplied targets. (Optional to API >= 2.1025)
- dirCnt: The total counts of the directory for all the supplied targets. (Optional to API >= 2.1025)
- sizes: An object of each target size infomation. (Optional to API >= 2.1030)
{
"dirCnt": 2,
"fileCnt": 2,
"size": 10681,
"sizes": {
"l1_QWRkb24vanM": {
"dirCnt": 1,
"fileCnt": 1,
"size": 5723
},
"l1_QWRkb24vcGhw": {
"dirCnt": 1,
"fileCnt": 1,
"size": 4958
}
}
}
Background command. Creates thumbnails for images that do not have them. Number of thumbnails created at a time is specified in the Connector_Configuration_RU option tmbAtOnce. Default is 5.
Arguments:
- cmd : tmb
- targets[] : an array of hash path to the directory in which to create thumbnails
Response:
{
"images" : { // (Object)
"a696323d7fd86513754004ba8bc12967": // (String) has of the file path
"http://localhost:8001/~troex/git/elfinder/files/.tmb/a696323d7fd86513754004ba8bc12967.png"
// (String) Thumbnail URL
}
}
Return folder's subfolders.
Arguments:
- cmd : tree
- target : folder's hash
Response:
- tree : (Array) Folders list. Information about File/Directory
Process file upload requests. Client may request the upload of multiple files at once.
Arguments (HTTP POST):
- cmd : upload
- target : hash of the directory to upload
- upload[] : array of multipart files to upload
- upload_path[] : (optional) array of target directory hash, it has been a pair with upload[]. (specified at folder upload)
- mtime[] : (optional) array of files UNIX time stamp, it has been a pair with upload[].
- name[] : (optional) array of files name for suggest, it has been a pair with upload[].
- renames[] : (optional) array of rename request filenames
- suffix : (optional) rename suffix
- hashes[hash] : (optional) array of hash: filename pairs
- overwrite : (optional) Flag to overwrite or save another name. If "0" is specified and the same name file exists, the connector should save the upload file as a different name.
Response: An array of successfully uploaded files if success, an error otherwise.
- added : (Array) of files that were successfully uploaded. Information about File/Directory
If the files could not be uploaded, also return warning.
- warning : (Array) of error messages like a errors
Chunked uploads
Chunking Extra arguments:
-
chunk : chunk name "
filename.[NUMBER]_[TOTAL].part
" - cid : unique id of chunked uploading file
-
range : Bytes range of file "
Start byte,Chunk length,Total bytes
"
Response:
- added : (Array) empty array
- _chunkmerged : (String) file name of server side. ONLY when the upload of all the chunk file has been completed.
- _name : (String) uploading file name. ONLY when the upload of all the chunk file has been completed.
Chunk merge request (When receive _chunkmerged
, _name
)
Extra arguments:
-
upload[] : Value of
_name
-
chunk : Value of
_chunkmerged
Response:
- added : (Array) of files that were successfully uploaded. Information about File/Directory
Returns the url of a file. This method is called if the initial value for the file's url is "1"
.
Arguments:
- cmd : url
- target : hash of file
- options[] : array of options (?)
Response:
- url: url of the file
- API >= 2.1012
Arguments:
- cmd : zipdl
- targets[] : array of hashed paths of the nodes
Response:
- zipdl array data for 2nd request
{
file: "5abf02cc77050", // key of temporary archive file
name: "Test here_Files.zip", // download file name
mime: "application/zip" // MIME type
}
Arguments:
- cmd : zipdl
- download : 1
- targets[0] : hash path for detect target volume drive (e.g. cwd hash)
- targets[1] : target temporary archive file key
- targets[2] : download file name
- targets[3] : MIME type
Response: RAW data of archive file with HTTP headers for download