novaconium/README.md

novaconium

A tiny, Hugo-flavored PHP micro-framework. Routes are directories on disk, pages render with Twig, and any page that needs real logic gets an optional PHP "sidecar" file. Pages without a sidecar are pre-rendered once and served as static HTML straight from Apache afterwards. No Composer — Twig is vendored directly into the repo as plain source files.

Features

• File-based routing — a directory under App/pages/ is a route (Hugo-style page bundles). No route table to maintain.
• [param] segments — a directory literally named [param] (e.g. App/pages/products/[id]/) captures any single URL segment into $params['param'] for clean URLs, no query strings.
• Optional PHP "sidecars" — drop an index.php next to any index.twig to supply Twig context data, or return a Response (redirect/JSON/XML/HTML) to short-circuit templating entirely.
• Static caching, zero config — sidecar-less pages render once and are written to public/cache/; .htaccess serves the cached file directly on every later hit, skipping PHP and Twig entirely.
• Override-by-path — App/ (your project) is checked before novaconium/ (the framework defaults) for every page, layout, Lib\ class, and even the Sass color palette (App/sass/_colors.sass). Drop a file at the same relative path to override it; nothing needs duplicating to get a working site.
• Layout inheritance — _layout/layout.twig directories are resolved by walking upward from the matched page, so you can override the layout for a whole subtree.
• SEO boilerplate out of the box — the default layout ships meta description, canonical link, robots, Open Graph, and Twitter Card tags, all overridable per-page via Twig blocks.
• Built-in Matomo analytics — set matomo_url and matomo_site_id in App/config.php to enable tracking site-wide, including automatic 404 tracking. Off by default.
• Admin authentication — gate every /admin/* route behind a session login with multi-user management: a SQLite-backed users table, /admin/login//admin/logout, and an /admin/users page to create, disable, delete, group, promote/demote, and change the email or password of accounts (plus a novaconium/bin/create-admin-user.php CLI for the first user or deploy scripts). Two roles: the first user created is the admin; everyone after is a registered user with an optional group. Every account has a unique, normalized email address — groundwork for email verification later. Enabled with a single admin_auth_enabled flag in App/config.php; off by default, and reusable for any admin page a project adds later.
• Access control — assign a page (or a section, one line per page) to a user or group from its sidecar: Access::require('group:members') returns null or a ready-made Response (login redirect with a return path, or a 404 for the wrong account). Public is the default — a sidecar that never calls it is untouched, and static (sidecar-less, cached) pages are always public by construction. Gated pages stay out of /search and /sitemap.xml automatically.
• Draft pages — list a route under draft_routes in App/config.php to make it visible only to an authenticated admin; anyone else gets a plain 404, not a login prompt. Reuses the admin auth check directly, and is excluded from static caching so a cached copy can't leak the draft to the public. See /admin/docs/drafts.
• Dark/light theme toggle — a nav button flips a data-theme attribute (persisted to localStorage) that swaps every color via CSS custom properties; both palettes live in App/sass/_colors.sass, same override mechanism as everything else.
• Self-hosted spam prevention & form validation — Lib\SpamGuard, a reusable class for any form: a CSS-hidden honeypot field plus a submission-timing check, no external CAPTCHA service, site key, or outbound API call. Pairs with Lib\FormValidator (accumulating required-field/email/length checks) and Lib\Validate (the underlying validation primitives — email, length, phone, postal/zip, spam-word checks). All three ship in novaconium/lib/, demonstrated on the contact form.
• Form security by default — Lib\Input, a cleaning accessor for $_POST/$_GET (defense-in-depth against HTML/script injection, not a substitute for parameterized queries), and Lib\Csrf, standalone session-token CSRF protection called directly from a sidecar. Both ship in novaconium/lib/, wired into the contact form, /admin/clear-cache, /admin/login, and /admin/users.
• SQLite/MySQL database, zero setup — Lib\Db, a thin PDO wrapper (no ORM) supporting multiple named connections open at once — e.g. this site's own SQLite data plus a MySQL connection to a legacy database, usable in the same sidecar — each with its own plain-SQL migration convention, applied automatically on first use or via php novaconium/bin/migrate.php. SQLite data lives in a project-owned top-level data/ directory, outside both public/ and novaconium/. See /admin/docs/database.
• Sessions with flash data — Lib\Session, a thin wrapper around native PHP sessions with CodeIgniter-style flash values (set now, readable on exactly the next request) for post/redirect/GET flows without a query-string flag. Lazy-start, same mechanism Lib\Csrf already uses. See /admin/docs/session.
• Content index: sitemap, search, tags — /sitemap.xml, full-text /search (SQLite FTS5), and blog tag browsing all share one crawler that renders every page and harvests keywords/tags/changefreq/priority Twig blocks via Twig's own renderBlock() — no front-matter, no separate metadata files. Off by default (depends on SQLite); reindexes lazily on demand or via php novaconium/bin/index-content.php. See /admin/docs/content-index.
• Blog RSS feed — /blog/feed, built from the same hand-written post list App/pages/blog/index.php itself renders from, so it works with no database at all. Lib\Rss (a small RSS 2.0 envelope builder) also backs a per-tag feed, /blog/tag/<tag>/feed, once the content index above is enabled. Auto-discovered via a <link rel="alternate"> on /blog/* pages.
• Syntax-highlighted code blocks — vendored highlight.js colors PHP/Bash/HTML code blocks site-wide, auto-detected with no per-block markup, swapping between dark (ir-black) and light (github) themes along with the existing dark/light toggle. Twig-syntax samples (which highlight.js can't parse) are left plain rather than colored wrong. See /admin/docs/upgrading-highlightjs.
• No build step, no Composer — clone it, point Apache (or php -S) at public/, and it runs. Twig is vendored as source; see /admin/docs/upgrading-twig for upgrading it.

Getting started

Requirements: PHP 8.1+ (uses readonly constructor-promoted properties) with the pdo_sqlite extension (bundled with PHP, just needs to be enabled — no separate install; add pdo_mysql too if using a MySQL connection), and, for production, Apache with mod_rewrite and AllowOverride All. The content index's search (/admin/docs/content-index) additionally needs SQLite's FTS5 extension, bundled with pdo_sqlite on virtually every modern PHP build — only relevant if content_index_enabled is turned on.

Run it locally (no Apache needed)

php -S 127.0.0.1:8000 -t public public/router.php

public/router.php is a dev-only script that mimics the .htaccess rules (canonical redirects + static cache lookup) so you can develop without Apache. It is never used in production — Apache reads public/.htaccess directly.

Visit http://127.0.0.1:8000/ for the static home page, then click around — /about, /blog/hello-world, /contact, and /admin (cache clearing + these same docs, rendered live) are all included as working examples.

Deploy on Apache

Point the vhost's document root at public/, make sure mod_rewrite is enabled and AllowOverride All is set for that directory so public/.htaccess takes effect, and it just works — no build step required.

Run it in Docker

docker compose up --build

Builds an Arch Linux-based Apache/PHP image and serves the site at http://localhost:8080/. Three named volumes (cache, data, images) keep the page cache, SQLite database, and a reserved-for-later images directory out of paths the "Updating the framework" workflow below would wipe; App/ is baked into the image but can be bind-mounted for edits without a rebuild. See Docker for details.

Starting a new project

Clone this repo and drop its Git history — no Composer scaffold or installer:

git clone --depth 1 <novaconium-repo-url> my-new-project
cd my-new-project
rm -rf .git && git init && git add -A && git commit -m "Initial commit from novaconium template"

Then replace the example content under App/pages/ with your own; leave novaconium/ and public/ alone.

Updating the framework

Since the framework core lives entirely under novaconium/, pick up a new release by overwriting just that directory against a tag and committing the diff:

git clone --depth 1 --branch <release-tag> <novaconium-repo-url> /tmp/nova-update
rm -rf novaconium && cp -r /tmp/nova-update/novaconium ./novaconium && rm -rf /tmp/nova-update
git add novaconium && git commit -m "Update novaconium framework to <release-tag>"

Safe by construction — App/ always overrides novaconium/, so an update can't clobber project customizations. See Getting started for the full write-up.

Add a page

Create a directory under App/pages/ with an index.twig — the directory path is the URL:

App/pages/pricing/index.twig   ->   /pricing

Add an index.php next to it if the page needs data or logic. See Sidecars in the docs for the full contract, or SEO for a ready-to-paste starter template with every overridable block — or skip the copy-paste and scaffold it:

php novaconium/bin/create-static-page.php blog/my-new-post

Documentation

The full framework documentation — routing, sidecars, libraries, database, session, content index, XML sitemap, RSS feeds, layouts, static caching, SEO, Matomo analytics, admin authentication, draft pages, styling, project layout, and third-party notices — lives at /admin/docs on any running instance (so it travels with the code, no internet connection needed). Highlights:

• Getting started
• Docker
• Routing
• Sidecars
• Libraries
• Database
• Session
• Content index
• XML sitemap
• RSS feeds
• Layouts
• Static caching
• SEO
• Matomo
• Admin authentication
• Access control
• Draft pages
• Styling
• Project layout
• Third-party

AGENTS.md is the short, agent-facing version for coding assistants working in this repo, and novaconium/ISSUES.md is the roadmap/backlog.

Project layout

App/            your project — pages/ (routes), lib/ (Lib\ classes), sass/ (color overrides) — the only directory you're expected to edit
public/         Apache document root — front controller, .htaccess, static cache, compiled CSS
novaconium/     the framework itself — router, renderer, vendored Twig, default pages/lib/sass — not edited per-project

See Project layout for the full tree with every file explained.

Third-party

Twig is vendored in source form under novaconium/vendor/twig/ (no Composer — see /admin/docs/upgrading-twig for how to upgrade it). It's BSD-3-Clause licensed; the full license text ships alongside it at novaconium/vendor/twig/LICENSE.