4lt/novaconium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 11 Wiki Activity

Replace v1 with v2 codebase

Browse Source 
Full rewrite: swap out the v1 framework (src/, controllers/, views/,
twig/, sass/, skeleton/) for the working v2 codebase from phpproject
(App/, novaconium/, public/).
This commit is contained in:
code
2026-07-14 01:58:25 +00:00
parent d9c4b64d9c
commit fbd4e92e9f
460 changed files with 30107 additions and 4661 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+59 -40
View File
@@ -1,65 +1,84 @@
![Novaconium PHP](/_assets/novaconium-logo.png)
# novaconium
# Novaconium PHP: A PHP Framework Built from the Past
A tiny, Hugo-flavored PHP micro-framework. Routes are directories on disk, pages render with [Twig](https://twig.symfony.com/), 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.
NovaconiumPHP is a high-performance PHP framework designed with inspiration from classic coding principles.
## Features
Pronounced: Noh-vah-koh-nee-um
- **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 HTTP Basic Auth by setting `admin_username`/`admin_password_hash` in `App/config.php`; reusable for any admin page a project adds later, with a `/admin/logout` link to clear cached credentials and a built-in `/admin/password-hash` form so generating the hash doesn't require the CLI. Off by default.
- **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`, and `/admin/password-hash`.
- **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.
* Packagist: https://packagist.org/packages/4lt/novaconium
* Master Repo: https://git.4lt.ca/4lt/novaconium
## Getting started
## Getting Started
**Requirements:** PHP 8.1+ (uses `readonly` constructor-promoted properties) and, for production, Apache with `mod_rewrite` and `AllowOverride All`.
Novaconium is designed to be developed primarily using Docker. Instead of relying on tools installed directly on your system, common development tasks are executed inside containers:
### Run it locally (no Apache needed)
* Composer runs inside a Docker container rather than on your host machine
* Apache / PHP are served from containers instead of your local environment
* Sass compilation is also handled within a container
```
php -S 127.0.0.1:8000 -t public public/router.php
```
As long as you have Docker installed, you can use the full development environment without installing additional dependencies on your system.
`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.
You can [learn more about how novaconium works with composer](https://git.4lt.ca/4lt/novaconium/src/branch/master/docs/Composer.md).
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.
```bash
PROJECTNAME=novaproject;
mkdir -p $PROJECTNAME/novaconium;
cd $PROJECTNAME;
### Deploy on Apache
docker run --rm --interactive --tty --volume ./novaconium/:/app composer:latest require 4lt/novaconium;
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.
cp -R novaconium/vendor/4lt/novaconium/skeleton/. .;
### Add a page
# Edit .env
# pwgen -cnsB1v 12 # root password
# pwgen -cnsB1v 12 # mysql user password (need in both config and env)
# pwgen -cnsB1v 64 # framework key (need in config)
# Edit novaconium/App/config.php
Create a directory under `App/pages/` with an `index.twig` — the directory path *is* the URL:
docker compose up -d
```
App/pages/pricing/index.twig -> /pricing
```
Add an `index.php` next to it if the page needs data or logic. See [Sidecars](http://127.0.0.1:8000/admin/docs/sidecars) in the docs for the full contract, or [SEO](http://127.0.0.1:8000/admin/docs/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
* [Novaconiumm Official Repo](https://git.4lt.ca/4lt/novaconium)
* [CORXN Apache and PHP Container for Novaconium](https://git.4lt.ca/4lt/CORXN)
The full framework documentation — routing, sidecars, libraries, layouts, static caching, SEO, Matomo analytics, admin authentication, 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](http://127.0.0.1:8000/admin/docs/getting-started)
- [Routing](http://127.0.0.1:8000/admin/docs/routing)
- [Sidecars](http://127.0.0.1:8000/admin/docs/sidecars)
- [Libraries](http://127.0.0.1:8000/admin/docs/libraries)
- [Layouts](http://127.0.0.1:8000/admin/docs/layouts)
- [Static caching](http://127.0.0.1:8000/admin/docs/caching)
- [SEO](http://127.0.0.1:8000/admin/docs/seo)
- [Matomo](http://127.0.0.1:8000/admin/docs/matomo)
- [Admin authentication](http://127.0.0.1:8000/admin/docs/admin-auth)
- [Styling](http://127.0.0.1:8000/admin/docs/styling)
- [Project layout](http://127.0.0.1:8000/admin/docs/project-layout)
- [Third-party](http://127.0.0.1:8000/admin/docs/third-party)
### How it works
`AGENTS.md` is the short, agent-facing version for coding assistants working in this repo, and `novaconium/ISSUES.md` is the roadmap/backlog.
#### htaccess
## Project layout
htaccess ensures that all requests are sent to index.php
```
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
```
#### index.php
See [Project layout](http://127.0.0.1:8000/admin/docs/project-layout) for the full tree with every file explained.
index.php does two things:
1. Allows you to turn on error reporting (off by default)
2. Loads the novaconium bootstrap file novaconium.php
## Third-party
#### novaconium.php
What happens here:
1. Autoload composer
1. Loads configurations
[Twig](https://twig.symfony.com/) 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`.