449e6f8e03
- Add phpt test runner and suite for app functions - Introduce testing workflow to AGENT.md - Add tests for cache, content, context, helpers, hooks, plugins, rendering - Mount tests directory in dev container
43 lines
2.9 KiB
Markdown
43 lines
2.9 KiB
Markdown
# FolderWeb
|
|
|
|
Minimal file-based CMS. Folders = URLs. PHP 8.4+, no JS, no frameworks, no build tools.
|
|
|
|
## Philosophy
|
|
|
|
Decade-scale maintainability. Only essential tech. Readable, simple, future-proof. No volatile dependencies.
|
|
|
|
## Two Modes of Work
|
|
|
|
1. **Building on top** (`custom/`): Create sites using the framework. Never modify `app/`. In this mode, `app/` is typically symlinked or submoduled from the framework repo into a separate site repo.
|
|
2. **Framework development** (`app/`): Evolve the core. Preserve all stable contracts (see architecture doc). `custom/` may be symlinked in from a site repo for testing.
|
|
|
|
## Framework Development Workflow
|
|
|
|
When modifying or adding code in `app/`: write tests and run them before marking work done. Read `docs/05-testing/01-testing.md` for the required workflow and test format.
|
|
|
|
## Standards
|
|
|
|
- **Stack:** HTML5, PHP 8.4+, CSS. Nothing else.
|
|
- **Security:** Path traversal protection, document root restriction, strict MIME types, escape all UGC
|
|
- **PHP:** Arrow functions, null coalescing, match expressions. Type hints where practical. Single-purpose functions, avoid side effects. Comments only for major sections.
|
|
- **HTML:** Classless, semantic markup.
|
|
- **CSS:** Variables, native nesting, relative units. Modern CSS (`oklch()`, `light-dark()`, `clamp()`, logical props). Global styles first, page-scoped when needed.
|
|
- **Templates:** `<?= htmlspecialchars($var) ?>` for UGC. `<?= $content ?>` for pre-rendered HTML.
|
|
|
|
## Knowledge Base
|
|
|
|
Read these docs on-demand when working on related areas. Do not load all at once.
|
|
|
|
| Skill | File | Read When |
|
|
|---|---|---|
|
|
| Architecture | `docs/04-development/01-architecture.md` | Understanding project structure, request flow, module dependencies, stable contracts |
|
|
| Content System | `docs/04-development/02-content-system.md` | Working with routing, URL resolution, metadata, content discovery, navigation |
|
|
| Configuration | `docs/04-development/03-configuration.md` | Config loading, the `custom/` override system, static asset routing |
|
|
| Context API | `docs/04-development/04-context-api.md` | The Context class, Templates class, built-in context keys |
|
|
| Hooks & Plugins | `docs/04-development/05-hooks-plugins.md` | Hook system, plugin manager, writing plugins, the language plugin |
|
|
| Templates | `docs/04-development/06-templates.md` | Template hierarchy, resolution, variables, list item schema, partials |
|
|
| Rendering | `docs/04-development/07-rendering.md` | Rendering pipeline, Markdown caching, static file serving, Parsedown |
|
|
| Dev Environment | `docs/04-development/08-dev-environment.md` | Container setup, Apache config, performance profiling, test data generation |
|
|
| Testing | `docs/05-testing/01-testing.md` | **Required before modifying `app/`** — workflow, test format, what's testable |
|
|
|
|
Human-facing docs (tutorials, reference) are in `docs/01-getting-started/`, `docs/02-tutorial/`, `docs/03-reference/`.
|