Documentation

Integration

CKEditor Integration » Demo

To make KCFinder the default file manager for CKEditor you should edit config.js file located in the CKEditor's installation directory:

CKEDITOR.editorConfig = function(config) {
   config.filebrowserBrowseUrl = '/kcfinder/browse.php?opener=ckeditor&type=files';
   config.filebrowserImageBrowseUrl = '/kcfinder/browse.php?opener=ckeditor&type=images';
   config.filebrowserFlashBrowseUrl = '/kcfinder/browse.php?opener=ckeditor&type=flash';
   config.filebrowserUploadUrl = '/kcfinder/upload.php?opener=ckeditor&type=files';
   config.filebrowserImageUploadUrl = '/kcfinder/upload.php?opener=ckeditor&type=images';
   config.filebrowserFlashUploadUrl = '/kcfinder/upload.php?opener=ckeditor&type=flash';
};

Modify /kcfinder/ to match your KCFinder installation path. There is an option to apply this configuration using CKEditor's API. Refer to CKEditor documentation.

TinyMCE 4 Integration » Demo

In JavaScript sources which creates the editor you should add file_browser_callback function property into tinyMCE.init() object parameter:

tinyMCE.init({
//  ...
    file_browser_callback: function(field, url, type, win) {
        tinyMCE.activeEditor.windowManager.open({
            file: '/kcfinder/browse.php?opener=tinymce4&field=' + field + '&type=' + type,
            title: 'KCFinder',
            width: 700,
            height: 500,
            inline: true,
            close_previous: false
        }, {
            window: win,
            input: field
        });
        return false;
    }
//  ...
});

Replace /kcfinder/ with your path to KCFinder installation. Also you may change width and height properties.

Note that TinyMCE 4 integration is available since version 2.53!

TinyMCE 3 Integration » Demo

First, you should set _tinyMCEPath in KCFinder's config.php file, pointed to TinyMCE source directory (where tiny_mce_popup.js is located).

In JavaScript sources which creates the editor you should add file_browser_callback property in tinyMCE.init() object parameter:

tinyMCE.init({
//  ...
    file_browser_callback: 'openKCFinder'
//  ...
});

Now make a function named openKCFinder. Replace /kcfinder/ with your path to KCFinder installation. Also you may change width and height properties:

function openKCFinder(field, url, type, win) {
    tinyMCE.activeEditor.windowManager.open({
        file: '/kcfinder/browse.php?opener=tinymce&type=' + type,
        title: 'KCFinder',
        width: 700,
        height: 500,
        resizable: true,
        inline: true,
        close_previous: false,
        popup_css: false
    }, {
        window: win,
        input: field
    });
    return false;
}

FCKeditor Integration » Demo

Only versions 2.x of FCKeditor are supported! To make KCFinder default file manager for FCKEditor you should edit fckconfig.js file located in the FCKEditor's installation directory and change these settings:

FCKConfig.LinkBrowserURL = '/kcfinder/browse.php?opener=fckeditor&type=files';
FCKConfig.ImageBrowserURL = '/kcfinder/browse.php?opener=fckeditor&type=images';
FCKConfig.FlashBrowserURL = '/kcfinder/browse.php?opener=fckeditor&type=flash';
FCKConfig.LinkUploadURL = '/kcfinder/upload.php?opener=fckeditor&type=files';
FCKConfig.ImageUploadURL = '/kcfinder/upload.php?opener=fckeditor&type=images';
FCKConfig.FlashUploadURL = '/kcfinder/upload.php?opener=fckeditor&type=flash';

Modify /kcfinder/ to match your KCFinder installation path.

Custom Integration

Input Parameters

These are the GET paramaters you can add to the KCFinder URL. Example:

/kcfinder/browse.php?type=images&lang=bg&dir=images/public

The following table describes the input parameters you can use:

Name(s) Examplary Value Description
type images Selects the Type Directory you want to use. Allowed values are the keys of types setting. If you don't specify one or the specified Type Directory does not exist, KCFinder will choose the first defined type.
lng, lang, language, langCode or lang_code de Selects the language. If you don't specify a language or the relevant file does not exist, KCFinder will use English (en). If your language is missing you can create a new localization file using the online language files generator available here.
theme dark You can override theme setting (in config.php) using this parameter. If the theme is missing, KCFinder will ignore this parameter. This parameter is available since version 2.4.
dir images/public The initial folder which will be opened when KCFinder loads. It should contain the Type Directory at the beginning. If the folder does not exist or it is outside the Type Directory (using ../ and / prefixes), KCFinder will open the Type Directory root.
opener tinymce This parameter tells KCFinder which application it is opened from. Possible values are: ckeditor, fckeditor, tinymce, tinymce4, custom.
cms drupal If it's set for example to drupal, a file /kcfinder/integration/drupal.php will be executed first if it is exists. It is useful to integrate KCFinder with external user managment system.

Custom Applications

To link selected file(s) from KCFinder to your web applications, you should create window.KCFinder object and window.KCFinder.callBack() method for single file or window.KCFinder.callBackMultiple() for multiple files. To avoid collisions it's recommended to add the object and method when KCFinder loads and remove them once the file(s) are selected and KCFinder is closed. Examples:

function openKCFinder_singleFile() {
    window.KCFinder = {};
    window.KCFinder.callBack = function(url) {
        // Actions with url parameter here
        window.KCFinder = null;
    };
    window.open('/kcfinder/browse.php', 'kcfinder_single');
}
 
