📦 PhPstrap — Project Structure Guide

A practical map of the folders and files that make up PhPstrap. This reflects the v0.1.3 changes: Bootstrap 5 defaults, a unified Admin Updater, and a single source of truth for versioning.

🗂️ Root (/)

• index.php — Front controller / landing page.
• install.php — Setup wizard entry point (Requirements → DB → Admin → Modules → Config → Done).
• .htaccess — Web server rules (friendly URLs, basic hardening). Updater can skip this by default.
• robots.txt — Crawl hints for search engines.
• maintenance.php — Optional maintenance page template.
• LICENSE, README.md — Project license and documentation.
• backups/ — Auto-created by the Updater before installs (safe to keep outside web root if possible).
• cache/
  • updates/ — Temporary ZIPs and extracted update trees used by the Updater.
• uploads/ — User-generated uploads (keep writable; never commit secrets here).
• logs/ — App/admin logs, rotation hints; protected via .htaccess.

🔧 /admin/

• dashboard.php — Admin overview.
• update.php — New unified Updater (Download → Preview → Install), with backups and safe skip lists. Reads config/version.php first, falls back to DB.
• users.php, invites.php, logs.php — User/admin management and logs.
• settings.php — Site & module settings UI.
• login.php / logout.php — Admin auth endpoints.
• includes/
  • admin-auth.php — Admin session guard (require admin).
  • admin-sidebar.php — Sidebar renderer used across admin pages.

🧱 /includes/

• settings.php — Get/set helpers for the settings table.
• modules.php — Module bootstrap & hook runner.
• header.php, footer.php, nav.php — Layout partials.
• header-scripts.php, footer-scripts.php — JS/CSS includes.

🛠️ /installer/

• requirements.php — PHP version & extension checks.
• database.php — Connection + schema install (with safe fallbacks).
• config.php — Writes core configs and helper files.
• ui.php — Updated installer UI (BS5) with step indicator; footer now reads version.php.

📊 /dashboard/

• index.php — User-facing dashboard (post-login, if used).

🎨 /assets/

• css/ — Bootstrap 5 & custom styles (e.g., admin.css, dashboard.css, homepage.css).
• js/ — bootstrap.bundle.min.js and app scripts.
• img/ — Static images, logos, icons.

🗃️ /config/

• app.php — App initialization (sessions, timezone, guardrails).
• database.php — PDO connection factory (reads install values).
• version.php — Single source of truth: PHPSTRAP_NAME, PHPSTRAP_VERSION, PHPSTRAP_BUILD. Read by installer and updater.
• functions.php — Common utilities (if present).

🧩 /modules/

• Each module lives in its own folder, e.g. /modules/hcaptcha/, /modules/smtp/, /modules/analytics/.
• module.json — Metadata + default settings (written by installer when selected).
• [name].php — Module class; can register hooks such as form_captcha or send_email.
• Optional docs (e.g. README.md, provider templates).

🌐 /lang/

• lang_en.php — Base language strings (generated by installer).

🧩 Legacy / compatibility

• /css/ — Legacy stylesheet location used in early builds. Prefer /assets/css/ going forward.

---

🔐 File Safety & Updates

• The Updater makes a timestamped backup in /backups/ before installing.
• By default it skips sensitive paths: config/, uploads/, logs/, cache/, .git/, .github/, installer/, plus files like config/database.php, config/app.php, index.php, .htaccess. You can opt-in to “Allow core overwrites” if needed.
• Version shown in Admin is read from config/version.php, with a DB fallback.

📌 Recommended Permissions

• Directories: 755
• Files: 644
• Writable by PHP (hosting-dependent): /uploads, /logs, /cache, /backups

---

Questions or ideas? Open an issue on GitHub.