Coding Standards

VoltCMS Coding Standards

When you build your own CMS to save time on real projects, cleverness can quickly turn into maintenance pain later on. VoltCMS uses a clear, practical set of coding standards so every file feels familiar, works smoothly on ordinary shared hosting, and stays safe without bloated frameworks.

1. Built to Run Simply on Shared Hosting

Many modern web projects assume you have SSH terminal access, scheduled cron jobs, Composer packages, or JavaScript build tools. VoltCMS skips all of that so you can upload and run it on normal shared hosting without extra setup:

  • Stays Compatible with PHP 8.0: Code sticks to PHP 8.0 features and avoids newer 8.1+ syntax (such as readonly, enums, never, first-class callables, new in initialisers, or array_is_list), starting regular PHP files with declare(strict_types=1); right after <?php (except templates and views).
  • No Composer, No Build Step, No Heavy Framework: You do not need package managers or bundlers. The only external third-party library is Bootstrap loaded from a CDN, pinned to an exact version with a Subresource Integrity (SRI) hash.
  • No Shell or Cron Needed: Everything works using standard web requests and basic PHP extensions listed in the installer checklist.

2. Keeping Files & Folders Strictly Separated

Good boundaries prevent messy cross-dependencies and accidental data loss. In VoltCMS, every class lives in the Cms namespace—one class per file, with the filename matching the class name—and the autoloader checks core/engine/ first and then core/admin/:

Public vs. Admin Code

Classes in core/engine/ can run on public visitor pages, while core/admin/ is strictly for the admin area and is never required by public code (even post previews go through PublicApp rather than pulling admin code into public pages). Code inside core/ also never writes files back into core/.

Consistent File Formatting

Classes default to final unless genuinely extended, PHP-only files omit closing ?> tags, and files use UTF-8 without BOM, LF line endings, 4 spaces, single quotes where possible, short arrays, and trailing commas in multi-line arrays and argument lists.

3. Naming Rules You Don't Have to Guess

When you return to a project after weeks or months away, predictable names save mental energy. Here is how things are named across VoltCMS:

What It Is Naming Style Examples
Classes PascalCase ContentWriter, RateLimiter
Methods, properties & variables camelCase latestPublicArticles(), $userCache
Class constants UPPER_SNAKE_CASE MAX_BODY, PENDING_TTL
Template helper functions Short snake_case e(), url(), partial(), get_theme_url()
DB tables, columns, settings & config keys snake_case (tables use {p} prefix) {p}content_revisions, published_at, site_name, active_theme
Migrations NNNN_name.sql (4 digits, lowercase, forward-only) 0002_content.sql
Admin views snake_case in core/admin/views/ content_form.php
Theme templates, partials & URLs Lowercase with hyphens book-nav.php, page-about.php, /admin/content/12/revisions
Theme folders & test names Theme folder: a-z 0-9 - (max 39); Tests: plain words my-site; 'purge refused while a trashed child exists'

4. Keeping Logic, Database & Templates Clean

Instead of inventing extra layers or service containers, VoltCMS keeps each job in one clear place so the code stays easy to trace:

  • One Home per Job & No Over-Engineering: Core tasks map to dedicated classes (Config, Database, Router, Auth, Files, Logger, Env, and Sanitizer/e()), constructors accept dependencies like Database or ContentStore when helpful for testing (with App::db() as the shared request connection), and new classes are only created when two places need the same logic.
  • Controllers Coordinate, Workers Execute: Controllers (AdminApp, ContentAdmin, ThemeAdmin, PublicApp) decide what response to show (returning 0, 404, or 405 in admin and always returning after Response::redirect()), while worker classes like ContentWriter and ContentRepository do the heavy work. Content links always come from content_url($row) / Url::content($path) using content.path rather than slug alone.
  • Safe SQL, UTC Dates & Ordered Writes: Queries always run through Database with prepared statements and {p} prefixes, casting LIMIT/OFFSET to int and escaping !, %, and _ in LIKE searches with ESCAPE '!'. Timestamps are saved as UTC from PHP (gmdate('Y-m-d H:i:s')) instead of SQL NOW(), formatted for display via format_date() / iso_date() while keeping RSS and sitemaps in UTC. Multi-step updates use Database::transaction() (writing files last), using 0644 for web-server-served files and 0640 for other files.
  • Simple Templates & Public Theme API: Templates and views stay light—mostly loops, conditions, and = e(...) ?>—with business logic in classes, available variables noted at the top of the template, and theme API changes documented in THEME_GUIDE.md and CHANGELOG.md.

5. Security Habits, Admin UI, Error Handling & Testing

These day-to-day habits protect the site and keep changes trustworthy before they ever go live:

  • Escaping, CSP & Safe Paths: Print values with e() (only sanitised content bodies are printed raw), block inline scripts/handlers via CSP, never trust proxy headers for client IP, keep secrets out of logs/URLs, validate paths before touching disk, and route admin disk writes through ThemeFiles, MediaWriter, or CodeAssetStore using Files::writeAtomic().
  • Undo-Friendly Destructive Actions: Always favor recovery first—trash before delete, save a revision before overwriting, and archive before purging.
  • Smart Admin Pickers: Use AutocompleteField + LookupService for large record lists instead of giant <select> menus, write dependency-free scripts in core/admin/assets/ without using innerHTML for data (tested with jsdom in tests/js/), and always re-validate submitted IDs on the server.
  • Quiet Public Errors & Safe Logs: Engine classes throw exceptions that controllers turn into flash messages or error pages, public pages hide internal errors (display_errors off; debug only in user/config/app.php for development), Logger writes non-secret context arrays, and theme/partial hiccups degrade gracefully.
  • Testing & Definition of Done: Run php tests/run.php using isolated temp directories (plus a throwaway CMS_TEST_DB database and scratch HTTP tests), write tests for every bug fix and new rule, and finish changes by updating DATABASE_SCHEMA.md, THEME_GUIDE.md, CHANGELOG.md, and PROJECT_STATUS.md as needed.