From 1c78f23b20fb158ea8aa2efcd53fd5ce1bff5ec2 Mon Sep 17 00:00:00 2001 From: Hermes Bot Date: Wed, 10 Jun 2026 11:31:12 +0200 Subject: [PATCH] docs: add README.md --- README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..220fd3d --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +# phpfilebrowser + +Single-file PHP file browser with a modern dark theme. No external dependencies — no CDN, no frameworks, no build step. Everything lives in one `index.php`: PHP backend, CSS, and JavaScript. + +## Features + +- **Directory listing** — recursive navigation with back/forward buttons and clickable breadcrumbs +- **Sortable table** — sort by name, date, or file size (ascending/descending); directories are always grouped first +- **Client-side filtering** — debounced text search across file and folder names +- **Media preview** — images, audio, and video files open in a full-screen overlay with playback controls and seek support +- **File download** — non-media files trigger a browser download via the PHP backend +- **Responsive design** — adapted for desktop and mobile, with adaptive column visibility on small screens +- **Browser history** — directory navigation is tracked in the browser history; back/forward buttons work as expected + +## Requirements + +- PHP 7.4+ (uses only built-in functions: `opendir`, `finfo`, `realpath`, `pathinfo`, etc.) +- Any modern browser (Chrome, Firefox, Safari, Edge) +- A web server with PHP support (Nginx, Apache, or PHP's built-in server) + +## Installation + +### 1. Deploy + +Copy `index.php` (and optionally `config.php`) to a directory accessible by your web server. + +```bash +# Example: PHP built-in server (for testing) +php -S localhost:8080 index.php +``` + +### 2. Configure (optional) + +Create `config.php` in the same directory as `index.php` to set a custom root: + +```php +` | Returns a JSON array of directory entries | +| `?action=download&file=` | Downloads a file with `Content-Disposition: attachment` | +| `?action=stream&file=` | Streams a file with correct MIME type; supports Range requests for seeking | + +**Example — list a directory:** + +``` +GET /index.php?action=list&path=/photos/vacation +``` + +**Response:** + +```json +[ + { + "name": "beach.jpg", + "type": "file", + "size": 2468000, + "modified": "2026-06-01 14:32:00", + "path": "/var/www/files/photos/vacation/beach.jpg" + }, + { + "name": "logs", + "type": "dir", + "size": null, + "modified": "2026-06-08 09:15:00", + "path": "/var/www/files/photos/vacation/logs" + } +] +``` + +## Supported Media Types + +| Type | Extensions | +|------|-----------| +| Images | `jpg`, `jpeg`, `png`, `gif`, `webp`, `svg`, `bmp`, `ico`, `tiff`, `avif` | +| Audio | `mp3`, `ogg`, `wav`, `flac`, `aac`, `wma`, `opus`, `m4a` | +| Video | `mp4`, `webm`, `ogg`, `mov`, `avi`, `mkv`, `m4v` | + +## Design + +- **Theme**: Dark mode with CSS custom properties (GitHub-inspired palette) +- **Layout**: Flexbox-based, fixed toolbar with scrollable file table +- **Icons**: Inline SVG file-type icons (no external font or image files) +- **Responsiveness**: Columns hidden progressively on smaller viewports (768px, 480px breakpoints) + +## Security + +- **Path traversal protection**: `realpath()` resolves the full path and verifies it stays within `ENTRY_POINT` +- **No SQL**: Pure file-system access, no database layer +- **No external requests**: All assets are self-contained in the single file + +## License + +MIT