Documentation

Installation

  1. Copy the distribution files to your web server inside the /kcfinder directory or any other directory in your web site.
  2. Create a directory in the server to hold all uploaded files. By default, KCFinder is configured to use the /kcfinder/upload/ directory.
  3. Make the above upload directory writable by the web server. On Linux, chmod it to 0777.
  4. On 3.x versions there is /kcfinder/cache directory. If you plan to modify CSS and JavaScript code or create a new theme, you should make this directory and its files (excluding .htaccess) writable by the web server.

Configuration

KCFinder settings are located in conf/config.php file organized as associative array. The keys of the array are the names of the settings. The settings which names doesn't begin with underscore can be overridden with an user session. I'll call them Dynamic Settings. The dynamic settings must not be commented or removed from the conf/config.php file. If you are upgrading KCFinder please check the new conf/config.php file for new dynamic settings which should be added to your old configuration file. The other kind of settings, which names begin with underscore, cannot be overridden by an user session, I'll call them Static Settings.

Dynamic Settings

'disabled' => true,

By default KCFinder is disabled. If you just set this setting to false all public visitors can upload and manage files on your web site. It is recommended to override this setting with sesssion configuration so only authenticated users can use KCFinder.

'denyZipDownload' => false,

KCFinder allows downloading folders or the files in your clipboard as a ZIP file. To use this functionality PHP ZIP extension should be available on your server. If you store big files, as movies or ISO images, creating such huge archive can cause problems with your server. To disable downloading multiple files as a single ZIP archive, you should set this setting to true.

'denyUpdateCheck' => false,

If you set this to true, online checking for new version in "About" box will not appear.

'denyExtensionRename' => false,

This setting is used to forbid the changing of file's extensions. If this option is set to true and an user tries to rename the file extensions, a warning message will appear and the operation will be canceled.

'theme' => "default",

The visual theme of KCFinder. Pick one from the themes directory.

'uploadURL' => "upload",

URL path to main directory for file uploads. In the example above the path is relative to KCFinder main directory. Other examples:
/files/upload - relative to the site root
../upload - 'upload' directory located in KCFinder parent directory
httр://yourdomain.com/upload - absolute URL path.

'uploadDir' => "",

This setting is used when KCFinder can't automatically detect its local filesystem path to the folder specified in uploadURL setting. Change this setting when KCFinder can't fetch the local filesystem path automatically.

'dirPerms' => 0755,
'filePerms' => 0644,

Default filesystem permissions for new files and directories created with KCFinder. Windows servers will skip these settings.

'access' => array(
 
    'files' => array(
        'upload' => true,
        'delete' => true,
        'copy' => true,
        'move' => true,
        'rename' => true
    ),
 
    'dirs' => array(
        'create' => true,
        'delete' => true,
        'rename' => true
    )
),

Defines user's write permissions for files and directories.

'deniedExts' => "exe com msi bat cgi pl php phps phtml php3 php4 php5 php6 py pyc pyo pcgi pcgi3 pcgi4 pcgi5 pchi6",

Global denied file extensions list. Will be checked when the user uploads or renames a file.

'types' => array(
   // The folowing directory types are just for an example
   'files'     => "",
   'flash'     => "swf",
   'media'     => "swf flv avi mpg mpeg qt mov wmv asf rm",
   'misc'      => "! pdf doc docx xls xlsx",
   'images'    => "*img",
   'mimages'   => "*mime image/gif image/png image/jpeg",
   'notimages' => "*mime ! image/gif image/png image/jpeg"
),

The Directory Types represented as associative array. The keys of the array defines directory names of the types. These directories will be created in the main upload directory. The values of the array defines the type of the files which can be uploaded in each directory. If the value is an empty string (Example: files), files of any type can be uploaded. There are three different value formats you can use:

  1. Space separated list of allowed extensions. (Example: media)
  2. Denied files extension list - space separated list that begins with "!" character. (Example: misc)
  3. Special types - types that begin with "*" character.
    • *img - Images which can be handled by image drivers configured with imageDriversPriority setting. (Example: images)
    • *mime - List of allowed MIME types. Works only if Fileinfo PHP extension is available. (Example: mimages)
    • *mime ! - List of denied MIME types. (Example: notimages)
    Read this to learn how to make a custom special type.

You can define some of the dynamic settings to a Directory Type. To do this you should modify the schema of the types array by changing the values from string to associative array. The element with key type defines the types of files which can be uploaded, any other key defines specific Directory Type setting. Example:

'types' => array(
 
    'files' => array(
        'type' => "",
        'thumbWidth' => 100,
        'thumbHeight' => 100
    },
 
    'flash' => array(
        'type' => "swf",
        'denyZipDownload' => true
    },
 
    'images' => array(
        'type' => "*img",
        'thumbWidth' => 150,
        'thumbHeight' => 150
    )
 
),

The settings you can use for Directory Types are: disabled, theme, dirPerms, filePerms, denyZipDownload, denyExtensionRename, access, deniedExts, filenameChangeChars, dirnameChangeChars, maxImageWidth, maxImageHeight, thumbWidth, thumbHeight, jpegQuality and watermark.

