5.4 KiB
5.4 KiB
phpfilebrowser — Project Instructions
Overview
Single-file PHP file browser. No external dependencies. Dark modern theme, responsive, mobile-optimized.
Architecture
phpfilebrowser/
├── AGENTS.md # This file — project state & agent instructions
├── index.php # Single-file application (PHP backend + CSS + JS inline)
└── .gitignore
Current State
Step 1 — Project Setup: completed (2026-06-09 16:30)
- ✅ Project directory created
- ✅ AGENTS.md created
- ✅ .gitignore created
- ✅ Git init + push to Gitea
Step 2 — PHP Backend: completed (2026-06-09 16:30)
- ✅ Directory listing via
?action=list&path=... - ✅ File download via
?action=download&file=... - ✅ Configurable ENTRY_POINT (default:
/tmp) - ✅ Path traversal protection (realpath + ENTRY_POINT prefix check)
- ✅ Metadata: name, type, size, modified
Step 3 — Frontend CSS: completed (2026-06-09 16:30)
- ✅ Dark theme with CSS variables (--bg-primary, --accent, etc.)
- ✅ Responsive table (columns hidden on small screens)
- ✅ Toolbar with nav buttons, breadcrumb, filter, sort selector
- ✅ Media overlay with backdrop blur
- ✅ Inline SVG file-type icons
- ✅ Custom scrollbar styling
- ✅ Mobile-first responsive breakpoints (768px, 480px)
Step 4 — Table & Sorting: completed (2026-06-09 16:30)
- ✅ Directory listing loaded via fetch()
- ✅ Sortable columns (name, date, size) with asc/desc toggle
- ✅ Directories always sorted first
- ✅ Sort state synced with dropdown selector
- ✅ Sort indicator arrows in headers
Step 5 — Filtering: completed (2026-06-09 16:30)
- ✅ Text filter with 150ms debounce
- ✅ Case-insensitive substring match
- ✅ Empty state with helpful message
Step 6 — Media Player Overlay: completed (2026-06-09 16:30)
- ✅ Image preview (img tag, object-fit: contain)
- ✅ Audio player (controls + autoplay)
- ✅ Video player (controls + autoplay)
- ✅ Close via button, backdrop click, or Escape key
- ✅ Media playback stops on close
Step 7 — Download Trigger: completed (2026-06-09 16:30)
- ✅ Non-media files trigger browser download
- ✅ PHP sets Content-Disposition header
- ✅ Client-side: dynamic element click
Step 8 — Browser Navigation: completed (2026-06-09 16:30)
- ✅ History stack for back/forward buttons
- ✅ URL reflects current directory via query params
- ✅ popstate listener for browser back/forward
- ✅ Breadcrumb navigation (clickable path segments)
- ✅ Nav buttons disabled at boundaries
Git Repository: completed
- ✅ Pushed to https://git.jlserver.de/JLtec/phpfilebrowser.git
- ✅ Commit:
7bb9b9b— feat: initial phpfilebrowser
Implementation Plan
Step 1: Project Setup
- Create project directory
- Create AGENTS.md
- Create .gitignore
- Git init, configure, push to Gitea
Step 2: PHP Backend (index.php — backend portion)
- Read directory contents (realpath-based, no traversal)
- Return JSON for current directory listing
- Handle relative path from query param (
?path=) - Return metadata: name, type (dir/file), size, modified date
Step 3: Frontend — CSS (dark, modern, responsive)
- Dark color scheme with CSS variables
- Responsive table layout (stack on mobile)
- Navigation bar with breadcrumb
- Back/Forward browser-style navigation buttons
- Filter input styling
- Media player overlay styling
- Sortable column headers with indicators
- File type icons (inline SVG)
Step 4: Frontend — Table & Sorting
- Render file/folder table from JSON data
- Clickable rows (folders navigate, files trigger action)
- Client-side sort by name, date, size (asc/desc)
- Sort state persisted in filter bar
Step 5: Frontend — Filtering
- Text filter input (substring match)
- Filter applied to table rows in real-time
Step 6: Frontend — Media Player Overlay
- Detect media file types (audio/video/image)
- Open overlay with embedded
<audio>,<video>, or<img> - Close button, backdrop click to close
- Overlay is large (centered, max-width constraint)
Step 7: Frontend — Download Trigger
- Non-media files trigger browser download
- PHP handles Content-Disposition header
Step 8: Browser Navigation
- Push state to history on directory change
- Back/Forward buttons in toolbar
- URL reflects current directory:
?path=/sub/dir
Completed
All 8 implementation steps done. Pushed to https://git.jlserver.de/JLtec/phpfilebrowser.git
Next Steps (Optional)
- Configure ENTRY_POINT to desired root directory
- Deploy to web server (Nginx/Apache)
- Add
.htaccessfor clean URLs - Add search-by-extension filter dropdown
- Add file permissions display
Agent Instructions
- Write code functionally: one feature at a time
- Verify each step works before moving to the next
- Use git commits after each completed step
- Keep everything in a single
index.php - All CSS and JS are inline in
index.php(no external files) - No external dependencies whatsoever (no CDNs, no npm, no frameworks)
- Use only PHP built-in functions (no composer)
- Use only vanilla JavaScript, CSS3, HTML5
- All SVG icons must be inline
- Follow the Dark modern design language throughout
Gitea
- Repository:
https://git.jlserver.de/JLtec/phpfilebrowser.git - API token in
~/.git-credentialsor usehttps://oauth2:<token>@git.jlserver.de