📦 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.