This document explains the internal architecture of ZapMachine and provides step‑by‑step instructions for extending it with new handlers, templates, and interactive elements.
All HTTP requests enter through `www/index.php`. The front controller reads the `mode` query parameter and dispatches to a class whose name is formed as `ZAP` + the ucfirst'd mode value.
`ZAPController` (in `lib/ZAPController.class.php`) constructs the class name from a prefix (`ZAP`) and the mode, verifies it exists via the autoloader, instantiates it, and calls `getContent()`:
`conf/init.php` registers an `spl_autoload_register` callback that searches every directory on the include path for both `{ClassName}.class.php` and `{ClassName}.interface.php`:
This means any `.class.php` or `.interface.php` file placed in one of those directories is automatically found — no manual `require_once` calls needed for library classes.
---
### Config Singleton
Configuration values that must be accessible from any class are managed through `Config` (`conf/Config.class.php`), a classic singleton:
```php
$config = Config::getInstance();
$config->register('engines', $search_engines); // store
$engines = $config->retrieve('engines'); // retrieve — returns false if not found
```
The singleton is wired in `www/index.php` immediately after `init.php` is loaded.
---
### Session Management
The `Session` class (`utils/Session.class.php`) wraps PHP's native sessions:
```php
Session::start('ZAP'); // Begin session (sessions named 'ZAP')
Available engines are registered as an array of names in `conf/conf.php` and wired through the Config singleton at runtime. `ImgSearch` randomly selects an engine from the registered list each time it runs:
```php
$config = Config::getInstance();
$engines = $config->retrieve('engines');
$this->engine = $engines[array_rand($engines)];
```
**Current engine:** `Brave` (`resource/Brave.class.php`) — uses the Brave Search API.
2. Add `'yourengine'` to the `$search_engines` array in `conf/conf.php`.
---
### Image Processing Pipeline
The image pipeline runs entirely server-side through three classes in `lib/`:
1.**`ImgSearch`** (`lib/ImgSearch.class.php`) — searches for an image URL via a registered engine, downloads the file, validates its MIME type (`image/jpeg`, `image/gif`, `image/png`), and saves it to the session folder.
2.**`ImgProcess`** (`lib/ImgProcess.class.php`) — constructs collages using ImageMagick. Each collage starts with `createBasicCanvas()` (zoom-crops the first source image) then layers additional images via `addToCanvas()` (random transparency + composite).
3.**`ImgIOTools`** (`lib/ImgIOTools.class.php`) — handles output: `onScreen()` streams an Imagick object as an HTTP image response; `urlOnScreen()` loads a file path first; `saveImg()` writes to disk.
CLI scripts (in `cli_scripts/`) bootstrap the application differently from web requests. Because `init.php` skips `Session::start()` when `php_sapi_name() === 'cli'`, CLI scripts must handle sessions manually if needed.
**Example — `cli_scripts/test.php`:**
```php
#!/usr/bin/env php
<?php
// Make sure relative paths in init.php resolve against this script's directory
chdir(__DIR__);
// Bootstrap the application (autoloader, constants, Config, but NOT session)
require_once __DIR__ . '/../conf/init.php';
// If you need sessions in CLI, call Session::start() manually:
// Session::start('ZAP');
// Now all classes, the autoloader, and Config singleton are available
$config = Config::getInstance();
$config->register('engines', $search_engines);
```
Key differences from the web entry point:
-`chdir(__DIR__)` is **required** before `require_once 'init.php'` because `init.php` uses `realpath('.')` to define `ZAP_APP_BASE_DIR`.
-`Session::start()` is **not called** — the `init.php` condition `php_sapi_name() !== 'cli'` guards against it.
- You must explicitly register engines with `Config::getInstance()->register('engines', …)` because `www/index.php` normally does this.
The `Log` class (`utils/Log.class.php`) writes timestamped messages to a session folder. It is used by `ImgSearch` (controlled by the `ZAP_LOG` constant in `conf/conf.php`). Each log call appends to both `log.txt` (plain text) and `log.html` (HTML-friendly) in the session's output directory.
$log->addToLog('ok', 'Search: ', "downloaded to $imageName");
$log->addToLog('error', 'Search: ', 'bad search data received');
}
```
---
## Template Rendering Pipeline
The template system is a minimal PHP-native pattern built around `ob_start()` / `include` / `extract()` / `ob_get_clean()`. There is no template engine — templates are plain PHP files that receive variables via the symbol table.
### How Templates Work
Every `ZAP{Mode}` handler follows the same rendering pattern:
```php
class ZAPHome {
private $template = 'index'; // corresponds to tpl/index.tpl
private $tpl = '';
public function __construct() {
$this->ver = ZAP_VERSION;
extract(get_object_vars($this)); // ← makes all private properties available as $variables
ob_start(); // ← start output buffer
include getZAPTemplate($this->template); // ← include the .tpl file
1. Properties are set in the constructor (often from `$_POST`, `$_SESSION`, or constants like `ZAP_VERSION`).
2.`extract(get_object_vars($this))` promotes every private property to a local variable in the current symbol table. A property `$this->template = 'index'` becomes `$template = 'index'`.
3.`ob_start()` begins capturing all output.
4.`include getZAPTemplate($this->template)` includes the file `tpl/{name}.tpl`. The included file inherits the current symbol table, so it can use `$ver`, `$folder`, `$words`, etc. directly.
5.`ob_get_clean()` retrieves the captured HTML and closes the buffer.
6.`getContent()` returns the accumulated output string, which `ZAPController::fetch()` returns to `index.php` for `print()`.
All templates live in the `tpl/` directory and have the `.tpl` extension. The helper resolves the absolute path so the `include` call works from any working directory.
### Adding a New Template
To add a new page/view:
1.**Create the `ZAP{Mode}` handler** in `lib/`. The class must be named `ZAP{Mode}` (case-sensitive, PascalCase after the prefix) and must implement a `getContent()` method that returns a string:
3.**Use the route:** Navigate to `index.php?mode=example`. The autoloader finds `ZAPExample` in `lib/`, the front controller instantiates it, and `getZAPTemplate()` loads `tpl/example.tpl`.
No registration step is required — the front controller's naming convention (`ZAP` + ucfirst(mode)) and the autoloader handle discovery automatically.
---
## Adding Interactive Elements
This section documents the two interactive-element patterns used in the application. Each pattern pairs a server-side template with a client-side JavaScript file.
### Pattern 1: Form with Client-Side Validation (`index.tpl` + `js/main.js`)
Used by `ZAPHome` to collect word inputs, validate them in the browser, and POST to the `display` mode.
**Server side (`ZAPHome` in `lib/ZAPHome.class.php`):**
The handler passes two template variables into `tpl/index.tpl`:
-`$ver` — the ZAP version string.
-`$status` — an optional status message from the query string (`?stat=...`).
The template renders a `<form id="form1">` that POSTs to `index.php?mode=display`. Each input is named `word01`, `word02`, … `word{MAX_WORDS}` (zeropadded to two digits). A `<select name="collages">` controls the number of collages, and width/height text inputs control dimensions.
**Client side (`js/main.js`):**
The `form1Submit()` function performs validation before the form is submitted:
```javascript
function form1Submit() {
// Minimum of two words required
var word1 = document.getElementById('word01').value;
var word2 = document.getElementById('word02').value;
var width = document.getElementById('width').value;
var height = document.getElementById('height').value;
if (word1.length <= 0) {
document.getElementById('status').innerHTML = 'Minimum of two words required';
return;
}
if (word2.length <= 0) {
document.getElementById('status').innerHTML = 'Minimum of two words required';
Used by the `display` and `zap` modes to show collage progress. The server streams individual image responses, and the client alternates between two `<img>` tags to give the appearance of continuous updating.
**Server side:**
`ZAPDisplay` (in `lib/ZAPDisplay.class.php`) sets session variables from `$_POST` and renders `tpl/display.tpl`. The template declares `onload="go(this,['img1','img2'],5000);"` on the `<body>` tag, which kicks off the polling loop.
`ZAPZap` (in `lib/ZAPZap.class.php`) handles each individual poll request. On each invocation it either:
- Downloads the next source image (if `$_SESSION['words']` is not empty) and streams it via `ImgIOTools::onScreen()`.
- Starts the next collage (if `$_SESSION['words']` is empty but `$_SESSION['collages'] > 0`).
- Adds the next source image to the current collage via `ImgProcess::addToCanvas()`.
- Signals completion by destroying the session and returning an error string (which triggers the `onerror` handler in JavaScript).
**Client side (`js/display.js`):**
```javascript
var go = function(b, img_id, interval) {
var i = 0;
var img0 = document.getElementById(img_id[0]);
var img1 = document.getElementById(img_id[1]);
var img = [img0, img1];
var activeImage = 1; // index of visible image
var url = 'index.php?mode=zap';
if (isNaN(interval)) {
interval = 5000;
}
// Trigger the next image fetch after the current one has loaded.
img[0].onload = img[1].onload = function() {
var inactiveImage = activeImage === 0 ? 1 : 0;
img[activeImage].style.display = 'none';
img[inactiveImage].style.display = '';
activeImage = inactiveImage;
setTimeout(function() {
img[inactiveImage].src = url + '&i=' + (i++);
}, interval);
};
// When the backend signals completion it returns a small HTML page.
// Show the ready link and stop fetching new images.
1.`body onload="go(this,['img1','img2'],5000)"` starts the loop with a 5s interval between successive fetches.
2. Two `<img>` tags (`#img1` and `#img2`) are used — one is visible, the other hidden.
3. When the visible image finishes loading (`img.onload`), the pair swaps: the loaded image is hidden, and the previously hidden one is shown. After a 5s delay (`setTimeout`), the newly hidden image's `src` is set to `index.php?mode=zap&i={counter}`.
4. Each request to `mode=zap` returns raw image data (a `Content-Type: image/jpeg` response). The browser renders it into the `<img>` tag, triggering `onload` again and continuing the cycle.
5. When `ZAPZap` finishes all collages, it destroys the session and returns an HTML error string instead of image data. The `<img>` tag fails to load an image, triggering `onerror`, which replaces the image area with a "Ready" link.
**To reproduce this pattern in a new handler:**
1. Create a template with two `<img>` elements and `<body onload="go(this,['id1','id2'],intervalMs)">`.
2. Include `js/display.js` (or copy the pattern into your own JS file).
3. Create a `ZAP{Mode}` handler that returns raw image data (set `Content-Type` headers and use `echo` with `readfile()` or Imagick's `getImageBlob()`).
4. Signal completion by returning a non-image response that will trigger `onerror` on the `<img>` tag.
---
## Summary: Creating a New Feature End-to-End
To add a completely new feature to ZapMachine, follow these steps:
1.**Add configuration** in `conf/conf.php` (constants, engine names) if needed.
2.**Create the handler**`lib/ZAP{Mode}.class.php` with `getContent()` returning a string.
3.**Create the template**`tpl/{mode}.tpl` using the `ob_start`/`include`/`extract`/`ob_get_clean` pattern.
4.**Choose an interactive pattern:**
- For form input with validation: add a form in the template, write a JS validation function, and include the script.
- For polling/image updates: use the two-`<img>` swap with `onload`/`onerror`.
5.**Create a JS file** in `www/js/` and reference it from the template's `<head>`.
6.**Test the route** at `index.php?mode={ModeName}`.
7.**Test from CLI** using the bootstrap pattern in `cli_scripts/test.php` (remember `chdir(__DIR__)` + manual `Session::start()` if needed).
