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