ZapMachine/docs/framework_review.md

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

---