README

A modern, secure, and feature-rich PHP file manager with beautiful Bulma UI. Built for standalone use or seamless integration with frameworks like CodeIgniter 4.

🤖 Built with Antigravity - This project was developed using AI-assisted coding.

🛡️ Reporting Issues & Security Vulnerabilities

Caution

Found a security vulnerability? Please do NOT open a public issue. Instead, report it privately via GitHub Security Advisories so it can be addressed before public disclosure.

For bugs and feature requests, please open an issue on GitHub:

• 🐛 Report a Bug
• 💡 Request a Feature
• ❓ Ask a Question

✨ Features

File Operations

• 📁 Browse & Navigate - Intuitive directory browsing with breadcrumb navigation
• ⬆️ Upload Files - Drag-and-drop file uploads with progress indicators
• 📥 Download - Single file or multi-file download as ZIP
• ✏️ Rename - Quick inline renaming
• 🗑️ Delete - Single or bulk delete with confirmation modal
• 📋 Copy & Paste - Clipboard operations with cut/copy/paste
• 📦 Compress - Create ZIP archives from selected files

Multi-Select Operations

• ☑️ Checkbox Selection - Select multiple files with checkboxes
• 🎯 Select All - Quick select/deselect all items
• 🔧 Bulk Actions - Cut, copy, delete, download selected files

Drag & Drop

• 🎯 Drag to Move - Drag files/folders into other folders
• 🎨 Visual Feedback - Drop targets highlight during drag
• 📦 Multi-Drag - Select multiple items and drag them together
• ✅ Confirmation Modal - Preview move operation before confirming

Preview & View

• 🖼️ Image Preview - View images with dimensions
• 📄 Text/Code View - Syntax-highlighted code preview
• 📑 PDF Viewer - Inline PDF viewing
• 🍎 HEIC Support - Apple HEIC/HEIF image preview and dimensions

Security

• 🔐 Authentication - Built-in login with password hashing
• 🛡️ CSRF Protection - Token-based form protection
• 📂 Path Validation - Prevents directory traversal attacks
• ⚙️ Configurable Auth Bypass - Optional for framework integration

Modern UI

• 🎨 Bulma CSS - Clean, responsive design
• 🌙 Context Menu - Right-click actions
• 🔔 Toast Notifications - Non-intrusive feedback
• 📱 Responsive - Works on desktop and mobile

📸 Screenshots

🚀 Installation

Via Composer

composer require lifeishex/php-file-manager

Manual Installation

1. Clone or download the repository
2. Copy files to your project
3. Configure config.php

🔄 Updating Frontend Assets

Frontend libraries (Bulma, Font Awesome, Dropzone, SortableJS, Bulma Responsive Tables) are managed via npm. The compiled files are committed to the repo so no build step is needed for regular use.

To update a library

# 1. Install npm dependencies (first time only)
npm install

# 2. Edit the version in package.json, then:
npm install   # pulls the new version

# 3. Copy dist files into assets/
npm run build

# 4. Commit the updated assets/
git add assets/ package.json
git commit -m "chore: update <lib> to vX.Y.Z"

Current versions

Note: The node_modules/ directory is gitignored. Only the built files in assets/ are committed.

⚙️ Configuration

Create or modify config.php:

<?php
return [
    'fm' => [
        'root_path' => '/path/to/managed/files',
        'title'     => 'File Manager',
        'language'  => 'en',
        'date_format' => 'Y-m-d H:i',
        'show_hidden' => false,

        // Column visibility — cosmetic only, does NOT restrict operations
        'columns' => [
            'size'        => true,
            'owner'       => true,
            'modified'    => true,
            'permissions' => true,  // Hides the column, NOT the chmod button
        ],
    ],
    'auth' => [
        'require_login' => true,
        'username'      => 'admin',
        'password'      => password_hash('your-password', PASSWORD_DEFAULT),
    ],
    'upload' => [
        'max_file_size'      => 50 * 1024 * 1024,
        'chunk_size'         => 1 * 1024 * 1024,
        'allowed_extensions' => ['*'],
    ],
    'security' => [
        'csrf_enabled' => true,
    ],

    // Role-based access control — controls what users can DO
    'permissions' => [
        'default_role' => 'viewer',
        'roles' => [
            'admin'  => ['*'],
            'editor' => ['upload', 'download', 'delete', 'rename', 'new_folder', 'copy', 'move', 'view', 'view_pdf', 'extract', 'zip'],
            'viewer' => ['view', 'view_pdf', 'download'],
        ],
    ],
];

Column Visibility vs. Permissions — Key Difference

Important

These are two separate and independent settings. Do not confuse them.

Example scenarios:

• Hide the permissions column but still allow chmod → set columns.permissions = false, keep 'permissions' in the role's action list
• Show the permissions column but disallow chmod → set columns.permissions = true, remove 'permissions' from the role's action list
• Both hide the column AND disallow chmod → set columns.permissions = false AND remove 'permissions' from the role

🔧 Standalone Usage

<?php
require_once 'vendor/autoload.php';

use FileManager\FileManager;

$config = require 'config.php';
$fileManager = new FileManager($config);
$fileManager->run();

🔌 Framework Integration

CodeIgniter 4

<?php
// app/Controllers/FileManagerController.php
namespace App\Controllers;

use FileManager\Integration\FileManagerService;

class FileManagerController extends BaseController
{
    public function index()
    {
        $config = [
            'fm' => [
                'root_path' => WRITEPATH . 'uploads',
                'asset_path' => '/filemanager/assets',
            ],
            'auth' => [
                'require_login' => false, // Use CI4's auth
            ],
        ];
        
        $fileManager = new FileManagerService($config);
        return $fileManager->handleRequest();
    }
}

Dynamic Root Path

// Per-user file management
$config['fm']['root_path'] = WRITEPATH . 'uploads/user_' . session()->get('user_id');

📋 Requirements

• PHP 8.3+
• ext-zip - For multi-file ZIP downloads
• ext-mbstring - For proper string handling

Optional: HEIC Image Support

HEIC/HEIF files (Apple format) can be previewed in the file manager if a suitable conversion tool is available on the server. The file manager detects tools automatically — no configuration needed.

Note: On Ubuntu, the default apt install imagemagick package (ImageMagick 6) may not include HEIC support. If HEIC conversion fails, verify with: convert -list format | grep HEIF If not listed, install a version compiled with libheif:

sudo apt install imagemagick libheif-dev

Graceful degradation: If no HEIC tool is found, the file manager still works normally — HEIC files can still be uploaded, downloaded, renamed, and deleted. Only the inline preview will be unavailable.

🤝 Contributing

Contributions are welcome! This is an MIT-licensed open-source project.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Mahdi Hezaveh

• GitHub: @LifeIsHex

⭐ Support

If you find this project useful, please consider giving it a ⭐ on GitHub! Your support helps the project grow and motivates continued development.