kukrik / qcubed-filemanager
QCubed-4 plugin for FileManager
Package info
github.com/kukrik/qcubed-filemanager
Language:JavaScript
Type:qcubed-library
pkg:composer/kukrik/qcubed-filemanager
Requires
- php: >=8.3
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-03 07:56:29 UTC
README
A file management solution built specifically for the QCubed-4 framework.
This plugin centralizes all uploaded files into a single location while automatically generating and maintaining derived image versions for efficient usage.
โ ๏ธ This is not a generic PHP file manager. It is designed specifically for QCubed-4.
โจ Features
-
Chunk upload (large file support)
-
Regular upload (fallback mode)
-
Automatic image resizing:
- large (max 1500px)
- medium (max 480px)
- thumbnail (max 320px)
-
WEBP support (GD-based)
-
File usage locking system (green / red / yellow indicators)
-
Multi-select file handling
-
Drag selection (mouse-based selection of multiple rows)
-
Toolbar-based file operations:
- Rename
- Crop
- Copy
- Move
- Delete
- Download
-
Breadcrumb navigation
-
Quick search
-
Multiple views:
- ImageListView
- ListView
- BoxView
-
CKEditor integration
-
MediaFinder integration
-
Database-backed file metadata
๐งฑ Architecture
The FileManager uses a predictable and maintainable structure:
upload/ โ original files (source of truth)
tmp/_files/
โโโ large/ โ resized images (โค1500px)
โโโ medium/ โ resized images (โค480px)
โโโ thumbnail/ โ resized images (โค320px)
โโโ temp/ โ temporary chunk upload files
โโโ zip/ โ temporary archives for download
Principles
- All original files are stored in one central location
- Resized files are generated separately
- Temporary folders must remain empty outside processing
- File operations stay synchronized across directories
๐ผ Image handling
Uploaded images are automatically resized:
| Folder | Max size |
|---|---|
| large | 1500px |
| medium | 480px |
| thumbnail | 320px |
Original files are always preserved in the upload/ directory.
๐ Database
Required tables:
foldersfiles
These are included in the package.
โ๏ธ Requirements
- PHP 8.3+
- QCubed-4
- GD extension
- WEBP support recommended
๐ Configuration
Verify directory paths in:
install/project/includes/configuration/active/2directories.cfg.php
Incorrect configuration will break uploads and file handling.
๐งช Usage
Navigation
- Double-click โ open folder
- Single-click โ select file or folder
Multi-selection
You can select multiple files in two ways:
-
Drag the mouse across rows (selection only)
-
OR use:
Cmd(Mac)Ctrl(Windows)
Operations
After selecting files, use toolbar buttons:
- Rename
- Copy
- Move
- Delete
- Download
๐ File usage indicators
| Color | Meaning |
|---|---|
| ๐ข Green | Free file |
| ๐ด Red | Locked (in use by another service) |
| ๐ก Yellow | Reserved / activity locked |
Controlled via activities_locked in the files table.
๐ Integrations
CKEditor
Allows:
- inserting images
- linking files
MediaFinder
Provides quick selection of files for content areas.
๐ฆ Upload system
Chunk upload (recommended)
- Handles large files
- Works better on slow connections
- Uses
.part*temporary files - Automatically merges chunks
Regular upload
- Simpler fallback
- Suitable for small files
๐ง Design philosophy
- Centralize all files
- Keep structure predictable
- Separate original and generated data
- Reflect real usage state in UI
- Avoid hidden file duplication
๐ Examples
Located in examples:
dialoog.phpfinder.php
Used mainly for popup integrations.
๐ผ Screenshots
FileManager
MediaFinder
CKEditor Integration
๐ฅ Installation
composer require twbs/bootstrap v3.3.7
composer require kukrik/qcubed-filemanager
composer require qcubed-4/plugin-bootstrap
composer require kukrik/bootstrap-filecontrol
composer require qcubed-4/plugin-ckeditor
composer require ckeditor/ckeditor
โ ๏ธ Notes
- Built specifically for QCubed-4
- Not framework-agnostic
upload/is the source of truth- Temporary folders must remain clean
๐ฌ Feedback
Suggestions and improvements are welcome.