function openKCFinder_multipleFiles() {
    window.KCFinder = {};
    window.KCFinder.callBackMultiple = function(files) {
        for (var i; i < files.length; i++) {
            // Actions with files[i] here
        }
        window.KCFinder = null;
    };
    window.open('/kcfinder/browse.php', 'kcfinder_multiple');
}

The second parameter of window.open() defines the name of the opened popup window. If you are using multiple integrations on one page, it's recommended to use different window names. If you are using <iframe> tags instead of window.open(), the name attributes should be different. Currently KCFinder can be used only from one opened instance in one page at the same time. If you are using more than one integration in one page, you should not allow the opening of multiple KCFinder instances. See the demos: Textbox, Iframe, Image, Multiple files.

Session Configuration

You can configure KCFinder in your web application using the user session, but first you should synchronize session ini settings between your application and KCFinder.

If your application does not change the default session ini settings you don't have to synchronize anything. In this case you can leave all _session* settings in config.php file commented, but the _sessionVar setting should be uncommented.

In the other case you should check all session.* ini settings from your application and set them the same for KCFinder. To do this, I suggest using phpinfo() function, inserted in the place you want to configure KCFinder.

...
// Just display phpinfo() output
phpinfo();
...

...
// Write phpinfo() output to a file
ob_start();
phpinfo();
file_put_contents("/path/to/file.html", ob_get_clean());
...

Look at the "session" section of phpinfo() output. If there are some ini settings with "Local Value" different than "Master Value", you have to transfer local values of these settings to KCFinder PHP configuration.

IMPORTANT NOTE: If you have session.save_handler with local value "user", your application uses its own session save handler. You need to implement the same handler using session_set_save_handler() function in core/bootstrap.php file which contains an example handler class.

There are some ini settings you can set directly in config.php file: session.gc_maxlifetime, session.save_path, session.cookie_domain and session.cookie_path.

'_sessionLifetime' => 30, // In minutes
'_sessionDir' => "/path/to/session/files",
'_sessionDomain' => ".mysite.com",
'_sessionPath' => "/my/path",

If you don't want to set the ini settings in config.php or there are other session.* ini settings to transfer, you can set them by creating a .htaccess file in the KCFinder root folder. Example:

<IfModule mod_php5.c>
    php_value session.gc_maxlifetime 1800
    php_value session.save_path /path/to/session/files
    php_value session.cookie_domain .mysite.com
    php_value session.cookie_path /my/path
</IfModule>

Or you can do this using ini_set() function calls in core/autoload.php file:

ini_set('session.gc_maxlifetime', "1800");
ini_set('session.save_path', "/path/to/session/files");
ini_set('session.cookie_domain', ".mysite.com");
ini_set('session.cookie_path', "/my/path");

When synchronization is done, you can configure KCFinder from your application. For example you can configure upload directory for logged user in your web site:

$_SESSION['KCFINDER'] = array(
    'disabled' => false,
    'uploadURL' => "/users/" . $user['username'] . "/upload",
    'uploadDir' = ""
);

Making Special Directory Type

Special directory types (*img and *mime) are implemented as PHP classes located in core/types directory. To add new file type detection, the only thing you have to do is to make a class file in this directory. The name of the class should begins with "type_" followed by identification word, which can be used in types config setting. The filename should be the same as the class name plus .php. For example if you pick type_src for your class name, the filename should be type_src.php. Then you can define it in config.php like this:

'types' => array(
//  ...
    'sources' => "*src",
//  ...
),

The class should contain a public method checkFile(), which is called upon file upload event and should returns true if the file is verified or an error string if it's not. The method has two input parameters. The first one gets filename path of uploaded file. It's a temporary file path and its name is not like the real uploaded file. The second parameter is an array and gets KCFinder configuration settings. Two additional elements are added to the settings array - filename and params. The filename element contains the real filename of the uploaded file (only the filename without path!). The params element contains additional parameters right after *src if any. For example if your types setting is:

'types' => array(
//  ...
    'sources' => "*src php html",
//  ...
),

the params element will contain "php html". So let see some example code:

<?php
 
class type_src {
 
    protected patterns = array(
        'php' => '/\<\?php\s/si',
        'html' => '/\<[a-z]+\>/si',
        'css' => '/[^\{]+\s*\{\s*([a-z0-9]+\s*\:\s*[^\;^\}]+\s*\;?\s*)+\}/si'
    );
 
    public function checkFile($file, array $config) {
        $extension = file::getExtension($config['filename']);
 
        $params = strlen($config['params'])
            ? preg_split('/\s+/', $config['params'])
            : array_keys($this->patterns);
 
        $content = file_get_contents($file);
        foreach ($params as $param)
            if (isset($this->patterns[$param]) &&
                (strtolower($extension) == strtolower($param)) &&
                preg_match($this->patterns[$param], $content)
            )
                return true;
 
        return "Incorrect source type!";
    }
}
 
?>

This will check if the content of uploaded file matches to the defined regular expression patterns.

You may want to deny extension rename (denyExtensionRename config setting) if you want to relate the type to the file extension. Also you may want to set empty deniedExts for your type, because the example class will check the extension.

'types' => array(
//  ...
    'sources' => array(
        'type' => "*src php html",
        'denyExtensionRename' => true,
        'deniedExts' => ""
    ),
//  ...
),

Important notes:

  • The examples in this section are just to show you how to create special directory type. In some cases the use of the example class unmodified, could be dangerous! You should be more precise when defining regular expressions for file contents!
  • filename config element and denyExtensionRename config setting are available since version 2.41.