ruben/folderweb
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Activity Actions
folderweb/AGENT.md
Ruben 449e6f8e03 Update framework testing infrastructure and standards 
- 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
2026-03-17 12:51:07 +01:00

2.9 KiB
Raw Blame History

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/.