gamerz-file-explorer: Instructions file for Claude Code

CLAUDE.md

Guidance for working in the GaMerZ File Explorer codebase.

What this is

A single-directory PHP web app (no framework, no Composer, no database) that lists, searches, views, and downloads the contents of a configured root folder — styled like Windows Explorer. Procedural PHP, distributed as a set of files users drop into a web directory.

Layout

Every entry point starts with require 'config.php'; require 'settings.php'; require 'functions.php'; in that order.

Conventions

• PHP 8.1+, declare(strict_types=1), PSR-12, 4-space indent, short array syntax [], snake_case functions/vars, GFE_-prefixed SCREAMING_SNAKE constants, ' . $x . ' concatenation spacing throughout. .editorconfig and phpcs.xml.dist are authoritative.
• settings.php returns a settings array; entry points do $settings = require 'settings.php'; and pass it into the functions.php helpers. There is no shared global state.
• When outputting any dynamic value (filenames, paths, search terms, request values), escape it at the point of output with esc($value) — the functions.php helper for htmlspecialchars($value, ENT_QUOTES, 'UTF-8') (the only place that raw call should appear). Pass raw values to url() — it URL-encodes the path internally, so esc() the display copy rather than the raw value. url() can also return a ?by=&order= query string (a non-default sort), so also esc() its result wherever it lands in markup (an href), not just the display copy.
• urldecode() the incoming dir/file request values before using them and before the traversal check in index.php/view.php — reject any . or .. path segment (explode('/') then in_array) plus a literal //, so a bare .. with no trailing slash can't list the parent of the web root. Nice-URLs encode a space as +, which the web server passes as %2B; skipping the decode breaks paths with spaces (the 3.0.0 regression). Keep that decode-then-check order for any new path input.
• settings.php ignore lists keep internal files (config.php, functions.php, the Composer/PHPStan/PHPCS/PHPUnit files, the README/LICENSE/AGENTS.md/CLAUDE.md metadata, …) out of listings; add new internal files there. Hiding is not access control — the .htaccess/Nginx deny rules and the CLI-only guard in tests/ are what stop the web server serving dev/tooling files. Keep them in place.
• Frontend is Bootstrap 5.3 + Font Awesome 6 loaded from cdnjs with SRI hashes, no jQuery. If you bump a CDN version, update its integrity hash too.
• Custom styling and behaviour live in resources/style.css and resources/script.js, linked from functions.php with a ?v=GFE_VERSION cache-buster (resources/ is served statically and is in $ignore_folders). The stylesheet defines light/dark design tokens keyed off data-bs-theme and maps Font Awesome classes (.fa-file-pdf, .fa-folder, …) to category CSS variables; the script wires the three-way theme switch (data-gfe-theme, auto/light/dark, persisted to localStorage), the clickable rows, and highlight.js. The one inline script is the tiny theme-detection snippet in <head> that sets data-bs-theme before paint to avoid a flash — keep it inline. Keep style.css comment-free and bump GFE_VERSION for visible style changes (so the cache-buster updates).
• view.php embeds PDFs inline with <object> (with an open/download fallback for browsers that can't render it), and video/audio with <video>/<audio>. The PDF <object> needs the site CSP to allow object-src 'self'; <video>/<audio> rely on media-src. Only browser-playable $video_ext/$audio_ext embed; everything else downloads.