docs: add README.md
This commit is contained in:
@@ -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
|
||||||
Reference in New Issue
Block a user