code
d9c4b64d9c
Documents project structure, Docker-only build/run commands, and conventions so any coding agent (Claude Code, DeepSeek, etc.) can orient quickly. CLAUDE.md imports AGENTS.md as the single source of truth. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
60 lines
4.4 KiB
Markdown
60 lines
4.4 KiB
Markdown
# NovaconiumPHP
|
|
|
|
A lightweight PHP 8.1+ MVC-ish web framework/CMS toolkit (router + controllers + Twig views + Sass styling), authored by Nick Yeoman (4lt.ca) and distributed via Composer as `4lt/novaconium`. The canonical repo is hosted on a self-hosted Gitea instance (`git.4lt.ca`), not GitHub — do not assume `gh` CLI or GitHub Actions apply here.
|
|
|
|
## Directory map
|
|
|
|
- `src/` — core framework classes, namespace `Novaconium\` (PSR-4 → `src/`): `novaconium.php` (bootstrap), `Router.php`, `Database.php`, `Session.php`, `Redirect.php`, `Post.php`, `Logger.php`, `MessageHandler.php`, `functions.php`, `twig.php`, and `src/Services/` (`Auth.php`, `TagManager.php`).
|
|
- `controllers/` — framework-level default controllers (dashboard, pages, messages, settings, auth/, sitemap, 404, init, create_admin, etc.).
|
|
- `config/routes.php` — framework-level default route definitions, merged with app-level `App/routes.php` at runtime.
|
|
- `views/` — Twig views mirroring controller names (`controllers/dashboard.php` ↔ `views/dashboard.html.twig`).
|
|
- `twig/` — shared/partial Twig templates (layout pieces: `master.html.twig`, `nav.html.twig`, `head.html.twig`, `foot.html.twig`, `cp/` control-panel partials, `javascript/`).
|
|
- `sass/` — framework's default Sass source (indented Sass, not SCSS), 7-1-ish structure: `abstracts/`, `base/`, `framework/`, `controlPanel/`, `coming-soon/`; has its own `Dockerfile` for compiling.
|
|
- `skeleton/` — scaffold copied into a new consumer project on install: `.env`, `docker-compose.yml`, `novaconium/App/{config.php,routes.php,controllers,views,templates}`, `novaconium/public/{index.php,.htaccess,css,js}`, `novaconium/sass/project.sass`.
|
|
- `docs/` — one short Markdown file per topic (see below).
|
|
- `_assets/` — static assets (e.g. logo used in README).
|
|
|
|
## Build / run (Docker-only — no host tooling assumed)
|
|
|
|
**Agents (Claude Code, opencode, etc.) run inside containers and have no access to Docker.** Do not attempt to run any `docker`/`docker compose` command below — they will fail. These commands are documented for a human maintainer to run on their own host. If you need to verify a change, do so by reading/reasoning about the code, not by invoking Docker.
|
|
|
|
**Composer** (per `docs/Composer.md`):
|
|
```
|
|
docker run --rm --interactive --tty --volume $PWD:/app composer:latest require 4lt/novaconium
|
|
docker run --rm --interactive --tty --volume $PWD:/app composer:latest update
|
|
```
|
|
|
|
**Sass build** (per `docs/Sass.md`), using `sass/Dockerfile`:
|
|
```
|
|
cd sass && docker build -t sass-container .
|
|
docker run --rm -v $(pwd):/usr/src/app -w /usr/src/app sass-container sass novaconium/sass/project.sass novaconium/public/css/novaconium.css
|
|
```
|
|
Compressed variant: add `--style=compressed`, e.g.
|
|
```
|
|
docker run --rm -v $(pwd):/usr/src/app -w /usr/src/app sass-container --style=compressed sass/novaconium.sass skeleton/novaconium/public/css/novaconium.css
|
|
```
|
|
|
|
**Dev stack**: `docker compose up -d` from `skeleton/docker-compose.yml` — services: `4lights/corxn:8.5.3` (Apache+PHP), `redis`, `mariadb`, `phpmyadmin`.
|
|
|
|
**Testing a cloned copy without reinstalling via Composer**: see `docs/Dev-Fake_autoload.md` for the fake-autoload dev trick.
|
|
|
|
## No test suite / lint / CI
|
|
|
|
There is no `phpunit.xml`, no lint config (no PHPCS, `.editorconfig`, ESLint), and no CI pipeline in this repo. Don't hunt for `npm test`/`phpunit`/lint commands — none exist.
|
|
|
|
## Conventions
|
|
|
|
- PSR-4 autoloading: `Novaconium\` → `src/`.
|
|
- Controllers and views are name-paired by default (e.g. `controllers/dashboard.php` ↔ `views/dashboard.html.twig`), but this is only a convention — a controller can render any view, they are not required to match.
|
|
- Sass partials are prefixed `_` (e.g. `_forms.sass`), aggregated per-folder via `index.sass`.
|
|
- App-level config (`App/config.php`) is a multi-dimensional PHP array: database credentials, `base_url`, `secure_key`, `logfile`, `loglevel`.
|
|
- Versioning strategy is semantic-versioning (declared in `composer.json` `extra.versioning`).
|
|
|
|
## Git workflow
|
|
|
|
Single `master` branch (no `main`), tracking a self-hosted Gitea remote. Solo-maintainer, trunk-based, direct commits to `master` with short informal messages — no conventional-commits enforcement, no PR-based tooling assumptions.
|
|
|
|
## Further reading
|
|
|
|
See `docs/*.md` for per-topic detail: `404.md`, `Composer.md`, `ConfigurationFile.md`, `Dev-Fake_autoload.md`, `Logs.md`, `Messages.md`, `Post.md`, `Redirect.md`, `Sass.md`, `Session.md`, `StyleSheets-sass.md`, `Twig-Views.md`, `docker.md`.
|