'filenameChangeChars' => array(
    " " => "_",
    ":" => "."
),

This setting defines characters or strings that will be automatically replaced in file names during file upload or rename. This is useful for SEO purposes. In the example above all spaces in filenames will be changed to underscores and all ":" to "."

'dirnameChangeChars' => array(
    " " => "_",
    ":" => "."
),

Same as filenameChangeChars setting but related to directories creation and renaming.
By default these two settings are empty arrays with commented elements inside. If you want to use them, you should remove the comments.

'mime_magic' => "",

Full path to magic file. This setting is related to *mime Special Directory Type. If you don't wish to use MIME type detection, you could skip this setting. The magic file must be on local filesystem. If you leave this setting empty the default magic file will be loaded. Default magic file path depends on your server's platform and on some platforms it is not defined (usually /usr/share/misc/magic).

'maxImageWidth' => 0,
'maxImageHeight' => 0,

Maximum image width and height. If uploaded image resolution exceeds these settings it will be automatically resized. If both are set to zero, images will not be resized. If one of these settings is set to zero, the image will be proportionally resized to fit the other setting.

'thumbWidth' => 100,
'thumbHeight' => 100,

Resolution for the generated thumbnail images.

'thumbsDir' => ".thumbs",

Thumbnails directory location, relative to main upload directory. If it does not exists KCFinder will automatically create it.

'imageDriversPriority' => "gmagick imagick gd",

Space separated image drivers. Only first working one will be used for image manipulations.

'jpegQuality' => 90,

JPEG compression quality of thumbnails and resized images.

'watermark' => "images/pngfile.png",

Places a watermark on the uploaded images. The path to the image is KCFinder relative. The watermark will be placed on bottom-right corner. There is extended setting definition:

'watermark' => array(
    'file' => "images/pngfile.png",
    'left' => null,
    'top' => true
),

In this example the watermark will be placed at top of the uploaded images, center alligned. left and top elements could be true, false, null or integer value. null means center align. The integer value is offset in pixels. The watermark will not be applied when:

  • the watermark config setting is missing;
  • the watermark config setting is false or empty string;
  • the watermark file does not exist or it's not an image;
  • the watermark is bigger than the image or it is outside.

'cookieDomain' => "",
'cookiePath' => "",

Domain and path, cookies will be sent to. If the cookieDomain is empty the domain from the browser URL will be used. If the cookiePath is empty, root ("/") path will be used. See _sessionDomain and _sessionPath settings for example.

'cookiePrefix' => 'KCFINDER_',

Cookie names prefix to prevent collisions with other integrated applications.

Static Settings

'_normalizeFilenames' => false,

If it is set to true all accented characters from the file and directory names will be replaced width simple latin letter equivalents, and all special characters will be removed. This transformation will be executed upon upload and rename. Useful when your filesystem is not Unicode compatible.

'_check4htaccess' => true,

Whether to check for .htaccess file in the main upload folder. If it is set to true and the file does not exist, KCFinder will try to create it. This is useful to prevent script executions from the upload directory.

'_tinyMCEPath' => "/tiny_mce",

Path to TinyMCE 3 sources. For more information check TinyMCE 3 Integration.

'_sessionVar' => "KCFINDER",

Name of the session variable to store the session configuration. This session variable can be set by integrating application to configure KCFinder before its opening. It should contain an array with dynamic settings. The settings which don't exists in the array will use their values set in conf/config.php file. For example, to enable KCFinder you should execute from your application:

$_SESSION['KCFINDER'] = array(
    'disabled' => false
);

Read Integration » Session Configuration for more information.

'_sessionLifetime' => 30,

Defines inactive user session lifetime in minutes. This setting needs _sessionDir to be set, otherwise other web scripts on your site can remove user sessions earlier. If you leave this setting commented the default session.gc_maxlifetime ini seting will be used.

'_sessionDir' => "/full/path/to/directory"

Full path to directory where user sessions are saved. Make sure that the web server has read and write permissions for this directory. If you leave this setting commented the default session.save_path ini setting will be used.

'_sessionDomain' => ".mysite.com",
'_sessionPath' => "/my/path",

The session will be valid for the domain and path set in these settings. In the example above, the session will be valid for *.mysite.com/my/path. If you leave this settings commented the default session.cookie_domain and session.cookie_path ini settings will be used.

'_cssMinCmd' => "java -jar /path/to/yuicompressor.jar --type css {file}",
'_jsMinCmd' => "java -jar /path/to/yuicompressor.jar --type js {file}",

If you don't plan to modify CSS or JavaScript code you can safely leave these two settings commented. Otherwise you can set up JavaScript and CSS compressor on the fly. The compressed code is placed in /kcfinder/cache directory. Make sure this directory and its content (excluding .htaccess file) are writable by the web server. If not, the cache never will be updated and your code changes will be ignored.

If the chache directory is writable, and you leave these settings commented and modify CSS or JavaScript code, the joined code will be stored uncompressed.