docs: add README.md

This commit is contained in:
2026-06-10 11:31:12 +02:00
parent 38a976971d
commit 1c78f23b20
+115
View File
@@ -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
<?php
define('ENTRY_POINT', '/path/to/root/directory');
```
If no `config.php` exists, the default root is `/tmp`.
## Architecture
```
phpfilebrowser/
├── index.php # Single-file application (~1360 lines)
│ ├── PHP backend # API endpoints for listing, download, streaming
│ ├── CSS # Dark theme, responsive layout
│ └── JavaScript # Table rendering, sorting, filtering, navigation
├── config.php # Optional: set ENTRY_POINT (gitignored)
└── .gitignore # Excludes config.php
```
### API Endpoints
All endpoints are accessed through `index.php` via the `action` query parameter.
| Parameter | Description |
|-----------|-------------|
| `?action=list&path=<url-encoded-path>` | Returns a JSON array of directory entries |
| `?action=download&file=<url-encoded-file>` | Downloads a file with `Content-Disposition: attachment` |
| `?action=stream&file=<url-encoded-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