fabs/ZapMachine
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

optimize framework: ready to merge and release 0.9.0

Browse source
This commit is contained in:
Fabian de Boer 2026-07-20 14:35:35 +02:00
commit 42cfff87d0
5 changed files with 49 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs/framework_review.md Normal file
View file

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