From 42cfff87d030189e45569973d2bf14fe2c09bd24 Mon Sep 17 00:00:00 2001 From: Fabian de Boer Date: Mon, 20 Jul 2026 14:35:35 +0200 Subject: [PATCH] optimize framework: ready to merge and release 0.9.0 --- .gitignore | 1 - docs/framework_review.md | 39 +++++++++++++++++++ kanban/activity.jsonl | 2 + ...request-building-lazy-url-single-encode.md | 6 ++- ...utoloader-use-path-separator-instead-of.md | 6 ++- 5 files changed, 49 insertions(+), 5 deletions(-) create mode 100644 docs/framework_review.md diff --git a/.gitignore b/.gitignore index b9c4024..532dbc8 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,3 @@ sessions/* conf/conf.local.php ignore .pi-tasks -docs/framework_review.md diff --git a/docs/framework_review.md b/docs/framework_review.md new file mode 100644 index 0000000..2865e02 --- /dev/null +++ b/docs/framework_review.md @@ -0,0 +1,39 @@ +# ZAP Framework Review + +Task #10 — *“Check if the framework is the optimal, most simple and flexible way to go. If not: suggest some changes.”* + +This review audits the internal ZapMachine PHP framework (documented in `docs/framework_guide.md`) against three criteria — **optimal**, **simple**, and **flexible** — based on a full read of the current source on branch `optimize-framework` (commit `d971512`). + +**Scope:** audit + recommendations only. **No source files are modified in this deliverable.** Every recommendation below is a proposal that should get its own kanban task and separate approval before implementation. + +--- + +## Verdict + +The framework’s **architecture is genuinely simple and flexible** for its scope. Adding a new page (`?mode=`) is a one-class + one-template operation with zero registration. Adding a new search engine is a one-class operation behind a clean interface. PHP-native templating means no build step and no engine dependency. These are real strengths and should be preserved. + +It is **not optimal**, however, because: + +1. **Three P0 correctness bugs** silently degrade the core search pipeline (Brave `size`/`offset` params never sent; query double-URL-encoded; autoloader path split hardcodes `':'`). +2. **Unsafe / committed config defaults** (`ZAP_DEBUG=true`, placeholder API key in git-tracked `conf/conf.php`, `chmod 777`). +3. **Several loose abstraction boundaries** make the “framework contract” described in the guide looser than the code actually enforces (no `ZAPHandler` interface, inconsistent `extract()` template pattern, raw `$_SESSION` access beside a `Session` wrapper). + +None of these require replacing the architecture. They are bug fixes, a config-hygiene pass, and a few small interface tightenings. Recommended effort: a handful of small, well-scoped tasks — **not** a rewrite. + +--- + + +## Strengths worth preserving + +| Aspect | Why it’s good | +|---|---| +| Front-controller + naming convention (`ZAP` + ucfirst(mode)) | Zero-config routing. A new mode = one class in `lib/` + one `.tpl`. No route table, no registration. Very flexible, very simple. (`lib/ZAPController.class.php`) | +| `spl_autoload_register` over the include path | No manual `require_once` for library classes; drop a `.class.php` in the right dir and it loads. (`conf/init.php`) | +| `Search` interface plugin system | Engines are interchangeable behind a 3-method contract and a universal result-array shape. Adding `Pixabay`/`Pexels` (tasks #1/#2) is a clean drop-in. (`resource/Search.interface.php`, `resource/Brave.class.php`) | +| PHP-native templates (`ob_start`/`include`/`extract`/`ob_get_clean`) | No template engine, no compilation step, no extra dependency. Simplest possible rendering. | +| `Config` singleton | Decouples runtime config (e.g. registered engines) from individual classes. (`conf/Config.class.php`) | +| Clear layering | routing / handlers / search / imaging / utils are in separate dirs with single responsibilities. | + +These answer the “simple and flexible” part of the brief affirmatively. The rest of this document is about getting to “optimal.” + +--- diff --git a/kanban/activity.jsonl b/kanban/activity.jsonl index 0aab3a4..3352de4 100644 --- a/kanban/activity.jsonl +++ b/kanban/activity.jsonl @@ -91,3 +91,5 @@ {"timestamp":"2026-07-20T01:09:23.947300407+02:00","action":"edit","task_id":19,"detail":"Single source of truth for word count + cleanup handleWords"} {"timestamp":"2026-07-20T01:09:23.947430566+02:00","action":"claim","task_id":19,"detail":"rain-raven"} {"timestamp":"2026-07-20T01:09:23.97076796+02:00","action":"move","task_id":19,"detail":"todo -\u003e done"} +{"timestamp":"2026-07-20T14:15:55.814485137+02:00","action":"move","task_id":12,"detail":"review -\u003e done"} +{"timestamp":"2026-07-20T14:15:59.830512648+02:00","action":"move","task_id":11,"detail":"review -\u003e done"} diff --git a/kanban/tasks/011-fix-brave-request-building-lazy-url-single-encode.md b/kanban/tasks/011-fix-brave-request-building-lazy-url-single-encode.md index 5f2c2cc..88f61cc 100644 --- a/kanban/tasks/011-fix-brave-request-building-lazy-url-single-encode.md +++ b/kanban/tasks/011-fix-brave-request-building-lazy-url-single-encode.md @@ -1,10 +1,12 @@ --- id: 11 title: 'Fix Brave request building: lazy URL + single encode' -status: review +status: done priority: high created: 2026-07-17T03:57:00.444816503+02:00 -updated: 2026-07-17T12:26:38.759875442+02:00 +updated: 2026-07-20T14:15:59.825243496+02:00 +started: 2026-07-20T14:15:59.830054903+02:00 +completed: 2026-07-20T14:15:59.830054903+02:00 tags: - search - bug diff --git a/kanban/tasks/012-fix-autoloader-use-path-separator-instead-of.md b/kanban/tasks/012-fix-autoloader-use-path-separator-instead-of.md index 211a40d..54fd574 100644 --- a/kanban/tasks/012-fix-autoloader-use-path-separator-instead-of.md +++ b/kanban/tasks/012-fix-autoloader-use-path-separator-instead-of.md @@ -1,10 +1,12 @@ --- id: 12 title: 'Fix autoloader: use PATH_SEPARATOR instead of hardcoded '':''' -status: review +status: done priority: high created: 2026-07-17T03:57:06.82901804+02:00 -updated: 2026-07-17T12:27:53.056263524+02:00 +updated: 2026-07-20T14:15:55.809367918+02:00 +started: 2026-07-20T14:15:55.814059562+02:00 +completed: 2026-07-20T14:15:55.814059562+02:00 tags: - framework - bug