Simple PHP File Lister

A lightweight, zero-configuration PHP directory lister with a modern interface. Just drop index.php into any directory on a PHP-enabled server—it works immediately with no setup required.

<img width="842" height="942" alt="image" src="https://github.com/user-attachments/assets/a88b8572-6204-4d8b-9e4d-effaa9b9cf37" />

Features

- ✅ Zero configuration — works immediately - 📁 Directory navigation with breadcrumbs and pagination - ☑️ Multi-select — batch download or delete multiple files - 🔒 Security-hardened — protects against path traversal and code execution - 🎨 5 themes — Purple, Blue, Green, Dark, Light (user-switchable) - 🖼 File previews — hover to preview images/videos - 🎵 Built-in players — play audio and video files in-browser - 📤 File upload — drag-and-drop or button upload (optional) - ✏️ File management — rename, delete, create folders (optional) - 📦 ZIP downloads — download directories as ZIP files - 📱 Responsive design — works on desktop, tablet, and mobile - ⚡ Single file — no external dependencies except Font Awesome CDN

Quick Start

Requirements: - PHP 7.0+ (7.4+ recommended) - Web server with PHP support - Optional: ZipArchive extension for ZIP downloads

Installation: 1. Download index.php from releases 2. Copy it into the directory you want to list 3. Visit the directory in your browser

That's it! The file list renders automatically.

Customization

All settings are in the CONFIGURATION section at the top of index.php (lines 18-60). Open the file in a text editor to customize:

Display Settings:

$title = "Simple PHP File Lister";
$subtitle = "The Easy Way To List Files";
$footer = "Made with ❤️ by Blind Trevor";

Feature Toggles:

$enableRename = false;              // Rename files/folders
$enableDelete = false;              // Delete files/folders
$enableUpload = true;               // Upload files
$enableCreateDirectory = true;      // Create folders
$enableDownloadAll = true;          // "Download All as ZIP" button
$enableIndividualDownload = true;   // Individual file downloads

Themes:

$defaultTheme = 'purple';           // purple, blue, green, dark, light
$allowThemeChange = true;           // Let users change themes

Pagination:

$defaultPaginationAmount = 30;                 // Items per page (5, 10, 20, 30, 50, 'all')
$enablePaginationAmountSelector = true;        // Show pagination dropdown

Upload Settings:

$uploadMaxFileSize = 10  1024  1024;        // Max file size (10 MB)
$uploadMaxTotalSize = 50  1024  1024;       // Max batch size (50 MB)
$uploadAllowedExtensions = [];                 // [] = all except blocked

Advanced:

$includeHiddenFiles = false;        // Show hidden files (starting with .)
$zipCompressionLevel = 6;           // ZIP compression (0-9)
$showFileSize = true;               // Display file sizes
$showFolderFileCount = true;        // Display folder/file counts

Blocked Extensions: Edit the BLOCKED_EXTENSIONS constant to control which file types are hidden and blocked from download/upload (e.g., .php, .exe, .sh).

Security

SimplePhpFileLister prioritizes security:

- Path Traversal Protection — Uses realpath() validation, prevents ../ attacks - Code Execution Prevention — Blocks dangerous file extensions (.php, .exe, .sh, etc.) - Input Sanitization — All user inputs escaped with htmlspecialchars() - Security Headers — CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy - Hidden Files — Automatically excluded from listings (starting with .) - Secure Downloads — Content-Disposition headers, MIME type whitelisting - No Database — Single auditable file reduces attack surface

Key Features

Multi-Select: - Select multiple files/folders with checkboxes - Batch download as ZIP or batch delete - Displays selection count and total size

File Upload: - Drag-and-drop files anywhere on the page - Multi-file upload with progress feedback - Automatic duplicate handling - Size limits and file type restrictions

Media Players: - Audio — MP3, WAV, OGG, M4A, FLAC, AAC - Visual progress bars for audio playback - <img width="335" height="301" alt="image" src="https://github.com/user-attachments/assets/678d1780-d6c2-4f3b-8592-26929d982d91" /> - Video — MP4, WebM, OGV (fullscreen lightbox) - Hover over files to reveal play buttons - <img width="814" height="510" alt="image" src="https://github.com/user-attachments/assets/b470f8b5-122c-42ee-917e-1f9d3da9ae47" />

File Management: - Rename files/folders (configurable) - Delete files/folders (configurable, permanent) - Create new folders (configurable) - All operations include path validation and security checks

Themes

5 built-in themes available: - Purple (default) — Vibrant purple-magenta gradient - Blue — Fresh cyan-blue gradient - Green — Natural teal-green gradient - Dark — Sleek dark mode - Light — Minimal light theme

Users can switch themes via the floating palette icon (when $allowThemeChange = true). Preferences are saved in browser localStorage.

<img width="521" height="679" alt="image" src="https://github.com/user-attachments/assets/6ef3275f-e373-4b5f-b239-72b1d36c0d19" />

Notes

- No built-in authentication—use web server auth (.htaccess, HTTP Basic Auth) - Hover previews work on desktop only (disabled on touch devices) - Delete operations are permanent—no trash/recycle bin - Upload requires proper PHP configuration (upload_max_filesize, post_max_size) - Version info displayed in footer (auto-updated by GitHub Actions)

Version Management

This project uses automated semantic versioning: - Version location: APP_VERSION constant in index.php and footer - Auto-increment: PATCH version bumped on each merge to main - Manual updates: Edit APP_VERSION for MAJOR/MINOR changes - Releases: Auto-created on releases page - Skip versioning: Include [skip-version] in commit message

Updating

To update to a newer version: 1. Download new index.php from releases 2. Replace existing file 3. Re-apply your configuration settings (document them first!)

License

Free to use, modify, and redistribute.

---

Simple PHP File Lister • © Andrew Samuel 2026