Files
phpfilebrowser/AGENTS.md
T
2026-06-09 16:30:51 +02:00

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 .htaccess for 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-credentials or use https://oauth2:<token>@git.jlserver.de