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,newin initialisers, orarray_is_list), starting regular PHP files withdeclare(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, andSanitizer/e()), constructors accept dependencies likeDatabaseorContentStorewhen helpful for testing (withApp::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 (returning0,404, or405in admin and always returning afterResponse::redirect()), while worker classes likeContentWriterandContentRepositorydo the heavy work. Content links always come fromcontent_url($row)/Url::content($path)usingcontent.pathrather than slug alone. -
Safe SQL, UTC Dates & Ordered Writes: Queries always run through
Databasewith prepared statements and{p}prefixes, castingLIMIT/OFFSETtointand escaping!,%, and_inLIKEsearches withESCAPE '!'. Timestamps are saved as UTC from PHP (gmdate('Y-m-d H:i:s')) instead of SQLNOW(), formatted for display viaformat_date()/iso_date()while keeping RSS and sitemaps in UTC. Multi-step updates useDatabase::transaction()(writing files last), using0644for web-server-served files and0640for 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 inTHEME_GUIDE.mdandCHANGELOG.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 throughThemeFiles,MediaWriter, orCodeAssetStoreusingFiles::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+LookupServicefor large record lists instead of giant<select>menus, write dependency-free scripts incore/admin/assets/without usinginnerHTMLfor data (tested with jsdom intests/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_errorsoff;debugonly inuser/config/app.phpfor development),Loggerwrites non-secret context arrays, and theme/partial hiccups degrade gracefully. - Testing & Definition of Done: Run
php tests/run.phpusing isolated temp directories (plus a throwawayCMS_TEST_DBdatabase and scratch HTTP tests), write tests for every bug fix and new rule, and finish changes by updatingDATABASE_SCHEMA.md,THEME_GUIDE.md,CHANGELOG.md, andPROJECT_STATUS.mdas needed.