---

# Documentation: Async

As PHP is inherently synchronous, running code asynchronously requires a background loop that observes and dispatches events while handling promise resolutions. PHP.GT/Async introduces an event loop, timers and a promise-based approach to handling deferred operations.

This package provides:

- `Loop`, which waits until work is due and then dispatches it
- `IndividualTimer`, for one-off trigger times
- `PeriodicTimer`, for repeated trigger times
- `Event` and `EventDispatcher`, for lightweight publish-subscribe messaging
- Loop support for tracking `Deferred` objects from `phpgt/promise`

The package is standalone. We can use it in any PHP project with Composer. WebEngine also depends on this package, but the classes documented here can still be used directly outside WebEngine.

## A minimal example

```php
use Gt\Async\Loop;
use Gt\Async\Timer\IndividualTimer;

$loop = new Loop();
$timer = new IndividualTimer(2);

$timer->addCallback(function() use($loop) {
	echo "Two seconds have passed.", PHP_EOL;
	$loop->halt();
});

$loop->addTimer($timer);
$loop->run();
```

Here we schedule one callback to run two seconds in the future. Once it has run, the callback halts the loop.

---

Start with [[Getting started]] to build a working loop from scratch.


In this guide we will install the package, create a loop, add timers, and stop the loop cleanly.

## 1. Install the package

```bash
composer require phpgt/async
```

`phpgt/promise` is installed as a dependency, so the loop is ready for the deferred work covered later in this guide.

## 2. Create a loop

```php
use GT\Async\Loop;

$loop = new Loop();
```

Nothing happens yet because the loop has no timers to observe.

## 3. Add a one-off timer

`IndividualTimer` schedules one or more exact trigger times.

```php
use GT\Async\Timer\IndividualTimer;

$timer = new IndividualTimer(1.5);
$timer->addCallback(function() {
	echo "First callback", PHP_EOL;
});

$loop->addTimer($timer);
```

Passing `1.5` to the constructor means "run once, one and a half seconds from now".

## 4. Add a repeating timer

`PeriodicTimer` schedules callbacks every fixed number of seconds.

```php
use Gt\Async\Timer\PeriodicTimer;

$count = 0;

$periodicTimer = new PeriodicTimer(0.5, true);
$periodicTimer->addCallback(function() use(&$count, $loop) {
	$count++;
	echo "Tick $count", PHP_EOL;

	if($count === 3) {
		$loop->halt();
	}
});

$loop->addTimer($periodicTimer);
```

The second constructor argument controls the first tick:

- `true` means the first tick is immediate
- `false` means the first tick happens after the first period has passed

## 5. Run the loop

```php
$loop->run();
```

The loop will keep going until one of these things happens:

- there are no more scheduled timers
- one of the callbacks calls `$loop->halt()`
- deferred completion tracking halts the loop, which we will cover later

## 6. Run only one pass

If we call `run(false)`, the loop performs one pass over the timers that are currently due and then returns.

```php
$loop->run(false);
```

This is useful when another part of the application controls the outer execution flow.

---

Next, continue with [[Timers]] to see how the two timer types behave in more detail.


Timers are the objects the loop watches. Each timer keeps a queue of trigger times, and each time a timer is due it runs every callback attached to it.

## IndividualTimer

`IndividualTimer` is for one-off trigger times.

We can schedule a relative delay in the constructor:

```php
use GT\Async\Timer\IndividualTimer;

$timer = new IndividualTimer(5);
```

That means "trigger once, five seconds from now".

We can also add absolute trigger times:

```php
$start = microtime(true);

$timer = new IndividualTimer();
$timer->addTriggerTime($start + 1);
$timer->addTriggerTime($start + 5);
$timer->addTriggerTime($start + 10);
```

`addTriggerTime()` expects a Unix epoch float, not a delay value.

## PeriodicTimer

`PeriodicTimer` is for repeated work at a fixed interval.

```php
use Gt\Async\Timer\PeriodicTimer;

$timer = new PeriodicTimer(0.25, true);
```

This timer will trigger every quarter of a second, and because the second argument is `true`, the first tick is immediate.

If we want the timer to wait before the first tick, use:

```php
$timer = new PeriodicTimer(0.25, false);
```

## Adding and removing callbacks

Any timer can hold more than one callback:

```php
$timer->addCallback(function() {
	echo "A", PHP_EOL;
});

$timer->addCallback(function() {
	echo "B", PHP_EOL;
});
```

When the timer ticks, both callbacks run in the order they were added.

Callbacks can also be removed:

```php
$callback = function() {
	echo "Only once", PHP_EOL;
};

$timer->addCallback($callback);
$timer->removeCallback($callback);
```

## Running several timers together

The loop can observe any number of timers at once.

```php
use GT\Async\Loop;
use GT\Async\Timer\IndividualTimer;
use GT\Async\Timer\PeriodicTimer;

$loop = new Loop();
$stopTimer = new IndividualTimer(5);
$countdownTimer = new PeriodicTimer(1, true);
$dotTimer = new PeriodicTimer(0.1, true);
$count = 5;

$countdownTimer->addCallback(function() use(&$count) {
	echo "Countdown: $count", PHP_EOL;
	$count--;
});

$dotTimer->addCallback(function() {
	echo ".";
});

$stopTimer->addCallback(function() use($loop) {
	echo PHP_EOL, "Stop", PHP_EOL;
	$loop->halt();
});

$loop->addTimer($countdownTimer);
$loop->addTimer($dotTimer);
$loop->addTimer($stopTimer);
$loop->run();
```

This is the main idea behind the package: small pieces of work can take turns without us having to block on one long operation.

---

Next, move on to [[Deferred work]] to connect the loop to `Deferred` objects and promises.


Async depends on [`phpgt/promise`](https://www.php.gt/promise/), so the loop can track `Deferred` objects while their work is being processed in small steps.

This is useful when a task should not block the whole script. Instead of reading a file, stream, or queue item all at once, we can process a small piece on each tick and resolve the promise when the task is complete.

## The preferred approach: track completion only

If another part of your code already decides when work should be processed, use `trackDeferred()`:

```php
use GT\Async\Loop;
use GT\Promise\Deferred;

$loop = new Loop();
$deferred = new Deferred();

$loop->trackDeferred($deferred);
$loop->haltWhenAllDeferredComplete(true);
```

This tells the loop:

- this deferred task is part of the loop lifecycle
- remove it from tracking when it completes
- halt the loop when all tracked deferred tasks have completed

`trackDeferred()` does **not** attach any process callbacks to a timer.

## Attaching deferred processing to a timer

If we do want the loop to attach a deferred task's process callbacks to a timer, `addDeferredToTimer()` is available:

```php
use GT\Async\Timer\PeriodicTimer;
use GT\Promise\Deferred;

$timer = new PeriodicTimer(0.1, true);
$deferred = new Deferred();

$deferred->addProcess(function() {
	// Process one small step here.
});

$loop->addTimer($timer);
$loop->addDeferredToTimer($deferred, $timer);
```

> [!WARNING]
> `addDeferredToTimer()` is deprecated. Prefer `trackDeferred()` unless you specifically need the loop to wire the process callbacks onto a timer for you.

## Halting when all deferred work is complete

The loop can halt itself when the tracked deferred list becomes empty:

```php
$loop->haltWhenAllDeferredComplete(true);
$loop->addHaltCallback(function() {
	echo "All deferred work is complete.", PHP_EOL;
});
```

This is useful when the loop should stay alive only for as long as there is outstanding asynchronous work.

## A small example

```php
use GT\Async\Loop;
use GT\Async\Timer\PeriodicTimer;
use GT\Promise\Deferred;

$loop = new Loop();
$timer = new PeriodicTimer(0.1, true);
$stepsRemaining = 5;
$deferred = new Deferred();

$deferred->addProcess(function() use(&$stepsRemaining, $deferred) {
	echo ".";
	$stepsRemaining--;

	if($stepsRemaining === 0) {
		$deferred->resolve("Complete");
	}
});

$deferred->getPromise()->then(function(string $message) {
	echo PHP_EOL, $message, PHP_EOL;
});

$loop->addTimer($timer);
$loop->addDeferredToTimer($deferred, $timer);
$loop->haltWhenAllDeferredComplete(true);
$loop->run();
```

Each timer tick advances the task by one step. When the deferred resolves, the loop removes it from tracking and halts because there is no more deferred work left.

---

Next, continue with [[Events]] for the package's publish-subscribe classes.


Alongside the loop and timers, this package includes a small in-memory event system.

There are only two classes involved:

- `Event`, which carries an event name and optional detail data
- `EventDispatcher`, which stores subscribers by event name and publishes events to them

## Subscribing to an event

```php
use GT\Async\Event\Event;
use GT\Async\Event\EventDispatcher;

$dispatcher = new EventDispatcher();

$dispatcher->subscribe("tick", function(Event $event) {
	echo "Received: ", $event->getName(), PHP_EOL;
});
```

## Publishing an event

```php
$dispatcher->publish(new Event("tick"));
```

That will invoke every callback subscribed to `"tick"`, in the same order they were added.

## Passing detail data

The `Event` object can carry any detail value:

```php
$dispatcher->subscribe("message", function(Event $event) {
	echo $event->getDetail(), PHP_EOL;
});

$dispatcher->publish(new Event("message", "Hello"));
```

## What this dispatcher does not do

This is a deliberately small utility. It does not include:

- wildcard subscriptions
- unsubscribe methods
- cross-process or network delivery

If you need those features, they would need to be built on top.

---

Finally, take a look at [[Examples]] for the bundled scripts in this repository.


This repository includes three small example scripts in the `example/` directory.

## Delays

`01-delay-1-5-10-seconds.php` uses one `IndividualTimer` with three trigger times.

It shows:

- adding absolute trigger times with `addTriggerTime()`
- attaching one callback that runs on every trigger
- running the loop until no scheduled work remains

## Countdown

`02-countdown.php` combines:

- an `IndividualTimer` that halts the loop after five seconds
- a `PeriodicTimer` that prints a countdown once per second
- another `PeriodicTimer` that prints dots more frequently

This is a good example of several timers sharing one loop.

## Promise-based work

`03-promise.php` wraps a slow file reader in a class that returns a promise.

It shows:

- adding deferred process callbacks
- attaching that deferred work to a timer
- resolving promises when the work is complete
- halting the loop automatically when all deferred work is done

The example uses `addDeferredToTimer()`, which still works, but remember that the method is deprecated in favour of `trackDeferred()` when callback attachment is not needed.




---

# Documentation: Build

PHP.GT Build provides a system to describe client-side build work in one place and run it from PHP projects without introducing another package manager or task runner of its own.

The library does two jobs:

- checks that the commands the project depends on are installed and meet the version constraints
- runs the relevant commands when matching source files exist, either once or continuously in watch mode

Build does not install or manage front-end tooling for us. We can keep using whatever tooling is preferred, whether that means `node_modules/.bin`, `vendor/bin`, or programs installed elsewhere on the system.

## What the configuration looks like

The recommended format is `build.ini`. Each section name is a file pattern, and each section describes the command to run for that pattern.

`build.ini`:

```ini
[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

[style/**/*.scss]
name=Compile Sass
require=sass >=1.6
execute=sass ./style/style.scss ./www/style.css

[asset/**/*]
name=Publish static assets
require=vendor/bin/sync ^1.3
execute=vendor/bin/sync ./asset ./www/asset --symlink
```

When we run `vendor/bin/build`, Build checks the requirements first and then executes each task whose glob matches at least one file.

## INI is now the default

Build still supports `build.json`, but `build.ini` is usually more compact for this kind of command-focused configuration.

JSON support remains available for projects that already use it, or for cases where a nested object structure is preferred. There's a separate [[JSON configuration example]] page showing the equivalent layout.

## A few details worth knowing early

- If both `build.ini` and `build.json` exist in the same directory, Build uses `build.ini`.
- Mode files work with both formats: `build.production.ini` or `build.production.json`.
- The `require` line is optional, but it is worth using so problems are detected before a build starts.
- Task names are optional. If omitted, the command itself is used in log output.

---

Start with [[command line usage]] to see how Build finds configuration files and how the command-line options fit together.


Build is intended to be run from the command line.

When the package is installed in a project, the executable is available at:

```bash
vendor/bin/build
```

> [!NOTE]
> In WebEngine applications, the same functionality is also exposed through:
>
> ```bash
> gt build
> ```

By default, Build looks in the current working directory and prefers these filenames in this order:

1. `build.ini`
2. `build.json`

That means if both files exist, `build.ini` is the one that will be used.

If we want to point somewhere else, we can use `--config` or `-c`.

Examples:

```bash
vendor/bin/build --config ./config/build.ini
vendor/bin/build --config ./tools/build.json
vendor/bin/build --config ./some/project/directory
```

If the path passed to `--config` is a directory, Build looks inside that directory for `build.ini` first, then `build.json`.

## Running once

Running the command without `--watch` performs one pass:

```bash
vendor/bin/build
```

For each task, Build:

1. loads the configuration
2. checks the declared requirements
3. skips tasks whose file pattern matches nothing
4. runs the command for tasks with matching files

Build prints a timestamped line for each successful task and then reports the total elapsed time.

## Watching for changes

To keep Build running and rebuild when source files change, use `--watch` or `-w`:

```bash
vendor/bin/build --watch
```

In watch mode, Build remembers the modification time of each matched file and reruns only the tasks whose matching files changed.

This is usually the command we keep running during local development.

## Build modes

Mode files let us override part of the base configuration for a specific environment.

```bash
vendor/bin/build --mode production
vendor/bin/build -m dev
```

When the base file is `build.ini`, Build looks for files such as `build.production.ini`.
When the base file is `build.json`, Build looks for files such as `build.production.json`.

Only the properties that change need to be present in the mode file. The base and mode configuration are merged before the build runs.

The full behaviour is covered on [[different environments]].

## Default configuration

Frameworks and shared project setups can provide a fallback configuration by using `--default` or `-d`.

```bash
vendor/bin/build --default ./config/build.default.ini
vendor/bin/build --default ./framework/build
```

The default path may point to either a file or a directory. If it points to a directory, the same `build.ini` then `build.json` lookup order is used.

Build first looks for the project configuration. If none is found, it falls back to the default path.

The override model is explained on [[default config]].

---

Next, read [[build tasks]] for the structure of individual task definitions.


Each build task starts with a file pattern. When that pattern matches one or more files, Build knows which command to run.

Examples:

- `images/*.jpg` matches JPEG files directly inside `images/`
- `script/**/*.es6` matches ES6 files anywhere under `script/`
- `asset/**/*` matches every file under `asset/`

For one-off builds, Build checks each pattern in turn and runs the matching tasks once.
For watch mode, Build keeps checking the same patterns and reruns tasks when the modification time of a matched file changes.

## INI task format

In `build.ini`, each task is a section:

```ini
[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js
```

The section name is the glob pattern.

The supported keys are:

- `name`: optional label used in success output
- `require`: optional comma-separated list of command/version pairs
- `execute`: required command line to run

If `name` is omitted, Build logs the command instead.

If `require` is omitted, the task still runs, but Build will not check the environment first.

## The `require` line

The `require` line is a comma-separated list. Each item contains a command name followed by an optional version constraint.

```ini
require=node >=18, sass >=1.6, vendor/bin/sync ^1.3
```

These version constraints use Composer semver rules.

If the version is omitted, it defaults to `*`, which means “the command only needs to exist”.

```ini
require=esbuild, vendor/bin/sitemap ^1.0
```
## The `execute` line

The `execute` line is split into the command and its arguments.

```ini
execute=sass ./style/style.scss ./www/style.css
```

Quoted arguments are supported:

```ini
execute=./node_modules/.bin/esbuild "script/my cool script.es6" --bundle --outfile=./www/script.js
```

There are a few parser rules to be aware of:

- `execute` is required
- the command part may not be empty
- quoted arguments must be terminated correctly
- the line may not contain `;`, `#`, or line breaks

Those restrictions keep the configuration focused on one command invocation per task.

## Full INI example

```ini
[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

[style/**/*.scss]
name=Compile Sass
require=sass >=1.6
execute=sass ./style/style.scss ./www/style.css

[page/**/*.php]
name=Generate sitemap
require=vendor/bin/sitemap ^1.0
execute=php vendor/bin/sitemap src/page www/sitemap.xml
```

## JSON is still supported

If a project already uses JSON, the same concepts are available through `build.json`, with `require` and `execute` written as nested objects.

See [[JSON configuration example]] for a complete example.

---

Next, move on to [[different environments]] to see how task definitions are overridden per mode.


One project often needs slightly different build steps in different places. A local development build may generate source maps, while a production build may omit them. Build handles this through _modes_.

## How modes are named

The mode name is inserted before the file extension:

- `build.ini` + mode `production` becomes `build.production.ini`
- `build.json` + mode `production` becomes `build.production.json`

To use a mode:

```bash
vendor/bin/build --mode production
vendor/bin/build -m dev
```

Build loads the base configuration first, then loads the mode file, then recursively merges the two.

## INI example

Base configuration:

`build.ini`

```ini
[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

[style/**/*.scss]
name=Compile Sass
require=sass >=1.6
execute=sass ./style/style.scss ./www/style.css
```

Production override:

`build.production.ini`

```ini
[script/**/*.es6]
name=Bundle JavaScript for production
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --minify --outfile=./www/script.js
```

The production file only contains the task that changes.

Running `vendor/bin/build --mode production` keeps the Sass task from `build.ini`, but replaces the `name` and `execute` values of the JavaScript task with those from `build.production.ini`.

## Partial overrides are allowed

Mode files do not need to repeat the whole task definition.

For example, if we only want to change the arguments in an execute command, we can override just that property and leave the requirements and block name alone.

## Adding tasks in a mode

A mode file can also introduce brand new tasks.

For example, a `build.dev.ini` file might add a sitemap generator or some diagnostic step that only runs during development.

## Missing mode files

If we ask for a mode and the corresponding file does not exist, Build stops with an error rather than silently continuing with the wrong configuration.

That makes deployment mistakes more obvious when they happen.

---

Next, read [[default config]] to see how shared defaults and project-specific overrides fit together.


Default configuration lets a framework, starter project, or shared internal tool provide a base set of build tasks without forcing every project to copy the same file.

If the project does not have its own build file, Build can fall back to the path supplied by `--default`.

```bash
vendor/bin/build --default ./config/build.default.ini
```

The default path may be either:

- a specific file such as `./config/build.default.ini`
- a directory containing `build.ini` or `build.json`

## How Build chooses between project and default config

Build checks for the project configuration first.

If a project configuration is found, that file is used.
If no project configuration is found, Build tries the default path.

This makes defaults a good fit for frameworks and skeleton applications: projects can accept the shared configuration as-is, or add their own file when they need to customise it.

## Overriding shared defaults

Once a project supplies its own `build.ini` or `build.json`, that project file becomes the active configuration.

This is useful when the shared default covers most projects, but one application needs a different entry point, a production-only optimisation, or an extra task for a particular directory.

Mode files continue to work in the usual way on top of whichever base configuration is active.

## WebEngine

WebEngine exposes Build through `gt build`, so it can provide framework-level defaults while still allowing application projects to define their own configuration when required.

The Build repository is maintained separately, so the behaviour described here applies whether Build is used inside WebEngine or on its own.

---

From here, continue to see a [[JSON configuration example]].


Build now recommends `build.ini`, but JSON remains fully supported.

The JSON format represents the same ideas with nested objects:

- the top-level keys are glob patterns
- each task may contain `name`, `require`, and `execute`
- `execute` contains `command` and `arguments`

## Example `build.json`

```json
{
	"script/**/*.es6": {
		"name": "Bundle JavaScript",
		"require": {
			"node_modules/.bin/esbuild": ">=0.17",
			"node": ">=18"
		},
		"execute": {
			"command": "./node_modules/.bin/esbuild",
			"arguments": [
				"./script/app.es6",
				"--bundle",
				"--sourcemap",
				"--outfile=./www/script.js"
			]
		}
	},
	"style/**/*.scss": {
		"name": "Compile Sass",
		"require": {
			"sass": ">=1.6"
		},
		"execute": {
			"command": "sass",
			"arguments": [
				"./style/style.scss",
				"./www/style.css"
			]
		}
	},
	"asset/**/*": {
		"name": "Publish static assets",
		"require": {
			"vendor/bin/sync": "^1.3"
		},
		"execute": {
			"command": "vendor/bin/sync",
			"arguments": [
				"./asset",
				"./www/asset",
				"--symlink"
			]
		}
	}
}
```

## JSON and INI side by side

The same JavaScript task written in INI looks like this:

```ini
[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js
```

The behaviour is the same. The choice is mainly about which format fits the project better.

## Mode files in JSON

Mode files work in exactly the same way as with INI.

Base file:

`build.json`

```json
{
	"script/**/*.es6": {
		"name": "Bundle JavaScript",
		"execute": {
			"command": "./node_modules/.bin/esbuild",
			"arguments": ["./script/app.es6", "--bundle", "--sourcemap", "--outfile=./www/script.js"]
		}
	}
}
```

Override file:

`build.production.json`

```json
{
	"script/**/*.es6": {
		"name": "Bundle JavaScript for production",
		"execute": {
			"arguments": ["./script/app.es6", "--bundle", "--minify", "--outfile=./www/script.js"]
		}
	}
}
```

When we run `vendor/bin/build --mode production`, Build merges the two objects and keeps any properties not overridden by the mode file.




---

# Documentation: Cipher

Two-way encryption of messages for secure plain text transmission.

When messages are passed between two systems over a public network, encryption tools are needed to protect the content in transit. Encrypting and decrypting messages correctly can be fiddly and error-prone, so this library keeps the process small and explicit through the `PlainTextMessage`, `EncryptedMessage`, `CipherText`, `Key`, and `InitVector` abstractions.

Pass your secret message to the `PlainTextMessage` constructor, then call `encrypt()` with a shared `Key` to produce a `CipherText`. The encrypted payload is represented by the cipher text itself plus the IV returned by `getIv()`. Those values can then be passed to the receiver by any communication mechanism, with only the holder of the same shared key able to decrypt the original message.

On the receiving side, construct an `EncryptedMessage` with the incoming cipher text and IV, then call `decrypt()` with the same `Key` to recover the original plain text.

The `CipherText` class also provides a `getUri()` method for creating a pre-encoded URI. A URI containing `cipher` and `iv` query string parameters can then be passed to `EncryptedUri` and decrypted back into a `PlainTextMessage`.

## A very small example

```php
use GT\Cipher\Key;
use GT\Cipher\Message\EncryptedMessage;
use GT\Cipher\Message\PlainTextMessage;

$key = new Key();
$plainText = new PlainTextMessage("Hello, PHP.GT!");
$cipherText = $plainText->encrypt($key);

$received = new EncryptedMessage((string)$cipherText, $plainText->getIv());
echo $received->decrypt($key);
```

The message starts as plain text, is encrypted with a shared key, then reconstructed and decrypted on the receiving side using the same key and IV.

---

To see where each class fits before wiring anything up, continue to [[Overview]].


Cipher is intentionally small. Rather than exposing a large encryption framework, it wraps one clear workflow around libsodium's `secretbox` functions.

The main idea is simple:

1. We start with a plain text message.
2. We encrypt it using a shared secret key and an initialisation-vector (IV).
3. We transmit the cipher text and IV.
4. We reconstruct the encrypted message on the receiving side.
5. We decrypt it using the same shared key.

## The main objects

### `Key`

`Key` holds the shared secret bytes. If we do not pass bytes into the constructor, a secure random key is generated for us.

Casting the object to a string gives us a base64 representation, which is convenient for storage or transport:

```php
$key = new GT\Cipher\Key();
echo (string)$key;
```

That string form is for transport or display. The actual encryption methods use the raw bytes internally.

### `InitVector`

Every message needs an IV. In this library, the `InitVector` is generated automatically when a message is constructed, unless we pass one in ourselves.

The IV is not secret, but it is still required for decryption. If we send cipher text to another system, we must send the IV alongside it.

> [!NOTE]
> In cryptography, an Initialisation Vector is sometimes also known as a "nonce" [See wikipedia's page for more information](https://en.wikipedia.org/wiki/Cryptographic_nonce).

### `PlainTextMessage`

This is the object we construct when we have clear text data and want to encrypt it.

```php
use GT\Cipher\Message\PlainTextMessage;

$message = new PlainTextMessage("Quarterly figures attached");
```

Calling `encrypt()` returns a `CipherText` object:

```php
$cipherText = $message->encrypt($key);
```

### `CipherText`

`CipherText` represents the encrypted bytes. Casting it to a string gives the base64 encoded cipher text that we would usually transmit to another system.

It also has `getUri()`, which appends the cipher text and IV to a URI as `cipher` and `iv` query string parameters.

### `EncryptedMessage`

This is the receiving-side counterpart to `PlainTextMessage`. We construct it from the incoming cipher text and IV, then call `decrypt()` with the same key.

### `EncryptedUri`

If the sender chose to transmit the encrypted message in a query string, `EncryptedUri` can read the URI, extract the `cipher` and `iv` values, and decrypt them in one step.

## What Cipher does not try to do

This library does not handle:

- key exchange between systems
- public/private key cryptography
- long-term secret storage
- signing or authenticity checks beyond what `secretbox` itself provides
- message serialisation beyond strings and query string transport

That is deliberate. Cipher keeps one common secret-key message flow small, readable, and easy to reuse.

## Choosing the right entry point

- Use `PlainTextMessage` and `EncryptedMessage` when you are sending cipher text and IV separately.
- Use `CipherText::getUri()` and `EncryptedUri` when you are sending encrypted data through a link or redirect.
- Use `Key` directly when you need to generate, serialise, or reconstruct a shared key.

---

Now that the shape of the library is clear, move on to [[Getting started]].


This guide shows the smallest useful setup for encrypting and decrypting one message.

## 1. Install the package

```bash
composer require phpgt/cipher
```

The package requires the `sodium` extension. On current PHP versions this is usually available already, but it still needs to be enabled in the runtime environment.

## 2. Create a shared key

Cipher uses symmetric encryption, so both sides must know the same key.

```php
use GT\Cipher\Key;

$sharedKey = new Key();
```

If one side generates the key, the other side must receive the same bytes through a secure channel.

## 3. Create a plain text message

```php
use GT\Cipher\Message\PlainTextMessage;

$message = new PlainTextMessage("Hello from Cipher");
```

At this point the message also has an IV attached internally.

## 4. Encrypt the message

```php
$cipherText = $message->encrypt($sharedKey);
```

Now we have three important pieces of data:

- the key
- the IV
- the cipher text

The key must remain secret. The IV and cipher text can be transmitted to the receiver.

For example, the sender might transmit these text-safe values:

```php
$outgoingCipher = (string)$cipherText;
$outgoingIv = (string)$message->getIv();
```

## 5. Reconstruct the encrypted message on the receiving side

```php
$encryptedMessage = new EncryptedMessage($incomingCipher, $incomingIv);
```

The `EncryptedMessage` constructor takes the incoming base64 cipher string plus the incoming base64 IV. When the IV is supplied as a string, it is converted internally into an `InitVector` from base64.

## 6. Decrypt using the same key

```php
$decryptedMessage = $encryptedMessage->decrypt($sharedKey);
echo $decryptedMessage;
```

The output is a new `PlainTextMessage`, so it can be cast straight to a string.

## Full example

```php
use GT\Cipher\Key;
use GT\Cipher\Message\EncryptedMessage;
use GT\Cipher\Message\PlainTextMessage;

$sharedKey = new Key();
$message = new PlainTextMessage("Hello from Cipher");
$cipherText = $message->encrypt($sharedKey);
$cipherString = (string)$cipherText;
$ivString = (string)$message->getIv();

// Send $outgoingCipher and $outgoingIv to the receiver...
// ... then on the receiver:

$encryptedMessage = new EncryptedMessage(
	$cipherString,
	$ivString,
);

echo $encryptedMessage->decrypt($sharedKey);
```

## A note on sharing the key

In the example above, both sides are in the same PHP script just to keep the flow visible. In a real system:

- the sender and receiver are usually separate processes or separate machines
- both sides must already know the same secret key
- the key should not be transmitted in the same channel as the encrypted payload

---

With the basic flow working, continue to [[Encrypting and decrypting messages]] for a closer look at each step.


Once the basic setup is in place, the normal message flow is built around `PlainTextMessage`, `CipherText`, and `EncryptedMessage`.

## Encrypting a plain text message

The sender starts by creating a `PlainTextMessage`:

```php
use GT\Cipher\Message\PlainTextMessage;

$message = new PlainTextMessage("Launch code: tea and biscuits");
```

Calling `encrypt()` produces a `CipherText` object:

```php
use GT\Cipher\Key;

$key = new Key();
$cipherText = $message->encrypt($key);
```

At that point:

- `(string)$cipherText` is the base64 encoded cipher string
- `$message->getIv()` returns the `InitVector` used for encryption

The `CipherText` object itself keeps the raw encrypted bytes, but it is usually the base64 form that we transmit.

## What needs to be transmitted

To decrypt successfully, the receiving side needs:

- the cipher text
- the IV
- the same shared key

Only the key must remain secret. The IV is part of the normal payload.

## Decrypting an incoming message

On the receiving side we construct `EncryptedMessage` using the incoming cipher text string and IV:

```php
$received = new EncryptedMessage(
	$cipherString,
	$ivString,
);
```

Here the IV is shown in its transmitted base64 string form. `EncryptedMessage` will convert it internally into an `InitVector`.

Then decrypt using the same key:

```php
$plainText = $received->decrypt($key);
echo $plainText;
```

The return value is a `PlainTextMessage`, not a raw string. That keeps the API symmetric and lets us keep using the same message abstraction if needed.

## Supplying your own IV

`PlainTextMessage` creates a fresh IV by default, but we can also provide one explicitly:

```php
use GT\Cipher\InitVector;
use GT\Cipher\Message\PlainTextMessage;

$iv = new InitVector();
$message = new PlainTextMessage("Fixed IV example", $iv);
```

In normal usage, letting the library generate the IV is the safest and simplest option.

## String representations

The library uses string casting consistently:

- `(string)$message` gives the plain text content
- `(string)$cipherText` gives the base64 cipher text
- `(string)$message->getIv()` gives the base64 IV
- `(string)$key` gives the base64 key

That makes it straightforward to serialise values into JSON, query strings, logs, or storage layers. We should still take care never to expose the key in logs or browser-visible output.

## Receiving from another process

If the receiver is reconstructing the key from a stored base64 string, decode it first:

```php
use GT\Cipher\Key;

$storedBase64Key = "…";
$key = new Key(base64_decode($storedBase64Key));
```

If the IV was also received as a base64 string, it can usually be passed straight into `EncryptedMessage`:

```php
$received = new EncryptedMessage($cipherString, $storedBase64Iv);
```

If you need an `InitVector` object separately for some reason, you can still reconstruct it manually:

```php
use GT\Cipher\InitVector;

$iv = (new InitVector())->withBytes(base64_decode($storedBase64Iv));
```

That gives us both options: the simple string-based constructor path for normal receiving code, and the explicit `InitVector` reconstruction when an object is needed elsewhere.

---

If your transport mechanism is a URL rather than separate fields, continue to [[Encrypted URIs]].


One of the main usages of this library is the URI workflow. Instead of transmitting cipher text and IV as separate values, we can embed them directly into a URI.

This is useful for:

- redirects between applications
- links sent between trusted systems
- callback URLs that need to carry a small encrypted payload

## Creating an encrypted URI

Start with a normal encrypted message flow:

```php
use GT\Cipher\Key;
use GT\Cipher\Message\PlainTextMessage;

$key = new Key();
$message = new PlainTextMessage("Signed in as account 105");
$cipherText = $message->encrypt($key);
```

Then append the encrypted values to a base URI:

```php
$uri = $cipherText->getUri("https://example.com/receiver.php");
echo $uri;
```

The returned URI will contain two query string parameters:

- `cipher`
- `iv`

If the base URI already has a query string, those values are added alongside the existing parameters.

## Decrypting from the incoming URI

On the receiving side, construct `EncryptedUri` from the request URI:

```php
use GT\Cipher\EncryptedUri;

$encryptedUri = new EncryptedUri((string)$uri);
$plainText = $encryptedUri->decryptMessage($key);

echo $plainText;
```

`decryptMessage()` returns a `PlainTextMessage`.

## Using custom query string parameter names

If `cipher` and `iv` do not fit the surrounding application, we can supply custom names:

```php
$encryptedUri = new EncryptedUri(
	$requestUri,
	"payload",
	"rand",
);
```

The constructor then expects those parameter names instead of the defaults.

## Missing parameter behaviour

If either required parameter is absent or empty, Cipher throws `MissingQueryStringException`.

That helps distinguish:

- malformed links
- tampered links
- requests that were never meant for this decrypting endpoint

## URI safety notes

Encrypting a message does not make a URI invisible. The full URL may still be stored in:

- browser history
- access logs
- proxy logs
- analytics tools

Cipher protects the message content, but we should still think carefully before placing sensitive data in any URL.

For highly sensitive flows, POST bodies or server-side session state may still be the better transport choice.

---

For a closer look at the small helper objects used throughout the library, continue to [[Key and IV objects]].


`Key` and `InitVector` are deliberately tiny classes, but they are central to how the rest of the library stays readable.

## `Key`

`Key` wraps the raw bytes used as the shared secret.

### Creating a new random key

```php
use GT\Cipher\Key;

$key = new Key();
```

With no constructor argument, Cipher generates cryptographically secure random bytes of the correct length.

### Reconstructing an existing key

```php
$storedBase64 = "…";
$key = new Key(base64_decode($storedBase64));
```

This is the usual approach when the key comes from configuration, a secrets store, or another trusted process.

### Converting to a string

```php
echo (string)$key;
```

Casting to a string returns a base64 representation of the key bytes.

That is useful for storage, but the string should still be treated as secret material.

### Accessing raw bytes

```php
$bytes = $key->getBytes();
```

The raw bytes are what libsodium uses internally.

## `InitVector`

`InitVector` represents the random data used during encryption and decryption.

### Creating an IV

```php
use GT\Cipher\InitVector;

$iv = new InitVector();
```

In practice, we often do not need to do this ourselves because `PlainTextMessage` creates one automatically.

### Converting to a string

```php
echo (string)$iv;
```

The string value is base64 encoded, which makes it suitable for transmission in query strings or other text-safe transports.

### Reconstructing from bytes

```php
$iv = (new InitVector())->withBytes(base64_decode($storedBase64Iv));
```

`withBytes()` returns a cloned object with the supplied bytes, leaving the original object untouched.

### Valid byte length

If we pass an invalid length less than `1` to the constructor, Cipher throws `CipherException`.

```php
new InitVector(0); // throws
```

## Key and IV responsibilities

It is useful to keep their roles separate:

- the key is secret and must stay private
- the IV is not secret, but it must match the encrypted message
- both are required for successful decryption

## A practical pattern

One common pattern is:

1. Generate the key once and store it securely.
2. Generate a fresh IV for each message.
3. Transmit the IV with the encrypted payload.
4. Reuse the same key only between the systems that are meant to trust each other.

Cipher fits neatly around that model.

---

Next, read [[Error handling]] to see how failures are surfaced by the API.


## Base exception

All library-specific exceptions extend `GT\Cipher\CipherException`.

If we only need one catch block for any Cipher failure, catching that base type is usually enough:

```php
use GT\Cipher\CipherException;

try {
	// encrypt or decrypt here
}
catch(CipherException $exception) {
	// handle all Cipher-specific failures
}
```

## Encryption failures

`CipherText` throws `EncryptionFailureException` when encryption cannot be completed.

This generally means libsodium rejected the inputs, such as an invalid key size.

## Message decryption failures

`EncryptedMessage::decrypt()` throws `GT\Cipher\Message\DecryptionFailureException` when:

- the cipher text is malformed
- the key or IV does not match
- libsodium rejects the inputs

That allows the receiving application to treat the payload as unreadable without exposing any secret detail.

## URI decryption failures

`EncryptedUri::decryptMessage()` throws `UriDecryptionFailureException` when the URI contains cipher and IV values but decryption still fails.

In practice that often means:

- the wrong key was used
- the URI was altered
- the cipher text was not valid

## Missing URI parameters

The `EncryptedUri` constructor throws `MissingQueryStringException` when the required `cipher` or `iv` parameter is missing or empty.

The exception message contains the missing parameter name, which is useful when responding with validation errors or debugging integration issues.

## Working with previous exceptions

Where libsodium throws internally, Cipher wraps the original throwable as the `previous` exception.

That means application code can log the full exception chain during development while still presenting a cleaner message to the end user.

## Typical handling approach

For most applications, the following pattern is enough:

```php
use GT\Cipher\CipherException;

try {
	$plainText = $encryptedUri->decryptMessage($key);
}
catch(CipherException $exception) {
	http_response_code(400);
	echo "The encrypted message could not be read.";
}
```

That keeps the external response calm and predictable without leaking implementation details.

---

To see the library running end-to-end, continue to [[Examples]].


The `example/` directory is the quickest way to see the main workflows without building a larger application around them first.

Run an example from the repository root:

```bash
php example/01-encrypt-decrypt-message.php
```

## Example index

1. [example/01-encrypt-decrypt-message.php](https://github.com/PhpGt/Cipher/blob/master/example/01-encrypt-decrypt-message.php)
   Basic message encryption and decryption using `PlainTextMessage` and `EncryptedMessage`.
2. [example/02-encrypt-message-in-uri.php](https://github.com/PhpGt/Cipher/blob/master/example/02-encrypt-message-in-uri.php)
   Embedding encrypted content into a URI and reading it back with `EncryptedUri`.
3. [example/03-share-key-between-processes.php](https://github.com/PhpGt/Cipher/blob/master/example/03-share-key-between-processes.php)
   Reconstructing the same shared key from a base64 string on the receiving side.

## Repository root demos

There are also a few small scripts in the repository root which show the lower-level building blocks:

- [sodium.php](https://github.com/PhpGt/Cipher/blob/master/sodium.php): a direct libsodium demonstration with Cipher's exception types
- [sodium-lib.php](https://github.com/PhpGt/Cipher/blob/master/sodium-lib.php): message encryption and decryption using the library API
- [sodium-lib-uri.php](https://github.com/PhpGt/Cipher/blob/master/sodium-lib-uri.php): URI-based encryption and decryption using the library API

Those scripts are useful when reading through the repository history or comparing the raw sodium calls with the higher-level abstractions.

## What the examples are good for

The examples are especially helpful when we want to:

- verify the expected string forms of keys, IVs, and cipher text
- see the sender and receiver flow side by side
- test the package quickly in a local shell

---

If you want the class and method list in one place, finish with [[API reference]].


This page is a compact reference for Cipher's public API.

For walkthroughs and fuller explanations, use the earlier pages in the guide.

## Core value objects

### `GT\Cipher\Key`

- `__construct(?string $bytes = null)`
- `__toString(): string`
- `getBytes(): string`

### `GT\Cipher\InitVector`

- `__construct(int $byteLength = SODIUM_CRYPTO_BOX_NONCEBYTES)`
- `getBytes(): string`
- `withBytes(string $bytes): self`
- `__toString(): string`

### `GT\Cipher\CipherText`

- `__construct(string $data, InitVector $iv, Key $key)`
- `__toString(): string`
- `getBytes(): string`
- `getUri(string|Psr\Http\Message\UriInterface $baseUri = ""): Psr\Http\Message\UriInterface`

### `GT\Cipher\EncryptedUri`

- `__construct(string|Psr\Http\Message\UriInterface $uri, string $cipherQueryStringParameter = "cipher", string $initVectorStringParameter = "iv")`
- `decryptMessage(Key $key): GT\Cipher\Message\PlainTextMessage`

## Message classes

### `GT\Cipher\Message\AbstractMessage`

- `__construct(string $data, ?GT\Cipher\InitVector $iv = null)`
- `__toString(): string`
- `getIv(): GT\Cipher\InitVector`

### `GT\Cipher\Message\PlainTextMessage`

- `encrypt(GT\Cipher\Key $key): GT\Cipher\CipherText`

### `GT\Cipher\Message\EncryptedMessage`

- `decrypt(GT\Cipher\Key $key): GT\Cipher\Message\PlainTextMessage`

## Exception classes

### Base type

- `GT\Cipher\CipherException`

### Encryption and URI exceptions

- `GT\Cipher\EncryptionFailureException`
- `GT\Cipher\MissingQueryStringException`
- `GT\Cipher\UriDecryptionFailureException`

### Message exceptions

- `GT\Cipher\Message\DecryptionFailureException`

## Typical data flow

### Separate fields

```php
$message = new GT\Cipher\Message\PlainTextMessage("hello");
$cipherText = $message->encrypt($key);

$received = new GT\Cipher\Message\EncryptedMessage(
	(string)$cipherText,
	$message->getIv(),
);

$plainText = $received->decrypt($key);
```

### Query string transport

```php
$message = new GT\Cipher\Message\PlainTextMessage("hello");
$cipherText = $message->encrypt($key);
$uri = $cipherText->getUri("https://example.com/");

$received = new GT\Cipher\EncryptedUri((string)$uri);
$plainText = $received->decryptMessage($key);
```

## Related package requirements

- PHP `>= 8.4`
- `ext-sodium`
- `phpgt/http`




---

# Documentation: Cli

`phpgt/cli` is a command line interface builder for creating multi-command terminal applications with typed arguments, option parsing, usage generation and testable I/O streams.

The primary entry point is the `Application` class, which coordinates command discovery, argument parsing and output handling. Commands extend `Gt\Cli\Command\Command` and declare their contract through required/optional named parameters and required/optional flags/options.

The purpose of this library is to keep command line tools explicit and maintainable. Instead of reading raw `$argv` manually, each command receives an `ArgumentValueList`, giving predictable access to passed values and reducing parsing errors.

Beyond argument parsing, this library includes built-in `help` and `version` commands, stream abstraction for unit testing, enum-backed stream selection through `StreamName`, colour-aware output through `Palette`, and interactive terminal helpers such as cursor movement and progress bars.

A typical example
=================

The following script is a minimal command from `example/02-greeter.php`.

```php
$greeterCommand = new class extends Command {
	public function run(?ArgumentValueList $arguments = null):int {
		$name = (string)$arguments->get("name", "you");
		$this->output("Hello, $name!");
		return 0;
	}

	public function getName():string {
		return "greet";
	}

	public function getDescription():string {
		return "Greet a person by name";
	}

	public function getRequiredNamedParameterList():array {
		return [];
	}

	public function getOptionalNamedParameterList():array {
		return [
			new NamedParameter("name"),
		];
	}

	public function getRequiredParameterList():array {
		return [];
	}

	public function getOptionalParameterList():array {
		return [];
	}
};
```

The command takes an optional positional argument (`name`) and falls back to `you` when no value is passed, producing either `Hello, Greg!` or `Hello, you!`.

Command exit codes
==================

`Command::run()` must return an `int` exit code.

- Return `0` for success.
- Return a non-zero code to end the application with that code.

This gives commands a predictable way to exit early and makes CLI return-code handling explicit.

***

In the next section we will walk through all bundled [[examples]].

You can also jump ahead to [[output streams]] for standard/error output, or [[progress bars]] for in-place terminal updates.


The `example/` directory contains runnable scripts that progress from simple output to full multi-command applications.

To run any example from the project root:

```bash
php example/01-hello-world.php
```

Example index
=============

1. `01-hello-world.php`
Outputs a single message using command output helpers.

2. `02-greeter.php`
Accepts an optional named argument and prints a personalised greeting.

3. `03-colour.php`
Demonstrates one-off coloured output and persistent output palettes.

4. `04-parameters-and-flags.php`
Shows required named arguments, optional named arguments, required options and optional flags together.

5. `05-interactive.php`
Demonstrates interactive input with `readLine()` when optional arguments are omitted.

6. `06-multi-command.php`
Creates a multi-command CLI with `sum`, `repeat`, and built-in `help`.

7. `07-repeating-lines.php`
Demonstrates suppression markers for repeated consecutive output lines.

8. `08-progress-bar.php`
Shows an in-place progress bar that updates on one terminal line.

The examples are intentionally small and anonymous-class based so they can be copied directly into new scripts while keeping setup noise low.

***

Next, read [[parameters and arguments]] for how command contracts are defined.


Commands declare their interface by implementing four parameter list methods:

- `getRequiredNamedParameterList()`
- `getOptionalNamedParameterList()`
- `getRequiredParameterList()`
- `getOptionalParameterList()`

Named parameters map to positional values (`deploy production api`), while `Parameter` definitions map to options and flags (`--tag v1.2.3`, `--verbose`).

Defining command contracts
==========================

```php
public function getRequiredNamedParameterList():array {
	return [
		new NamedParameter("environment"),
	];
}

public function getOptionalNamedParameterList():array {
	return [
		new NamedParameter("service"),
	];
}

public function getRequiredParameterList():array {
	return [
		new Parameter(true, "tag", "t", "Release tag to deploy"),
	];
}

public function getOptionalParameterList():array {
	return [
		new Parameter(false, "dry-run", "d", "Preview only"),
		new Parameter(false, "verbose", "v", "Show extra detail"),
	];
}
```

Reading values in `run()`
=========================

```php
$environment = (string)$arguments->get("environment");
$service = (string)$arguments->get("service", "web");
$tag = (string)$arguments->get("tag");
$dryRun = $arguments->contains("dry-run");
$verbose = $arguments->contains("verbose");
```

The `get($key, $default)` pattern allows simple defaults for optional values, while `contains($key)` is used for boolean flags.

When required values are missing, command execution fails with explicit exceptions (`MissingRequiredParameterException`, `MissingRequiredParameterValueException`) and usage text is printed automatically.

***

Next, see [[coloured output]] for consistent terminal styling.


Output streams
==============

Command output is written to `StreamName::OUT` by default. To write to another stream, pass a `StreamName` enum value to the output helper.

```php
use GT\Cli\StreamName;

$this->writeLine("Saved successfully");
$this->writeLine("Could not save file", StreamName::ERROR);
```

The available stream names are:

- `StreamName::IN`
- `StreamName::OUT`
- `StreamName::ERROR`

Using `StreamName` prevents accidental writes to unknown stream names. Passing a raw string such as `"error"` is not supported.

Writing output
==============

`writeLine()` appends a line ending after the message. `write()` writes the message exactly as provided.

```php
$this->write("Downloading...");
$this->writeLine("done");
```

Both helpers accept a `StreamName` argument:

```php
$this->write("Warning: ", StreamName::ERROR);
$this->writeLine("configuration file missing", StreamName::ERROR);
```

Colour and streams
==================

The `output()` helper writes a coloured line and also accepts a stream name as its fourth argument:

```php
$this->output(
	"Could not connect",
	Palette::RED,
	null,
	StreamName::ERROR
);
```

Progress bars and cursor helpers also use `StreamName` when you need to target a stream other than standard output.

***

Next, read [[coloured output]] for terminal styling, or [[progress bars]] for in-place updates.


Colour support is provided through `Palette` and command-level output helpers.

There are two output modes:

- One-off colour for a single message
- Persistent palette for subsequent messages until reset

Basic usage
===========

```php
$this->output("Single green message", Palette::GREEN);

$this->setOutputPalette(Palette::RED, Palette::BLACK);
$this->output("This line uses red on black");
$this->output("So does this one");

$this->resetOutputPalette();
$this->output("Palette reset to terminal default");
```

`output()` writes a line and applies ANSI escape codes when a foreground/background palette is present. One-off colours reset automatically after that message, while persistent palettes remain active until `resetOutputPalette()`.

To send coloured output to another stream, pass a `StreamName` enum as the fourth argument:

```php
$this->output(
	"Error: deployment failed",
	Palette::RED,
	null,
	StreamName::ERROR
);
```

This makes it practical to standardise message types, for example:

- Success: `Palette::GREEN`
- Warnings: `Palette::YELLOW`
- Errors: `Palette::RED`
- Verbose/debug: `Palette::CYAN`

***

Next, read [[output streams]] for stream selection, or [[multiple commands]] to structure larger CLI applications.


A single `Application` can host multiple commands. The first CLI argument selects the command name, and remaining arguments are parsed according to that command's declared parameters.

Creating a multi-command app
============================

```php
$app = new Application(
	"Multi-command example",
	new ArgumentList(...$argv),
	$sumCommand,
	$repeatCommand
);
$app->run();
```

In `example/06-multi-command.php`:

- `sum left right` validates numeric input and prints a total
- `repeat text [count]` repeats user text with an optional count
- `help` is automatically available for global and per-command usage

Command-level errors can throw `CommandException`, which is caught by the application and displayed on the error stream.

```php
if(!is_numeric($left) || !is_numeric($right)) {
	throw new CommandException("Both values must be numeric");
}
```

This keeps command logic focused while preserving consistent output and exit handling.

For manual error output inside a command, pass `StreamName::ERROR` to `writeLine()`:

```php
$this->writeLine("Could not read input file", StreamName::ERROR);
```

Commands may also return explicit exit codes from `run()`:

- `0` indicates success.
- Any non-zero value exits the application with that code.

***

Next, refer to [[output streams]] for stream selection, or [[examples]] for complete runnable scripts.


Progress bars
=============

`phpgt/cli` supports dynamic, in-place progress updates for long-running tasks.

Use the `ProgressBar` helper
============================

From inside a command, create a progress bar using `createProgressBar()`:

```php
$progressBar = $this->createProgressBar(100, "Installing", 30);

for($i = 0; $i <= 100; $i++) {
	$progressBar->setProgress($i);
	usleep(35_000);
}

$progressBar->finish("Installation complete");
```

This renders a single line that updates in place, similar to package manager output.

Progress bars write to `StreamName::OUT` by default. Pass a `StreamName` enum as the fourth argument to target a different stream:

```php
$progressBar = $this->createProgressBar(
	100,
	"Installing",
	30,
	StreamName::ERROR
);
```

ProgressBar API
===============

- `setProgress(int $current, ?string $label = null): void`
Set an absolute progress value.
- `advance(int $amount = 1, ?string $label = null): void`
Increment progress by a relative amount.
- `finish(?string $label = null): void`
Complete the bar and end the line.

Cursor management
=================

Cursor movement is exposed through both `Stream` and command helper methods:

- `saveCursorPosition()`
- `restoreCursorPosition()`
- `moveCursorUp(int $amount = 1)`
- `moveCursorDown(int $amount = 1)`
- `moveCursorForward(int $amount = 1)`
- `moveCursorBack(int $amount = 1)`
- `setCursorColumn(int $column = 1)`
- `rewindCursor()`
- `clearLine()`

These methods make it easy to build interactive terminal UIs beyond progress bars. Each cursor helper accepts an optional `StreamName` argument when cursor control should be written somewhere other than standard output.

***

See [[output streams]] for stream selection, or [[examples]] for runnable scripts including `example/08-progress-bar.php`.




---

# Documentation: Config

[PHP.GT/Config](https://php.gt/config) parses INI files for managing application configuration, allowing you to override files and environment variables. It keeps configuration grouped into named sections, gives you typed access to values, and provides tools for loading and writing config from both PHP code and the command line.

Storing application configuration in INI files allows us to keep default values in version control, layer environment-specific overrides on top, and encapsulate sections of configuration, passing data to the parts of the application that need it.

The library has four main areas:

### 1. Load configuration from files

The `ConfigFactory` looks for a project's `config.ini` files, parses them, and combines them in the correct order.

```php
use GT\Config\ConfigFactory;

$config = ConfigFactory::createForProject(__DIR__);
```

### 2. Read values safely

The `Config` object supports dot notation and typed getters.

```php
$host = $config->getString("database.host");
$port = $config->getInt("database.port");
$debug = $config->getBool("app.debug");
```

### 3. Work with sections

Configuration can be split into logical groups, and an individual `ConfigSection` can be passed to a service that only needs one area of configuration.

```php
$dbConfig = $config->getSection("database");
$password = $dbConfig?->getString("password");
```

### 4. Generate or write config files

Deployment config can be created from CI scripts using the bundled `config-generate` command, or by writing a `Config` object back to disk in PHP.

```bash
vendor/bin/config-generate staging "database.host=staging-db.internal"
```

***

To begin, let us look at some [[Example config files]].


An application's configuration is stored in INI files. Each file is split into sections, and each section contains key-value pairs.

Here is a simple `config.ini`:

```ini
[app]
namespace=MyApp
debug=true

[database]
driver=mysql
host=localhost
schema=myapp
port=3306
username=app_user
password=app_pass

[stripe]
api_key=pk_test_80dbaff1f54f61fe104ce87832ae6c4e
secret_key=sk_test_de297e4be8dbc589d309ba04541d58db
```

In this example we can see three sections:

+ `[app]` for application-wide settings
+ `[database]` for connection details
+ `[stripe]` for payment platform API credentials

The keys within a section are later accessed using dot notation such as `database.host` or `stripe.secret_key`.

## Override files

Most applications need different configuration in different environments. Rather than duplicating the entire config file, this library allows smaller override files to replace only the values that change.

For example, a production override file might look like this:

```ini
[database]
host=live-db.example.com
username=live-example
password=260d153ad1bc8b5b

[stripe]
api_key=pk_live_b3d585b7ef94ba3f2fe0645e046834e2
secret_key=sk_live_322c5de70ec80aa99c33280b0b8516fe
```

Only the keys that need to change have to be present. Everything else is inherited from the earlier config files.

> [!NOTE]
> It's important to not store API keys within version control. In the examples above, we're assuming the config values are placed in override files manually, or generate on-the-fly by the `config-generate` script.

## Typed values

When the INI files are parsed, PHP's typed INI scanner is used. This means values such as booleans and integers are preserved rather than always being treated as plain strings.

For example:

```ini
[app]
debug=true
workers=4
cache_ttl=60
```

These can then be read with typed getters:

```php
$debug = $config->getBool("app.debug");
$workers = $config->getInt("app.workers");
$cacheTtl = $config->getInt("app.cache_ttl");
```

## Naming conventions

The factory looks for config files in a fixed order:

+ `config.default.ini`
+ `config.ini`
+ `config.dev.ini`
+ `config.deploy.ini`
+ `config.production.ini`

If an environment variable exists for a key, it takes precedence over the file value. Dots are replaced with underscores, so `database.password` becomes `database_password`.

***

In the next section we will look at [[Automatically loading config]].


The easiest way to use this library is through `ConfigFactory`. It looks for known config files, parses each one, and combines them into a single `Config` object.

```php
use GT\Config\ConfigFactory;

$config = ConfigFactory::createForProject(__DIR__);
```

Under the hood, file parsing is performed by `IniParser`, but in most applications there is no need to instantiate the parser directly because the factory already handles file discovery and merge order.

## Load order

Files are loaded in this order:

+ `config.default.ini`
+ `config.ini`
+ `config.dev.ini`
+ `config.deploy.ini`
+ `config.production.ini`

Later files take priority over earlier files. Internally, each later file becomes the base configuration, and any missing values are filled from earlier files.

This means that if `config.ini` contains:

```ini
[database]
host=localhost
schema=myapp
```

and `config.dev.ini` contains:

```ini
[database]
host=dev-db.internal
```

the final values will be:

+ `database.host = dev-db.internal`
+ `database.schema = myapp`

## Loading project defaults first

`createForProject()` accepts a second argument for a default config file outside the project root. This is useful when a framework or shared package wants to supply a baseline config.

```php
$config = ConfigFactory::createForProject(
	__DIR__,
	__DIR__ . "/vendor/example/framework/config.default.ini"
);
```

Any project file can then override those defaults as usual.

## Loading a single file directly

If you want to parse one INI file without the automatic project lookup, call `createFromPathName()` instead.

```php
$config = ConfigFactory::createFromPathName(__DIR__ . "/config.ini");
```

If the file does not exist, `null` is returned.

## Environment variable overrides

Whenever a value is read through `Config::get()`, the environment is checked first. The key name uses underscores instead of dots, so:

+ `app.namespace` becomes `app_namespace`
+ `database.password` becomes `database_password`

For example, here we can override the password without changing any file:

```php
putenv("database_password=super-secret");
echo $config->get("database.password");
```

Non-empty environment variable values take precedence over the INI files.

## Automatic production detection

When `config.production.ini` is part of the loaded set, the factory automatically sets `app.production=true` unless that key is already defined somewhere else.

This gives two ways to decide production mode:

+ define `app.production` explicitly yourself
+ allow the presence of `config.production.ini` to imply production mode

The resulting `Config` object exposes this through `isProduction()`.

***

Now that the config is loaded, the next step is [[Working with the Config object]].


The `Config` object represents the fully loaded configuration for your application. It is made up of one or more `ConfigSection` objects, each identified by name.

## Constructing a config manually

Although most applications load config from INI files, the object can also be created directly in PHP.

```php
use GT\Config\Config;
use GT\Config\ConfigSection;

$config = new Config(
	new ConfigSection("app", [
		"namespace" => "MyApp",
		"debug" => "true",
	]),
	new ConfigSection("database", [
		"host" => "localhost",
		"port" => "3306",
	])
);
```

This is particularly useful in tests or when assembling config from another source before writing it out again.

## Reading values with dot notation

The most common operation is reading a single value using section and key separated by a dot.

```php
$appNamespace = $config->get("app.namespace");
$dbHost = $config->get("database.host");
```

If the section or key does not exist, `null` is returned.

## Typed getters

The `Config` class includes the typed getter methods from `PHP.GT/TypeSafeGetter`. This means we can ask for the shape of data we expect rather than casting everything ourselves.

```php
$debug = $config->getBool("app.debug");
$port = $config->getInt("database.port");
$ratio = $config->getFloat("cache.ratio");
$launchAt = $config->getDateTime("release.launch_at");
```

These methods return `null` when the key is missing.

## Accessing sections

If several values belong together, it is often better to access the whole section.

```php
$database = $config->getSection("database");
```

This returns a `ConfigSection` object or `null` if the section does not exist. We will look at sections in detail in the next chapter.

## Listing section names

To inspect what is available, call `getSectionNames()`.

```php
foreach($config->getSectionNames() as $name) {
	echo $name, PHP_EOL;
}
```

## Checking production mode

The `isProduction()` method returns a boolean indicating whether the configuration should be treated as production.

```php
if($config->isProduction()) {
	// production-only behaviour
}
```

This checks `app.production` first. If that key was not defined manually, the factory may have set it automatically when `config.production.ini` was loaded.

## Merging configuration objects

Sometimes there is a need to combine two `Config` objects manually. The preferred way to do this is `withMerge()`.

```php
$combined = $primary->withMerge($fallback);
```

The naming is important here: the current object keeps its existing values, and the passed config only fills any missing keys or sections. In other words, it behaves like adding fallback values.

For example:

```php
$primary = new Config(
	new ConfigSection("app", [
		"namespace" => "Shop",
	])
);

$fallback = new Config(
	new ConfigSection("app", [
		"namespace" => "DefaultApp",
		"timezone" => "Europe/London",
	])
);

$combined = $primary->withMerge($fallback);
```

The resulting config will contain:

+ `app.namespace = Shop`
+ `app.timezone = Europe/London`

## Deprecated mutable merge

There is also a `merge()` method, but it is deprecated. It mutates the current object and should be avoided in new code.

```php
$config->merge($fallback); // deprecated
```

Prefer `withMerge()` so your code stays predictable and easier to reason about.

***

In the next section we will work more closely with [[Working with Config Sections]].


A `ConfigSection` represents one named group of config values such as `[database]`, `[app]` or `[stripe]`.

Working with sections is useful when a class needs several related values but should not be handed the entire config object.

## Getting a section

Sections are retrieved from the main config object by name:

```php
$database = $config->getSection("database");
```

If the section does not exist, `null` is returned.

## Reading values from a section

Once we have a section, individual keys can be accessed without dot notation.

```php
$host = $database?->get("host");
$port = $database?->getInt("port");
```

Like `Config`, each section also supports typed getters from `PHP.GT/TypeSafeGetter`.

## Checking whether a key exists

Sometimes `null` is a valid outcome from `get()`, so it is useful to check explicitly whether a key exists.

```php
if($database && $database->contains("password")) {
	// password was defined
}
```

## Iterating over keys and values

`ConfigSection` implements `IteratorAggregate`, so it can be looped over directly.

```php
foreach($database as $key => $value) {
	echo "$key = $value", PHP_EOL;
}
```

This is useful when copying a section into another object or displaying configuration for diagnostics.

## Using array-style access

Sections also implement `ArrayAccess`, so values can be read using array syntax.

```php
echo $database["host"];
```

The section remains immutable, so writing or unsetting values using array syntax will throw an exception.

## Converting to an array

If another API expects a plain array, call `asArray()`.

```php
$databaseConfig = $database?->asArray() ?? [];
```

This returns the internal key-value data of the section.

## Creating modified copies

`ConfigSection` is immutable. To add or replace a value, use `with()` to create a new section instance.

```php
$newDatabase = $database->with("port", "3307");
```

The original section is unchanged, and the returned section contains the updated value.

This immutability is what allows `Config::withMerge()` to build combined configurations without mutating earlier objects.

***

Once we know how to read configuration, the final piece is [[Generating config files]].


This library can also write configuration back to disk. There are two ways to do this:

+ from the command line with `config-generate`
+ from PHP using `FileWriter`

## Generating files from the CLI

The package exposes a binary named `config-generate`.

```bash
vendor/bin/config-generate deploy \
	"database.host=staging-db.internal" \
	"database.schema=shop_branch_42" \
	"stripe.secret_key=secret-for-ci"
```

This creates a new INI file in the current working directory. The first argument controls the suffix, and the remaining arguments are key-value pairs written using dot notation.

The allowed suffixes are:

+ `dev`
+ `deploy`
+ `prod`

So the above example writes `config.deploy.ini`.

## CLI argument format

Each config value must be written as:

```text
section.key=value
```

For example:

+ `app.namespace=MyApp`
+ `database.host=localhost`
+ `exampleapi.key=abc123`

If the arguments are invalid, the command writes an error message to standard error.

Within PHP, the `Generator` class throws `GT\Config\InvalidArgumentException` when the suffix or key-value arguments are invalid.

## Writing a config file in PHP

If you already have a `Config` object, use `FileWriter` to write it as an INI file.

```php
use GT\Config\Config;
use GT\Config\ConfigSection;
use GT\Config\FileWriter;

$config = new Config(
	new ConfigSection("app", [
		"namespace" => "MyApp",
		"debug" => "true",
	]),
	new ConfigSection("database", [
		"host" => "localhost",
		"port" => "3306",
	])
);

$writer = new FileWriter($config);
$writer->writeIni(__DIR__ . "/config.generated.ini");
```

Any missing directories in the pathname are created automatically.

If the file cannot be written, `FileWriter` throws `GT\Config\ConfigException`.

## A note on production file naming

The CLI generator's production suffix is `prod`, which writes `config.prod.ini`.

The automatic project loader described earlier looks for `config.production.ini`.

That means if you want a generated file to be picked up automatically by `ConfigFactory::createForProject()`, you should either:

+ write `config.production.ini` yourself using `FileWriter`
+ rename the generated `config.prod.ini` as part of your deployment process

## Typical deployment usage

Here we can see how this is useful in continuous integration. A deployment pipeline can create a small override file containing secrets or environment-specific hosts without editing the committed `config.ini`.

```bash
vendor/bin/config-generate deploy \
	"database.host=$DB_HOST" \
	"database.password=$DB_PASSWORD" \
	"shopapi.key=$SHOP_API_KEY"
```

This keeps the committed config readable while still allowing dynamic values at deploy time.

***

If you are using this package inside the wider PHP.GT framework, continue to [[Config within WebEngine applications]].


`PHP.GT/WebEngine` uses this library to load project configuration during the request lifecycle. The framework supplies its own default config first, then your application's config files are layered on top.

In WebEngine, configuration is loaded with `ConfigFactory::createForProject()` using:

+ `vendor/phpgt/webengine/config.default.ini`
+ your project's `config.ini`
+ any local override files such as `config.dev.ini` or `config.production.ini`
+ matching environment variables

This means your application usually does not need to manually create a `Config` object. Instead, WebEngine constructs it and makes it available through the service container.

## Accessing config in page logic

In a page logic class, the config object is available as `$this->config`.

```php
namespace App\Page;

class Checkout {
	public function go():void {
		$currency = $this->config->get("app.currency");
		$isProduction = $this->config->isProduction();
	}
}
```

Here we can see that page logic can read individual values directly, including whether the application is currently running in production mode.

## Injecting config into services

WebEngine's default service loader can also inject the `Config` object into your own classes. This is useful when a service needs multiple values or an entire section.

```php
use GT\Config\Config;
use GT\Config\ConfigSection;

class PaymentGateway {
	public function __construct(
		private ConfigSection $stripeConfig,
	) {}
}
```

Then in a service loader:

```php
use GT\Config\Config;

class ServiceLoader {
	public function __construct(
		private Config $config,
	) {}

	public function loadPaymentGateway():PaymentGateway {
		$stripeConfig = $this->config->getSection("stripe");
		if(!$stripeConfig) {
			throw new RuntimeException("Missing [stripe] config section.");
		}

		return new PaymentGateway(
			$stripeConfig,
		);
	}
}
```

Passing the smallest useful section helps keep services focused. A payment service rarely needs the entire application config, and this style keeps that boundary clear.

## Database integration

WebEngine's default service loader already reads values from the `[database]` section to construct the database connection:

+ `database.driver`
+ `database.schema`
+ `database.host`
+ `database.port`
+ `database.username`
+ `database.password`

Because of that, the most common use of this library inside WebEngine is simply maintaining accurate INI files in the project root.

## Production mode in WebEngine

If your project includes `config.production.ini`, this library marks `app.production=true` automatically unless you have already defined `app.production` yourself. That means WebEngine code can call `isProduction()` without requiring a separate flag in most production deployments.

***

From here, it is useful to return to the main API and continue with [[Working with the Config object]].




---

# Documentation: Cookie

`phpgt/cookie` gives us an object oriented way to work with HTTP cookies without reading from and writing to the `$_COOKIE` superglobal throughout our application.

Cookies are small pieces of text sent by the browser with each request. They are useful for remembering lightweight client-side state, such as a preference, a tracking token, or the identifier used by a server-side session system.

Native PHP exposes incoming cookies through `$_COOKIE`, and sends outgoing cookies with the global `setcookie()` function. This library keeps that same browser behaviour, but wraps the cookie data in a small API that is easier to pass around, test, and understand where data is being changed.

> [!NOTE]
> WebEngine depends on this package as one of its small single-purpose components. In a WebEngine application, global variables are protected by default, so cookie access should be handled explicitly rather than by reaching into `$_COOKIE` throughout page logic.

## What this library covers

- Creating a `CookieHandler` from the current request cookies.
- Reading cookies using method calls or array-style syntax.
- Checking whether a cookie exists.
- Setting cookies by calling PHP's `setcookie()` behind the scenes.
- Deleting one cookie, several cookies, or every tracked cookie.
- Iterating over cookies and exporting them as a plain array.
- Representing individual cookies as immutable `Cookie` objects.
- Validating cookie names and values before they are accepted.

## A small example

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);

if(!$cookies->contains("firstVisit")) {
	$cookies->set(
		"firstVisit",
		date("c"),
		new DateTime("+30 days"),
		secure: true,
		httponly: true,
	);
}

echo $cookies["firstVisit"] ?? "Welcome!";
```

The `CookieHandler` lets us read cookies with the same familiar `["name"]` syntax as `$_COOKIE`, while still giving us explicit methods for operations that affect the browser response.

---

To start from the smallest working example, continue with the [[Quick start guide]].


In this guide we will build the smallest useful cookie flow: read an incoming cookie, set it if it does not exist, and delete it again when we no longer need it.

## 1. Install the package

```bash
composer require phpgt/cookie
```

## 2. Create a CookieHandler

In plain PHP, construct the handler from `$_COOKIE`:

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);
```

The constructor copies the current request cookies into `Cookie` objects. After construction, the handler is the object we pass around instead of the superglobal.

## 3. Read an existing cookie

We can check for a cookie before reading it:

```php
if($cookies->contains("theme")) {
	echo "Your saved theme is " . $cookies["theme"];
}
```

Array access is intentionally similar to `$_COOKIE`. If the cookie does not exist, `$cookies["theme"]` returns `null`.

## 4. Set a cookie

Use `set()` when we want the browser to store a cookie:

```php
$cookies->set(
	"theme",
	"dark",
	new DateTime("+1 year"),
	secure: true,
	httponly: true,
);
```

This updates the handler immediately and calls PHP's `setcookie()` so the browser receives the `Set-Cookie` response header.

> [!IMPORTANT]
> Cookies are sent as HTTP headers. In a plain PHP script, call `set()` or `delete()` before output has started, otherwise PHP may not be able to send the header.

## 5. Delete a cookie

When the cookie should no longer be used:

```php
$cookies->delete("theme");
```

The cookie is removed from the handler, and the browser is sent an expired cookie with the same name.

## 6. Use the handler in application code

Once the handler exists, pass it to the part of the application that needs cookies:

```php
function rememberTheme(CookieHandler $cookies, string $theme):void {
	$cookies->set(
		"theme",
		$theme,
		new DateTime("+1 year"),
		secure: true,
		httponly: true,
	);
}
```

That keeps the rest of the code independent from `$_COOKIE`, which makes the function easier to test and easier to reuse.

---

Next, see [[Reading cookies]] for all of the ways to inspect the handler.


`CookieHandler` is designed to feel familiar if we have used `$_COOKIE`, while still being explicit about the difference between reading cookies and sending new cookie headers.

## Constructing from request cookies

The most common starting point is the current request:

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);
```

The array keys become cookie names, and the array values become cookie values. Each entry is stored internally as a `Cookie` object.

For tests or command-line scripts, we can pass any `array<string, string>`:

```php
$cookies = new CookieHandler([
	"theme" => "dark",
	"currency" => "GBP",
]);
```

## Checking for a cookie

Use `contains()` when the code needs to know whether the cookie exists:

```php
if($cookies->contains("currency")) {
	echo "Currency preference found";
}
```

This is equivalent to using `isset()` with array access:

```php
if(isset($cookies["currency"])) {
	echo "Currency preference found";
}
```

## Reading a value

Array access returns the cookie value as a string:

```php
$currency = $cookies["currency"];
```

If the cookie does not exist, array access returns `null`:

```php
$currency = $cookies["currency"] ?? "GBP";
```

## Reading the Cookie object

When we need the name and value together, use `get()`:

```php
$cookie = $cookies->get("currency");

if($cookie) {
	echo $cookie->getName() . " = " . $cookie->getValue();
}
```

`get()` returns `null` when the cookie does not exist.

## Iterating over cookies

`CookieHandler` is iterable. The key is the cookie name, and the value is the cookie value:

```php
foreach($cookies as $name => $value) {
	echo "$name = $value\n";
}
```

The handler is also countable:

```php
echo "There are " . count($cookies) . " cookies in this request.";
```

## Exporting as an array

Use `asArray()` when another API needs plain cookie data:

```php
$cookieArray = $cookies->asArray();
```

The returned array has the same basic shape as `$_COOKIE`: names as keys, values as strings.

---

Next, see [[Setting and deleting cookies]] for the methods that send `Set-Cookie` headers.


Reading cookies tells us what the browser sent with the current request. Setting and deleting cookies tells the browser what it should store for future requests.

In PHP, that happens through HTTP headers. `CookieHandler` calls PHP's `setcookie()` function for us, but the same rule still applies: headers must be sent before the response body starts.

## Setting a cookie

Use `set()` with a name, value, and optional expiry:

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);

$cookies->set(
	"seenWelcome",
	"yes",
	new DateTime("+30 days"),
);
```

After this call, two things have happened:

- the handler contains a `Cookie` object for `seenWelcome`
- PHP has been asked to send a `Set-Cookie` header to the browser

## Expiry

The third argument accepts any `DateTimeInterface`:

```php
$cookies->set("promo", "spring", new DateTime("2026-05-01 00:00:00"));
```

For persistent cookies, always pass an explicit future expiry date.

If the expiry argument is omitted, the current implementation sends the current timestamp to `setcookie()`. That is usually not what we want for a long-lived preference cookie, so examples in this guide pass the expiry explicitly.

## Domain, secure, and HTTP-only flags

`set()` also accepts a domain, secure flag, and HTTP-only flag:

```php
$cookies->set(
	"rememberDevice",
	"1",
	new DateTime("+90 days"),
	domain: "example.com",
	secure: true,
	httponly: true,
);
```

The cookie path is always sent as `/`.

`secure: true` tells the browser to send the cookie only over HTTPS. `httponly: true` tells the browser not to expose the cookie to JavaScript through `document.cookie`.

> [!TIP]
> For authentication or other sensitive server-side state, store the real data in a session or database and use the cookie only as an identifier. Cookies are sent by the browser and should not be treated as private storage.

## Why array assignment is blocked

This works for reading:

```php
echo $cookies["theme"];
```

But this does not work for writing:

```php
$cookies["theme"] = "dark";
```

Array assignment throws `CookieSetException`. Setting a cookie needs more information than a value alone, such as expiry and security flags, so the library requires us to call `set()` explicitly.

## Deleting one cookie

Use `delete()` when the browser should forget a cookie:

```php
$cookies->delete("theme");
```

The cookie is removed from the handler immediately. The browser receives an expired cookie with the same name and the path `/`.

Array unset uses the same behaviour:

```php
unset($cookies["theme"]);
```

## Clearing several cookies

Use `clear()` with one or more names:

```php
$cookies->clear("theme", "currency");
```

Each named cookie is set to an empty value with an expiry in the past, then removed from the handler.

## Clearing every tracked cookie

Call `clear()` without arguments:

```php
$cookies->clear();
```

This clears every cookie currently stored in the handler.

> [!IMPORTANT]
> Browsers match cookies by name, domain, and path. This library deletes cookies using the path `/`. If a cookie was created by other code with a different path or domain, that other code may need to delete it with the same attributes.

---

Next, see [[Cookie objects and validation]] to understand the immutable value objects stored by the handler.


`Cookie` is a small immutable value object. It stores a cookie name and value, and refuses names or values that contain characters which are not valid for HTTP cookies.

## Creating a Cookie object

```php
use GT\Cookie\Cookie;

$cookie = new Cookie("currency", "GBP");
```

The value defaults to an empty string:

```php
$empty = new Cookie("seenWelcome");
```

## Reading the name and value

```php
echo $cookie->getName();
echo $cookie->getValue();
```

The object can also be cast to a string, which returns the value:

```php
echo "Selected currency: " . $cookie;
```

## Immutability

`Cookie` objects do not expose setters. To change the value, use `withValue()`:

```php
$original = new Cookie("currency", "GBP");
$updated = $original->withValue("EUR");

echo $original->getValue(); // GBP
echo $updated->getValue(); // EUR
```

`withValue()` returns a clone, so the original object is unchanged.

## Validation

Cookie names and values are restricted by the characters that are valid in HTTP cookie headers. The library performs this validation when a `Cookie` is constructed and when `withValue()` is called.

Invalid data throws `InvalidCharactersException`:

```php
use GT\Cookie\Cookie;
use GT\Cookie\InvalidCharactersException;

try {
	$cookie = new Cookie("bad,name", "value");
}
catch(InvalidCharactersException) {
	echo "The cookie name or value contains characters that cannot be used.";
}
```

The exact character sets are exposed by `Validity`.

## Validity helper

`Validity` can be used directly when we want to validate before constructing a `Cookie`:

```php
use GT\Cookie\Validity;

if(!Validity::isValidName($name)) {
	throw new InvalidArgumentException("Invalid cookie name");
}

if(!Validity::isValidValue($value)) {
	throw new InvalidArgumentException("Invalid cookie value");
}
```

The helper also exposes the allowed characters as arrays:

```php
$nameCharacters = Validity::getValidNameCharacters();
$valueCharacters = Validity::getValidValueCharacters();
```

Name characters are alphanumeric characters plus the allowed cookie-name punctuation. Value characters are alphanumeric characters plus the allowed cookie-value punctuation and a space.

## Exceptions

All package-specific exceptions extend `CookieException`:

- `InvalidCharactersException` is thrown when a cookie name or value is invalid.
- `CookieSetException` is thrown when code tries to set a cookie through array assignment.

That means application code can catch the specific exception, or catch `CookieException` for any error raised by this package.

---

Next, see [[WebEngine usage]] for how this package fits into a PHP.GT application.


## Why WebEngine avoids superglobals

In plain PHP, it is common to read cookies directly from `$_COOKIE`. That works, but it means any code in the project can read from - and write to - global request state at any time.

WebEngine protects superglobals by default so request data is accessed through explicit objects instead. This keeps page logic easier to test, because a function can receive the objects it needs rather than reaching into global state.

> [!NOTE]
> WebEngine also uses [PHP.GT/Input](https://www.php.gt/input) for query strings, form submissions, uploaded files, and request bodies. Cookie data is separate because browser cookies have their own request and response behaviour.

## Using CookieHandler in application code

The useful pattern is to construct a `CookieHandler` near the edge of the application, then pass it to the code that needs cookies:

```php
use GT\Cookie\CookieHandler;

function showIntro(CookieHandler $cookies):void {
	if($cookies->contains("dismissedIntro")) {
		return;
	}

	// Render the introductory message.
}
```

The same idea applies to actions that set cookies:

```php
use GT\Cookie\CookieHandler;

function dismissIntro(CookieHandler $cookies):void {
	$cookies->set(
		"dismissedIntro",
		"1",
		new DateTime("+1 year"),
		secure: true,
		httponly: true,
	);
}
```

This keeps the dependency visible in the function signature. In a WebEngine project, that is the same style used by other PHP.GT components: page logic should depend on explicit objects rather than superglobals.

> [!NOTE]
> The current WebEngine lifecycle also uses the incoming cookie array when initialising sessions, because PHP's session system is identified by a browser cookie when cookie-based sessions are enabled.

## Sessions and cookies

Cookies are often used to identify a session, but they should not usually contain the session data itself.

For example, a browser may store a session ID cookie. The server uses that ID to load the actual session data from server-side storage. That is different from storing a user's private data directly in the cookie value.

When data belongs on the server, use PHP.GT/Session or another server-side store. When data is a small browser preference, `CookieHandler` can be enough on its own.

## Security defaults in application code

When setting cookies from WebEngine page logic, prefer explicit security flags:

```php
$cookies->set(
	"colourScheme",
	"dark",
	new DateTime("+6 months"),
	secure: true,
	httponly: true,
);
```

Use `httponly: false` only when JavaScript really does need to read the cookie. Use `secure: true` when the site is served over HTTPS, which should be the normal production setup.

---

Next, see the [[API reference]] for the complete public API of this package.


This page is a compact reference for the public API of the library.

For walkthroughs and examples, use the earlier pages in the guide.

## CookieHandler

`CookieHandler` represents the collection of cookies for a request and response.

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);
```

### Constructor

- `__construct(array $existingCookies = [])`

The array should be shaped like `array<string, string>`.

### Reading methods

- `contains(string $name): bool`
- `get(string $name): ?Cookie`
- `asArray(): array`
- `count(): int`

`asArray()` returns `array<string, string>`.

### Writing methods

- `set(string $name, string $value, ?DateTimeInterface $expires = null, string $domain = "", bool $secure = false, bool $httponly = false): void`
- `delete(string $name): void`
- `clear(string ...$nameList): void`

`set()` always sends the path `/` to PHP's `setcookie()` function.

`delete()` expires the named cookie and removes it from the handler.

`clear()` with names clears only those cookies. `clear()` without names clears every cookie currently tracked by the handler.

### ArrayAccess

- `isset($cookies[$name])` checks whether the cookie exists.
- `$cookies[$name]` returns the cookie value as `?string`.
- `unset($cookies[$name])` deletes the cookie.
- `$cookies[$name] = $value` throws `CookieSetException`.

Array assignment is not supported because setting a browser cookie needs expiry and security options.

### Iterator

`CookieHandler` can be used in a `foreach` loop:

```php
foreach($cookies as $name => $value) {
	echo "$name: $value";
}
```

The key is the cookie name. The value is the cookie value.

## Cookie

`Cookie` is an immutable value object.

### Constructor

- `__construct(string $name, string $value = "")`

### Methods

- `__toString(): string`
- `getName(): string`
- `getValue(): string`
- `withValue(string $value): self`

`withValue()` returns a cloned `Cookie` with the new value.

## Validity

`Validity` exposes the character validation used by `Cookie`.

- `Validity::getValidNameCharacters(): array`
- `Validity::getValidValueCharacters(): array`
- `Validity::isValidName(string $name): bool`
- `Validity::isValidValue(string $value): bool`

## Exceptions

- `CookieException`
- `CookieSetException`
- `InvalidCharactersException`

`CookieSetException` and `InvalidCharactersException` both extend `CookieException`.

## Namespace

New code should use the `GT\Cookie` namespace:

```php
use GT\Cookie\CookieHandler;
```

The package also keeps a Composer autoload mapping for the legacy `Gt\Cookie` prefix so older applications can continue to load the same classes.


These examples show the library on its own. In a larger application, the same operations usually live inside controllers, page logic functions, or small services.

## Remember a preference

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);

if($_SERVER["REQUEST_METHOD"] === "POST") {
	$scheme = $_POST["scheme"] ?? "light";

	$cookies->set(
		"colourScheme",
		$scheme,
		new DateTime("+6 months"),
		secure: true,
		httponly: true,
	);
}

$currentScheme = $cookies["colourScheme"] ?? "light";
```

The preference is available immediately from the handler after `set()` is called, and it will be sent back by the browser on later requests if the browser accepts the cookie.

## Dismiss a message

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);

if(isset($_POST["dismiss-intro"])) {
	$cookies->set(
		"dismissedIntro",
		"1",
		new DateTime("+1 year"),
		secure: true,
		httponly: true,
	);
}

if(!$cookies->contains("dismissedIntro")) {
	echo "<p>Welcome to the application.</p>";
}
```

This is a good use for a cookie because the value is small and does not need to be private.

## Clear preference cookies

```php
use GT\Cookie\CookieHandler;

$cookies = new CookieHandler($_COOKIE);

$cookies->clear(
	"colourScheme",
	"dismissedIntro",
	"currency",
);
```

Use this for "reset preferences" features, where a small known group of cookies should be removed together.

## Pass cookies into a function

```php
use GT\Cookie\CookieHandler;

function getCurrency(CookieHandler $cookies):string {
	return $cookies["currency"] ?? "GBP";
}

function rememberCurrency(CookieHandler $cookies, string $currency):void {
	$cookies->set(
		"currency",
		$currency,
		new DateTime("+1 year"),
		secure: true,
		httponly: true,
	);
}
```

Passing the handler in makes the dependency clear. The function can be tested with a simple in-memory handler:

```php
$cookies = new CookieHandler([
	"currency" => "EUR",
]);

assert(getCurrency($cookies) === "EUR");
```

## Use Cookie objects directly

```php
use GT\Cookie\Cookie;

$cookie = new Cookie("currency", "GBP");
$updated = $cookie->withValue("EUR");

echo $cookie->getValue(); // GBP
echo $updated->getValue(); // EUR
```

This is useful when a function should work with one cookie value without needing the whole handler.

---

For the complete method list, see the [[API reference]].




---

# Documentation: Cron

`phpgt/cron` lets us schedule PHP application tasks using familiar crontab syntax, then run the due jobs from PHP itself.

That means we can keep scheduled work close to the project instead of scattering it across system crontab entries, custom shell scripts, and framework-specific glue. A job can be:

- a shell command
- a static PHP function call
- a `go()` function inside a file in the project's `cron/` directory

> [!NOTE]
> In WebEngine development, this library is already included. WebEngine's `gt run` command starts the cron runner alongside the local web server and build watcher, and `gt cron` can be used when we only want the scheduler.

## What this library covers

- Parsing standard five-field crontab expressions.
- Ignoring comments and blank lines in `crontab` files.
- Running due jobs once or continuing to watch for future jobs.
- Calling static PHP methods directly from the crontab.
- Resolving short script names from the local `cron/` directory.
- Running `go()` cron scripts with query-string input and optional dependency injection.
- Extending the schedule language through custom `ExpressionFactory` implementations.

## A small example

`crontab`:

```text
# Run a direct shell command every hour.
0 * * * * printf 'Hourly report built\n'

# Run a short script alias from cron/hello.php every minute.
* * * * * hello

# Run a static method every weekday evening.
0 18 * * MON-FRI App\Task\Digest::send("team@example.com")
```

Run the scheduler from the project root:

```bash
vendor/bin/cron --now
```

If the jobs above are due, the runner executes them immediately. To keep the process alive and wait for future jobs, use `--watch`.

*****

Start with [[Quick start guide]] to build a working project from scratch.


In this guide we will build a tiny project with one cron script, one `crontab` file, and one command to run it.

> [!TIP]
> In WebEngine projects, `phpgt/cron` is already installed and `gt run` will start the scheduler for local development. This guide is for getting the project running outside of WebEngine, or just to understand what's going on under the bonnet.

## 1. Install the package

```bash
composer require phpgt/cron
```

This gives us the `vendor/bin/cron` executable and the PHP classes behind it.

## 2. Create a `crontab` file

In the project root, create a file called `crontab`:

```text
* * * * * hello
```

This line means "run `hello` every minute".

## 3. Create the matching script

Now create `cron/hello.php`:

```php
<?php
echo "Hello from cron at ", date("Y-m-d H:i:s"), PHP_EOL;
```

The runner looks in the local `cron/` directory when it sees a simple script name such as `hello`.

Project structure so far:

```text
.
├── cron
│   └── hello.php
├── composer.json
└── crontab
```

## 4. Run jobs that are due now

From the project root:

```bash
vendor/bin/cron --now
```

Because the job runs every minute, it will run immediately.

The CLI itself prints scheduler status messages. By default it does not stream the child script's own stdout or stderr, so real jobs usually write to a file, send an email, update a database row, or perform some other visible piece of work.

## 5. Keep the runner alive

If we want the process to wait for the next due time automatically:

```bash
vendor/bin/cron --watch
```

The runner prints status messages such as how many jobs just ran and when the next job is due.

## 6. Add another type of job

Cron jobs are not limited to files. For example, we can also call a static PHP method:

```text
0 9 * * MON-FRI App\Task\Digest::send("team@example.com")
```

Or run a full shell command exactly as written:

```text
30 2 * * * php bin/nightly-maintenance.php
```

Those two styles are explained in more detail in [[Static functions and shell commands]].

*****

Next, move on to [[Crontab syntax]] so we can read and write schedules confidently.


This library reads a standard five-field crontab schedule at the start of each line:

```text
* * * * * command
| | | | |
| | | | +-- day of week
| | | +---- month
| | +------ day of month
| +-------- hour
+---------- minute
```

The command starts after the fifth field.

## Basic examples

```text
* * * * * hello
0 * * * * printf 'Top of the hour\n'
30 9 * * 1-5 App\Task\Digest::send
0 0 1 * * php bin/monthly-report.php
```

## Comments and blank lines

Blank lines are ignored.

Lines beginning with `#` are also ignored:

```text
# This is a comment.
*/10 * * * * hello
```

## Lists, ranges, and steps

The field parser supports the usual cron building blocks:

- `*` for "any value"
- `?` for "any value"
- `1,3,5` for a list
- `9-17` for a range
- `*/15` for a step
- `1-10/2` for a stepped range

Examples:

```text
*/15 * * * * example("every 15 minutes")
0 9-17 * * 1-5 example("every hour from 9 through 17, Monday through Friday")
0 8,12,18 * * * example("hour 8, 12, and 18")
```

## Month and weekday names

Month and weekday fields may use short English names:

```text
0 22 * JAN MON-FRI hello
```

Supported month names:

- `JAN`
- `FEB`
- `MAR`
- `APR`
- `MAY`
- `JUN`
- `JUL`
- `AUG`
- `SEP`
- `OCT`
- `NOV`
- `DEC`

Supported weekday names:

- `MON`
- `TUE`
- `WED`
- `THU`
- `FRI`
- `SAT`
- `SUN`

The numeric weekday values `0` and `7` both mean Sunday.

## Nicknames

The library also accepts these nickname expressions:

- `@yearly`
- `@annually`
- `@monthly`
- `@weekly`
- `@daily`
- `@hourly`

Example:

```text
@daily App\Task\Cleanup::run
```

## Day-of-month and day-of-week behaviour

Cron has one important rule that often surprises people: when both the day-of-month and day-of-week fields are restricted, they use **OR** semantics.

For example:

```text
0 12 13 * FRI hello
```

This runs at noon on:

- every 13th day of the month
- every Friday

It does not require both conditions to match at the same time.

## Second-precision extension

This library adds one non-standard extension: the first field may use an `s` suffix to mean seconds within the matching minute.

```text
*/10s * * * * hello
```

That expression runs every 10 seconds.

This is useful for local development, short-running workers, or projects where minute precision is not enough.

## Validating a file

To check syntax without running anything:

```bash
vendor/bin/cron --validate
```

If the file is valid, the command prints `Syntax OK` with the resolved file path.

*****

Now that the schedule format is clear, continue with [[Running the runner]].


In WebEngine applications, the cron runner automatically starts with `gt run`, and can be executed manually with `gt cron`.

In standalone applications, the simplest way to use this library is through the bundled CLI command:

```bash
vendor/bin/cron
```

Run it from the project root so it can find the local `crontab` file and `cron/` directory.

## Default behaviour

With no flags, the runner:

- reads `./crontab`
- runs any jobs that are due right now
- prints the current local time
- prints the next due time
- exits

If there is no `crontab` file, it reports that and exits without running jobs.

## `--watch`

Use `--watch` to keep the process alive:

```bash
vendor/bin/cron --watch
```

In watch mode, the runner sleeps until the next due job, runs it, prints an update, and continues.

This is the usual choice during development if we want the scheduler to stay active in the background.

## `--now`

Use `--now` when we want to run every job immediately once before normal scheduling begins:

```bash
vendor/bin/cron --now
```

This is useful for checking that the commands themselves work, especially in development.

It can also be combined with watch mode:

```bash
vendor/bin/cron --now --watch
```

`--now` can also receive one job name to run only that matching job:

```bash
vendor/bin/cron --now load-wikis
```

The name is the shortened command name shown in runner output. For example:

- `load-wikis` matches `load-wikis`, `load-wikis.php`, or `cron/load-wikis.php`.
- `Digest::send` matches `App\Task\Digest::send(...)`.

If no job matches, the command exits with an error instead of running anything.

## `--validate`

To check the file without running jobs:

```bash
vendor/bin/cron --validate
```

This is helpful in CI, deployment scripts, or just before committing a new schedule.

## `--file`

To use a file other than `./crontab`:

```bash
vendor/bin/cron --file crontab.staging
```

The file is resolved relative to the current working directory.

## Reading the output

When jobs run, the CLI prints summaries such as:

- the current local time
- how many jobs just ran
- a shortened display name for each job
- the next scheduled run time
- the next command due

If local time is different from UTC, the current time and next run time include UTC in brackets:

```text
Current time: 16:49:52 (15:49:52 UTC)
Just ran 0 jobs
Next job at: 17:00:00 (16:00:00 UTC) [build-index]
```

The command due next is shown in square brackets after the time.

In watch mode it also prints `Waiting...` after each cycle.

## Child command output

The CLI status messages described above are separate from the command's own stdout and stderr.

By default, the bundled runner discards child process output. This keeps the scheduler output tidy, but it also means `echo` inside a cron script is not usually the right way to observe success.

If we are embedding the library in PHP ourselves, we can choose a different `ScriptOutputMode` through `JobRepository`:

- `ScriptOutputMode::DISCARD`
- `ScriptOutputMode::INHERIT`
- `ScriptOutputMode::CAPTURE`

## Using the runner from PHP

The CLI is convenient, but the library can also be used directly:

```php
use GT\Cron\RunnerFactory;

$runner = (new RunnerFactory())->createForProject(__DIR__);
$runner->run();
```

To ignore the schedule and run all jobs immediately:

```php
$runner->runAll();
```

To run only selected jobs immediately, pass a matcher that receives the original crontab command string:

```php
$runner->runMatching(
	fn(string $command):bool => str_contains($command, "load-wikis")
);
```

If we need more control, we can set a callback that receives progress data after each cycle:

```php
$runner->setRunCallback(
	function(
		int $jobsRan,
		?DateTime $nextRun,
		bool $continue,
		array $runCommandList,
		?string $nextCommand,
	):void {
		// Log or display status here.
	}
);
```

*****

Move on to [[Static functions and shell commands]] to see how the command part of each crontab line is interpreted.


After the schedule fields, each crontab line contains one command string. This library can interpret that string in a few different ways.

The simplest two are:

- run it as a shell command
- treat it as a PHP callable

## Shell commands

Any command that is not recognised as a PHP callable or special cron script is passed to the process runner.

```text
0 2 * * * php bin/nightly-maintenance.php
*/5 * * * * printf 'Heartbeat\n'
```

The command is executed through `proc_open()`.

If the process exits with a non-zero status, the runner treats that as a failure.

## Static function calls

If the command looks like a callable, the library runs it directly in PHP rather than starting a separate process.

```text
0 9 * * 1-5 App\Task\Digest::send
30 17 * * * App\Task\Cleanup::archive("weekly", 50)
```

This is a good fit when:

- the code already lives in your PHP application
- the task is easier to test as a normal method
- we want Composer autoloading rather than a standalone script entry point

## Callable resolution

The callable name is taken from everything before the first `(` character.

That means all of these are valid shapes:

```text
App\Task\Digest::send
\App\Task\Digest::send
App\Task\Cleanup::archive("weekly", 50)
```

If the callable does not exist, the runner raises a function execution error for that line.

## Arguments

Function arguments are parsed from the text inside the brackets using CSV-style rules:

```text
App\Task\Cleanup::archive("weekly", 50)
```

Be aware of two details:

- values are read as strings from the crontab line
- double quotes are the clearest way to include spaces or commas

In practice, PHP will usually coerce those strings into scalar parameter types when the method signature expects `int`, `float`, or `bool`, but it is best to keep the arguments simple.

## When to choose which style

Prefer a shell command when:

- the task already exists as a standalone script
- the process should be isolated from the current PHP process
- the command naturally belongs to another executable

Prefer a static method when:

- the task is application code
- we want to use Composer autoloading directly
- we do not need a separate process boundary

*****

If the task belongs in the project's `cron/` directory, continue with [[Cron directory scripts]] and [[Go function scripts]].


The runner can resolve short script names from a local `cron/` directory.

This lets us write:

```text
* * * * * hello
```

Instead of:

```text
* * * * * php cron/hello.php
```

## How alias resolution works

For ordinary script aliases, the runner looks for a file directly inside the project's `cron/` directory.

These two crontab lines both resolve to `cron/hello.php`:

```text
* * * * * hello
* * * * * hello.php
```

Using the current PHP binary automatically.

## Passing shell arguments through

Any text after the script name is preserved and passed through:

```text
* * * * * nightly-report "sales team" 2026-03
```

If `cron/nightly-report.php` exists, that becomes equivalent to:

```text
php cron/nightly-report.php "sales team" 2026-03
```

## A small example

`crontab`:

```text
*/15 * * * * report "internal"
```

`cron/report.php`:

```php
<?php
[$script, $audience] = $argv;
echo "Building report for $audience", PHP_EOL;
```

This style works well when we want a self-contained PHP script that still feels local to the project.

## One important limitation

Ordinary script aliases only resolve files that are direct children of `cron/`.

For example, this works:

```text
* * * * * hello
```

But this does not use ordinary script alias resolution:

```text
* * * * * reports/daily
```

If we need nested directories, query-string input, or dependency injection, use a `go()` script instead. That workflow is covered in [[Go function scripts]].

## When the file is not found

If the alias does not match a local `cron/*.php` file, the runner leaves the command unchanged. That means:

- a real shell command can still run normally
- a typo in an alias will not silently correct itself

*****

For the more integrated cron script style, continue with [[Go function scripts]].


`go()` scripts are a more application-friendly style of cron task.

Instead of launching a standalone script process and reading `argv`, we place a PHP file in `cron/` that defines a `go()` function:

```php
<?php
use GT\Input\Input;

function go(Input $input):void {
	file_put_contents(
		"var/cron.log",
		"Mode: " . $input->getString("mode") . PHP_EOL,
		FILE_APPEND
	);
}
```

The runner loads that function and invokes it directly.

## Why use `go()` scripts?

This style is useful when we want:

- a tidy task entry point in `cron/`
- request-like named input instead of shell arguments
- dependency injection for services
- query-string input without shell quoting

## Referencing a `go()` script

If `cron/cache.php` contains `function go(...)`, all of these command forms are accepted:

```text
* * * * * cache?type=db&mode=daily
* * * * * /cache?type=db&mode=daily
* * * * * cache.php?type=db&mode=daily
* * * * * cron/cache?type=db&mode=daily
* * * * * /cron/cache?type=db&mode=daily
```

The part after `?` is parsed as a query string.

## Reading input

Query-string values are made available through an `Input` object:

```php
<?php
use GT\Input\Input;

function go(Input $input):void {
	$type = $input->getString("type");
	$mode = $input->getString("mode");
}
```

This keeps the task code readable when there are several named options.

## Dependency injection

`go()` functions may also receive services as parameters when they can be resolved from the service container.

Example:

```php
<?php
use GT\Input\Input;
use App\Service\Recorder;

function go(Input $input, Recorder $recorder):void {
	$recorder->write($input->getString("type"));
}
```

The runner creates a container, puts the `Input` object into it, and then uses the service loaders that are available for the project.

## How project services are found

When configuration is available, the runner reads:

- `app.namespace`
- `app.class_dir`
- `app.service_loader`

From there it can:

- autoload project classes from the configured class directory
- register WebEngine's default service loader when it is installed
- register the project's own service loader class

> [!NOTE]
> In WebEngine projects this usually means `go()` scripts can use the same service-loading conventions as page logic, which makes cron tasks feel like part of the application rather than a separate subsystem.

## Nested files

Unlike ordinary script aliases, `go()` scripts may live in subdirectories under `cron/`.

For example, this may point at `cron/report/daily.php`:

```text
0 6 * * * report/daily?audience=internal
```

## One important limitation

`go()` script commands do not accept shell-style trailing arguments after the script name. The special handling is only used when the command is just the script reference, optionally followed by a query string.

Use query-string parameters when the task needs named input.

## Choosing between `go()` and ordinary scripts

Choose an ordinary `cron/*.php` script when:

- `argv` is enough
- we want a separate process
- the task is already written as a standalone script

Choose a `go()` script when:

- we are in a WebEngine context
- we want named input through `Input`
- we want service injection
- we want to organise tasks into nested directories

*****

If the built-in cron syntax is not enough, the next page shows how to extend it with [[Custom expression factories]].


The library uses `ExpressionFactory` to turn the schedule part of each crontab line into an `Expression` object.

Most projects will use the built-in `CronExpression`, but we can replace the factory when we need project-specific shorthand.

A custom expression factory is handy when we want to support things such as:

- extra nickname tokens
- application-specific schedule words
- test-only expressions
- migration paths from an older internal scheduler

## Basic shape

`ExpressionFactory` only needs one method:

```php
use GT\Cron\Expression;
use GT\Cron\ExpressionFactory;

class MyExpressionFactory extends ExpressionFactory {
	public function create(string $expression):Expression {
		// Return a custom Expression here.
	}
}
```

## Example: `@start` schedule

The repository includes an example of handling `@start` as "due immediately":

```php
use DateTime;
use GT\Cron\CronExpression;
use GT\Cron\Expression;
use GT\Cron\ExpressionFactory;

$customExpressionFactory = new class extends ExpressionFactory {
	public function create(string $expression):Expression {
		if($expression === "@start") {
			return new class implements Expression {
				public function isDue(DateTime $now):bool {
					return true;
				}

				public function getNextRunDate(?DateTime $now = null):DateTime {
					return clone ($now ?? new DateTime());
				}
			};
		}

		return new CronExpression($expression);
	}
};
```

Then pass that factory into the parser:

```php
use GT\Cron\CrontabParser;

$parser = new CrontabParser($customExpressionFactory);
```

Now a crontab can contain:

```text
@start hello
30 * * * * hourly-report
```

The above example will execute `hello` at the start of the execution, once. Then it will execute hourly-report at 30 minutes past every hour.

## Keep the contract simple

An `Expression` only needs to answer two questions:

- is this job due now?
- when is the next run date?

That small contract keeps custom schedules easy to reason about.

## Prefer clarity over cleverness

If a schedule rule is specific to your project, document it near the `crontab` file or deployment docs as well. Hidden shorthand tends to confuse the next person who reads the schedule.

*****

To see the built-in examples from this repository, continue with [[Examples]].


The `example/` directory is the quickest way to see the library working without building a full project first.

Run an example from the repository root:

```bash
php example/01-run-due-jobs.php
```

Each script embeds its own `crontab` string so the schedule and the code stay together.

## `01-run-due-jobs.php`

This example shows the smallest useful flow:

- create a `Queue`
- parse a crontab string into it
- run only the jobs due at a chosen time

It uses `ScriptOutputMode::INHERIT` so the command output is printed directly.

## `02-next-job.php`

This example focuses on scheduling rather than execution.

It demonstrates:

- running the jobs due now
- asking the queue for the next run date
- asking the queue for the next command due

This is a good page to read after [[Running the runner]] if you want the underlying API shape.

## `03-nickname-expressions.php`

This example shows that nickname schedules such as `@hourly` and `@daily` are accepted as the first token on a line.

It is a small, concrete demonstration of the nickname support described in [[Crontab syntax]].

## `04-custom-expression-factory.php`

This example injects a custom `ExpressionFactory` that understands an extra `@start` token.

Read this alongside [[Custom expression factories]] if you want to extend the scheduler for your own project.




---

# Documentation: Csrf

This library handles [CSRF protection](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)) automatically for you, including generating tokens, injecting them into all forms in the page and then verifying that a valid token is present whenever a POST request is received.

This repository provides the moving parts for that flow:

- `TokenStore` generates, stores, verifies and spends tokens.
- `HTMLDocumentProtector` injects tokens into HTML forms and exposes them through a `<meta>` tag for client-side retrieval.
- Exception types tell us whether the token was missing, invalid, or already used.

The package is designed to be used standalone in any PHP project.

> [!NOTE]
> When using PHP.GT/WebEngine, this library's functionality is automated wherever a `<form method="post">` is used - so there's nothing you need to manually set up or check/validate in WebEngine applications.

## What this library does

- Generates random token strings.
- Stores tokens in memory or in a session-backed store.
- Injects hidden `<input>` fields into `POST` forms.
- Adds or updates a `<meta name="csrf-token">` tag in the page `<head>`.
- Verifies submitted tokens and marks them as spent after use.
- Allows custom token store implementations.

## A minimal example

```php
use GT\Csrf\HTMLDocumentProtector;
use GT\Csrf\SessionTokenStore;
use Gt\Session\SessionArrayWrapper;

session_start();
$session = new SessionArrayWrapper($_SESSION);
$tokenStore = new SessionTokenStore($session);

if($_SERVER["REQUEST_METHOD"] === "POST") {
	$tokenStore->verify($_POST);
}

$html = <<<HTML
<!doctype html>
<html>
	<head>
		<title>Contact</title>
	</head>
	<body>
		<form method="post">
			<label>
				Your message
				<textarea name="message"></textarea>
			</label>
			<button>Send</button>
		</form>
	</body>
</html>
HTML;

$protector = new HTMLDocumentProtector($html, $tokenStore);
$protector->protect();
echo $protector->getHTMLDocument();
```

The same `SessionTokenStore` is used in both directions:

1. Before handling a `POST`, verify the submitted token.
2. Before sending HTML to the browser, inject the next token.

That is the whole flow in this package.

---

Start with [[Quick start]] to build the full request and response cycle from scratch.


In this guide we will set up a small standalone PHP page that uses a session-backed token store, verifies incoming `POST` requests, and injects the next token into the HTML response.

> [!NOTE]
> In WebEngine projects, the same building blocks are used, but request handling, document rendering and session access are usually already available elsewhere in the application. This page shows the package in isolation, using plain PHP techniques.

## 1. Install the package

```bash
composer require phpgt/csrf
```

## 2. Create a token store

For real web requests we need a store that survives between one page render and the next form submission, so `SessionTokenStore` is the usual starting point.

```php
use GT\Csrf\SessionTokenStore;
use GT\Session\SessionArrayWrapper;

session_start();
$session = new SessionArrayWrapper($_SESSION);
$tokenStore = new SessionTokenStore($session);
```

## 3. Verify incoming `POST` data

Before processing the form, verify the submitted token:

```php
use GT\Csrf\Exception\CsrfException;

if($_SERVER["REQUEST_METHOD"] === "POST") {
	try {
		$tokenStore->verify($_POST);
	}
	catch(CsrfException $exception) {
		http_response_code(403);
		exit("Invalid CSRF token");
	}
}
```

If the request body is empty, `verify()` does nothing. If there is `POST` data but no CSRF token, or the token is not valid, an exception is thrown.

## 4. Build the HTML response

```php
$html = <<<'HTML'
<!doctype html>
<html>
	<head>
		<title>Contact form</title>
	</head>
	<body>
		<form method="post">
			<label>
				Email
				<input name="email" type="email" />
			</label>
			<button>Send</button>
		</form>
	</body>
</html>
HTML;
```

## 5. Inject tokens into the page

```php
use GT\Csrf\HTMLDocumentProtector;

$protector = new HTMLDocumentProtector($html, $tokenStore);
$protector->protect();

echo $protector->getHTMLDocument();
```

After `protect()` runs:

- each `POST` form will contain a hidden field named `csrf-token`
- the page `<head>` will contain a `<meta name="csrf-token">` element
- the generated token will be saved into the token store

## 6. Put it together

```php
use GT\Csrf\Exception\CsrfException;
use GT\Csrf\HTMLDocumentProtector;
use GT\Csrf\SessionTokenStore;
use Gt\Session\SessionArrayWrapper;

session_start();
$session = new SessionArrayWrapper($_SESSION);
$tokenStore = new SessionTokenStore($session);

if($_SERVER["REQUEST_METHOD"] === "POST") {
	try {
		$tokenStore->verify($_POST);
	}
	catch(CsrfException $exception) {
		http_response_code(403);
		exit("Invalid CSRF token");
	}
}

$html = <<<'HTML'
<!doctype html>
<html>
	<head>
		<title>Contact form</title>
	</head>
	<body>
		<form method="post">
			<label>
				Email
				<input name="email" type="email" />
			</label>
			<button>Send</button>
		</form>
	</body>
</html>
HTML;

$protector = new HTMLDocumentProtector($html, $tokenStore);
$protector->protect();
echo $protector->getHTMLDocument();
```

## What to expect in the browser

The rendered form will now include a hidden field similar to this:

```html
<input name="csrf-token" value="CSRF_7068702E67742f63737266" type="hidden" />
```

The `<head>` will also contain:

```html
<meta name="csrf-token" content="CSRF_7068702E67742f63737266" />
```

That meta tag is useful when client-side JavaScript needs access to the current token value.

---

Next, [[Token stores]] explains how tokens are generated, retained and spent.


`TokenStore` is the base abstraction in this package. It's responsible for four things:

1. generating token strings
2. saving tokens so they become valid
3. verifying that a submitted token is still valid
4. spending tokens after successful use

## The base `TokenStore`

The abstract class `GT\Csrf\TokenStore` provides:

- `generateNewToken()`
- `setTokenLength(int $length)`
- `getMaxTokens()`
- `verify(array|object $postData)`

It leaves these methods for concrete stores to implement:

- `saveToken(string $token)`
- `verifyToken(string $token)`
- `consumeToken(string $token)`

### Token length

By default, tokens are generated as prefixed ULIDs, so the string begins with `CSRF_` followed by a 32 character ULID.

```php
$token = $tokenStore->generateNewToken();
echo $token; // CSRF_01H...
```

If needed, we can change the length before generating tokens:

```php
$tokenStore->setTokenLength(64);
```

This changes the ULID portion of the token. The `CSRF_` prefix remains in place.

That means the full token string length is always:

`configured token length + strlen("CSRF_")`

### Token limits

`TokenStore` keeps a maximum token count. By default this is `1000`.

```php
$tokenStore = new ArrayTokenStore(50);
echo $tokenStore->getMaxTokens(); // 50
```

When more tokens are saved than the configured limit, the oldest stored token is discarded.

## `ArrayTokenStore`

`ArrayTokenStore` stores tokens in a PHP array held in memory.

```php
use GT\Csrf\ArrayTokenStore;

$tokenStore = new ArrayTokenStore();
```

This is useful for:

- unit tests
- short-lived scripts
- custom applications where another layer persists the object for us

On its own, `ArrayTokenStore` does not survive between HTTP requests, so it is usually not enough for a normal browser form workflow unless we place the object somewhere persistent ourselves.

## `SessionTokenStore`

`SessionTokenStore` reads and writes the token list from a `Gt\Session\SessionContainer`.

```php
use GT\Csrf\SessionTokenStore;
use Gt\Session\SessionArrayWrapper;

session_start();
$session = new SessionArrayWrapper($_SESSION);
$tokenStore = new SessionTokenStore($session);
```

This is the usual choice for web applications because:

- the token generated when rendering a page is still available on the next request
- spent tokens can be tracked between requests
- the same store can be shared across the whole user session

Internally, the token list is saved under the session key `tokenList`.

## How stored token state works

Both built-in stores keep values in the same shape:

- `null` means the token exists and has not yet been used
- an integer timestamp means the token has already been spent

That timestamp is later used by `CsrfTokenSpentException` to report when the token was previously consumed.

## Choosing a store

- Use `SessionTokenStore` for ordinary browser-based forms.
- Use `ArrayTokenStore` for tests or temporary in-memory usage.
- Extend `TokenStore` if your application needs a database, cache or other storage backend.

---

To see how tokens are inserted into HTML documents, read [[Protecting pages]]


`HTMLDocumentProtector` is responsible for taking an HTML document, generating one or more tokens, storing them, and inserting them into the right places in the markup.

## Constructing a protector

The constructor accepts either a string of HTML or an existing `GT\Dom\HTMLDocument`, plus a token store:

```php
use GT\Csrf\HTMLDocumentProtector;

$protector = new HTMLDocumentProtector($html, $tokenStore);
```

Or with an existing document:

```php
use GT\Dom\HTMLDocument;

$document = new HTMLDocument($html);
$protector = new HTMLDocumentProtector($document, $tokenStore);
```

In both cases, `getHTMLDocument()` returns the `HTMLDocument` object after protection has been applied.

## What `protect()` changes

Calling `protect()` does three things:

1. finds `POST` forms in the document
2. prepends a hidden `<input>` containing the token to each matching form
3. creates or updates a `<meta name="csrf-token">` tag in the page `<head>`

```php
$protector->protect();
echo $protector->getHTMLDocument();
```

Only forms whose method is explicitly `post` are modified. Other forms are left alone.

## Hidden input fields

The inserted form field has these attributes:

- `name="csrf-token"`
- `value="<generated token>"`
- `type="hidden"`

The input is inserted before the form's first child.

## The head meta tag

The protector also keeps the token in a head meta tag:

```html
<meta name="csrf-token" content="...">
```

If a matching meta tag already exists, its `content` attribute is replaced.

If the document has no `<head>`, the protector creates one and appends it to the `<html>` element before adding the meta tag.

## One token per page or one token per form

The `protect()` method accepts a token-sharing mode:

```php
$protector->protect(HTMLDocumentProtector::ONE_TOKEN_PER_PAGE);
```

This is the default. One token is shared by all `POST` forms on the page and by the head meta tag.

If needed, we can ask for one token per form:

```php
$protector->protect(HTMLDocumentProtector::ONE_TOKEN_PER_FORM);
```

In that mode:

- each `POST` form gets a different token
- the head meta tag contains all generated tokens joined by commas

This is useful when one page can submit several different forms independently without a full page reload in between.

## Pages with no forms

If the document contains no `POST` forms, `protect()` still generates and saves one token so the meta tag is available:

```php
$protector->protect();
```

That means JavaScript can still read the token from the `<head>` even if the page itself has no form markup.

## Return value of `protect()`

`protect()` returns the last token it generated.

- with `ONE_TOKEN_PER_PAGE`, this is the shared page token
- with `ONE_TOKEN_PER_FORM`, this is the final form token generated during the loop

In most cases it is simpler to work with the document output rather than using the return value directly.

---

Next to see how submitted tokens are checked and spent, continue on to [[Verifying requests]].


Once a token has been inserted into the page, the next step is to verify it when the browser submits the form.

## The `verify()` method

The main entry point is `TokenStore::verify()`:

```php
$tokenStore->verify($_POST);
```

`verify()` expects either:

- an array of submitted values
- an object with an `asArray()` method

That second form exists so the package can work with object-based request input as well as plain PHP arrays.

## What `verify()` checks

When `verify()` receives non-empty request data, it checks for a field named `csrf-token`.

The method then:

1. throws `CsrfTokenMissingException` if the field is not present
2. calls `verifyToken()` on the submitted value
3. calls `consumeToken()` if the token is valid

That final step is important: tokens are single-use. A successful verification spends the token immediately.

## Empty request bodies

If the submitted data is empty, `verify()` returns without throwing an exception:

```php
$tokenStore->verify([]);
```

This allows the same code path to be called safely before deciding whether the request actually contains form input.

## A common verification pattern

```php
use GT\Csrf\Exception\CsrfException;

if($_SERVER["REQUEST_METHOD"] === "POST") {
	try {
		$tokenStore->verify($_POST);
	}
	catch(CsrfException $exception) {
		http_response_code(403);
		exit("Invalid CSRF token");
	}
}
```

This works because all package-specific CSRF exceptions inherit from `CsrfException`.

## Verifying object-based input

If your request input is wrapped in an object, `verify()` will accept that too as long as it provides `asArray()`:

```php
$tokenStore->verify($postObject);
```

The object does not need to implement a formal interface here. The method simply checks whether `asArray()` can be called.

## Repeated submissions

Because a valid token is spent immediately after verification, submitting the same form twice will fail on the second attempt with `CsrfTokenSpentException`.

This matters when:

- a user double-clicks the submit button
- JavaScript retries a request using an old token
- one page submits several background requests using the same token

In those cases, render or fetch a fresh page so the client receives new tokens.

## Reading the token name

The field and meta tag name are defined as:

```php
GT\Csrf\HTMLDocumentProtector::TOKEN_NAME
```

The current value is `csrf-token`.

---

Next, move on to [[Exceptions]] to see what each failure mode means and how to handle it.


This repository uses exceptions to report CSRF verification failures. All package-specific exceptions extend `GT\Csrf\Exception\CsrfException`.

## The exception hierarchy

- `CsrfException`
- `CsrfTokenMissingException`
- `CsrfTokenInvalidException`
- `CsrfTokenSpentException`

That means we can either catch specific cases or catch the base class.

## `CsrfTokenMissingException`

This is thrown when submitted data exists but there is no `csrf-token` field at all.

Typical causes:

- the form was rendered without calling `protect()`
- a client script submitted partial form data and omitted the token
- a request was forged manually

## `CsrfTokenInvalidException`

This is thrown when a token is present in the request, but it is not known to the current token store.

Typical causes:

- the token was never generated by this application instance
- the token has been evicted because the store exceeded its maximum token count
- the request belongs to a different session or environment

## `CsrfTokenSpentException`

This is thrown when the token exists but has already been used.

The exception message includes the earlier use time in ISO 8601 format, because the store records the consumption timestamp when `consumeToken()` is called.

Typical causes:

- the form was submitted twice
- background requests reused an old token
- the browser re-sent stale form data after a previous successful submission

## Catching exceptions

Catch the base exception when all failures should be handled in the same way:

```php
use GT\Csrf\Exception\CsrfException;

try {
	$tokenStore->verify($_POST);
}
catch(CsrfException $exception) {
	http_response_code(403);
	echo $exception->getMessage();
}
```

Catch specific subclasses when you want to distinguish the response:

```php
use GT\Csrf\Exception\CsrfTokenMissingException;
use GT\Csrf\Exception\CsrfTokenSpentException;

try {
	$tokenStore->verify($_POST);
}
catch(CsrfTokenMissingException $exception) {
	http_response_code(400);
}
catch(CsrfTokenSpentException $exception) {
	http_response_code(409);
}
```

The package itself does not decide what HTTP response to send. It only reports the verification result.

---

If tokens should be stored somewhere other than memory or the session, read [[Custom stores]].


The package includes two token stores, but the API is designed so we can implement our own storage backend when needed.

## When a custom store is useful

You might want a custom `TokenStore` when tokens need to live in:

- a database table
- Redis or another cache service
- a framework-specific session abstraction
- a distributed store shared between several application instances

## What must be implemented

Extend `GT\Csrf\TokenStore` and implement these methods:

- `saveToken(string $token): void`
- `verifyToken(string $token): void`
- `consumeToken(string $token): void`

The base class already provides token generation and the high-level `verify()` workflow.

## Example skeleton

```php
use GT\Csrf\Exception\CsrfTokenInvalidException;
use GT\Csrf\Exception\CsrfTokenSpentException;
use GT\Csrf\TokenStore;

class DatabaseTokenStore extends TokenStore {
	public function saveToken(string $token):void {
		// Persist the token as "not yet used".
	}

	public function verifyToken(string $token):void {
		$record = null; // Load from storage.

		if(!$record) {
			throw new CsrfTokenInvalidException($token);
		}

		if($record["used_at"] !== null) {
			throw new CsrfTokenSpentException(
				$token,
				$record["used_at"]
			);
		}
	}

	public function consumeToken(string $token):void {
		// Persist the current timestamp as the use time.
	}
}
```

## Behaviour to preserve

When writing a custom store, it helps to preserve the same behaviour as the built-in stores:

- a saved token should be valid exactly once
- a consumed token should produce `CsrfTokenSpentException`
- a missing token should produce `CsrfTokenInvalidException`
- old tokens should be removable when a maximum count is exceeded

If you need a retention policy, `getMaxTokens()` exposes the configured limit from the base class.

## Using the custom store

Once implemented, the custom store can be used anywhere a normal token store is expected:

```php
$tokenStore = new DatabaseTokenStore();
$protector = new HTMLDocumentProtector($html, $tokenStore);
```

That includes both page protection and request verification.

---

The [[API reference]] is a compact summary of classes, constants and methods.


This page summarises the public API in `phpgt/csrf`.

## Namespaces

The package now uses the `GT\Csrf` namespace prefix.

For backwards compatibility, Composer autoloading in this repository also accepts the legacy `Gt\Csrf` prefix.

## `GT\Csrf\TokenStore`

Abstract base class for token generation and verification flow.

Generated tokens are returned as prefixed ULIDs beginning with `CSRF_`.
The configured token length refers to the ULID portion only, so the full string length is the configured length plus the prefix length.

### Methods

- `__construct(?int $maxTokens = null)`
- `getMaxTokens(): int`
- `setTokenLength(int $newTokenLength): void`
- `generateNewToken(): string`
- `verify(array|object $postData): void`
- `saveToken(string $token): void`
- `consumeToken(string $token): void`
- `verifyToken(string $token): void`

## `GT\Csrf\ArrayTokenStore`

In-memory implementation of `TokenStore`.

### Methods

- inherits the constructor from `TokenStore`
- `saveToken(string $token): void`
- `consumeToken(string $token): void`
- `verifyToken(string $token): void`

## `GT\Csrf\SessionTokenStore`

Session-backed implementation of `TokenStore`.

### Constants

- `SESSION_KEY = "tokenList"`

### Methods

- `__construct(Gt\Session\SessionContainer $session, ?int $maxTokens = null)`
- `saveToken(string $token): void`
- `consumeToken(string $token): void`
- `verifyToken(string $token): void`

## `GT\Csrf\HTMLDocumentProtector`

Injects tokens into HTML documents.

### Constants

- `ONE_TOKEN_PER_PAGE = "PAGE"`
- `ONE_TOKEN_PER_FORM = "FORM"`
- `TOKEN_NAME = "csrf-token"`

### Methods

- `__construct(string|GT\Dom\HTMLDocument $document, TokenStore $tokenStore)`
- `protect(string $tokenSharing = self::ONE_TOKEN_PER_PAGE): string`
- `getHTMLDocument(): GT\Dom\HTMLDocument`

## Exceptions

### `GT\Csrf\Exception\CsrfException`

Base exception for all CSRF verification failures.

### `GT\Csrf\Exception\CsrfTokenMissingException`

Thrown when submitted data contains no CSRF token.

### `GT\Csrf\Exception\CsrfTokenInvalidException`

Thrown when the submitted token does not exist in the store.

### `GT\Csrf\Exception\CsrfTokenSpentException`

Thrown when the submitted token exists but has already been used.

## Dependencies

This package depends on:

- `phpgt/dom` for `GT\Dom\HTMLDocument`
- `phpgt/session` for the built-in session-backed token store




---

# Documentation: CssXPath

Introduction
============

Both CSS selectors and XPath queries help us find elements in a document, but CSS selectors are usually easier to read and write. The challenge is that tools like `DOMXPath` expect XPath strings, not CSS selectors.

`phpgt/CssXPath` bridges that gap by translating selector syntax such as `.menu li.selected > a` into the equivalent XPath query.

What this project is for
========================

Use this repository when we want modern selector-style traversal on top of PHP's DOM tooling.

Typical use cases:

+ Implementing `querySelector`-style helpers.
+ Using CSS selectors in existing `DOMXPath` code.
+ Writing tests against HTML/XML documents with terse selectors.

> [!IMPORTANT]
> php.gt/WebEngine heavily uses the Document Object Model (DOM), and HTMLDocument functions such as `querySelectorAll()` take CSS selectors to easily traverse the document.
>
> All of the functionality within this CssXPath is automatically included within WebEngine via the [PHP.GT/Dom][dom] repository.
> 
> To use CSS selectors within WebEngine, you don't need to require this library yourself - it's included by default, so you should only ever need CssXPath if you're building your own library working with the DOM document.

Quick example
=============

```php
use DOMDocument;
use DOMXPath;
use GT\CssXPath\Translator;

$html = <<<HTML
<nav class="c-menu">
	<ul>
		<li class="selected"><a href="/blog">Blog</a></li>
	</ul>
</nav>
HTML;

$document = new DOMDocument();
$document->loadHTML($html);

$xpath = new DOMXPath($document);
$links = $xpath->query(new Translator("nav.c-menu li.selected>a"));

echo $links->item(0)?->textContent; // Blog
```

What's covered in this guide?
=============================

+ [[Quick start]]
+ [[Using with DOMDocument]]
+ [[Selector syntax]]
+ [[Attribute selectors]]
+ [[Pseudo selectors]]
+ [[HTML mode and XML mode]]
+ [[Prefixes and advanced usage]]

Support
=======

Report bugs and suggest features on the [Github issue tracker](https://github.com/PhpGt/CssXPath/issues).

---

Continue to [[Quick start]].

[dom]: https://php.gt/dom


Quick start
===========

Install with Composer:

```bash
composer require phpgt/cssxpath
```

Here we can translate a selector by constructing `Translator` and casting it to a string:

```php
use Gt\CssXPath\Translator;

$translator = new Translator("form label>input[name=email]");
echo (string)$translator;
// .//form//label/input[@name="email"]
```

The constructor accepts three main arguments:

+ `cssSelector` (required): selector string to translate.
+ `prefix` (optional, default `.//`): XPath prefix used at the start of each selector.
+ `htmlMode` (optional, default `true`): whether element/attribute names are matched in HTML mode.

You can also call `asXPath()` if you prefer an explicit method name:

```php
$xpath = (new Translator(".c-menu li.selected"))->asXPath();
```

---

Next, we'll learn about [[using with DOMDocument]].


Using with DOMDocument
======================

The common workflow is to load markup into `DOMDocument`, create `DOMXPath`, and pass a `Translator` instance into `query()`.

```php
use DOMDocument;
use DOMXPath;
use Gt\CssXPath\Translator;

$document = new DOMDocument();
$document->loadHTMLFile("index.html");

$xpath = new DOMXPath($document);
$result = $xpath->query(new Translator("main article p"));

foreach($result as $p) {
	echo trim($p->textContent) . PHP_EOL;
}
```

Selecting relative to a node
----------------------------

`DOMXPath::query()` supports a context node. Here we can keep one translator and query different branches of the same document:

```php
$allItems = $xpath->query(new Translator("li"));
$itemsInNav = $xpath->query(
	new Translator("li"),
	$document->getElementsByTagName("nav")->item(0)
);
```

Grouped selectors
-----------------

Comma-separated CSS selectors are translated to XPath expressions joined by `|`.

```php
echo new Translator("h1, p");
// .//h1 | .//p
```

This lets us fetch mixed sets of nodes using a single query.

---

Next up, we'll learn the [[selector syntax]].


Selector syntax
===============

This page covers core selector patterns supported by the translator.

Basic selectors
===============

+ Element selector: `p`
+ Universal selector: `*`
+ ID selector: `#hero`
+ Class selector: `.selected`
+ Combined selector: `nav.c-menu.main-selection`

Combinators
===========

+ Descendant: `article p`
+ Child: `form>label`
+ Adjacent sibling: `header + div`
+ General sibling: `header ~ div`

Examples
========

| CSS | XPath |
|---|---|
| `main article p` | `.//main//article//p` |
| `form>label>input` | `.//form/label/input` |
| `.content#content-element` | `.//*[contains(concat(' ',normalize-space(@class),' '),' content ')][@id='content-element']` |
| `main header ~ div.details` | `.//main//header/following-sibling::div[contains(concat(' ',normalize-space(@class),' '),' details ')]` |

Notes
=====

+ Whitespace around `>` / `+` / `~` is optional.
+ Multiple class selectors can be chained (`.a.b.c`).
+ Multiple selectors can be grouped with commas (`h1, p, a.button`).

---

Continue learning about [[attribute selectors]].


Attribute selectors
===================

Attribute selectors are fully supported, including quoted values and operator variants.

Presence and exact match
========================

+ `[required]` checks attribute presence.
+ `[name=email]` exact value match.
+ `[name='email']` and `[name="email"]` are both supported.

Operator support
================

+ `[attr*=value]` contains substring.
+ `[attr~=value]` contains whole word in a space-separated list.
+ `[attr$=value]` ends with.
+ `[attr|=value]` exact value or value followed by hyphen.
+ `[attr^=value]` starts with.

Examples
========

| CSS | XPath |
|---|---|
| `[data-categories*=test]` | `.//*[contains(@data-categories,"test")]` |
| `[data-categories~=example]` | `.//*[contains(concat(" ",@data-categories," "),concat(" ","example"," "))]` |
| `[data-test-thing$=test]` | `.//*[substring(@data-test-thing,string-length(@data-test-thing) - string-length("test") + 1)="test"]` |
| `[class|=en]` | `.//*[@class="en" or starts-with(@class, "en-")]` |
| `[class^=class1]` | `.//*[starts-with(@class, "class1")]` |

Special cases
=============

+ Values containing commas are handled correctly, for example:
  `[data-ga-client='(Test) Message, this has a comma']`.
+ Values containing square brackets are supported, such as:
  `[name='choice[]']`.

---

Continue learning about [[pseudo selectors]].


Pseudo selectors
================

A focused set of pseudo selectors is currently supported.

Boolean attribute pseudo selectors
==================================

These map directly to attribute presence checks:

+ `:checked`
+ `:disabled`
+ `:selected`

Example:

```css
input:checked
```

Structural pseudo selectors
===========================

+ `:first-child`
+ `:nth-child(n)`
+ `:last-child`
+ `:first-of-type`
+ `:nth-of-type(n)`
+ `:last-of-type`

Example:

```css
form label:nth-of-type(2) input
```

Other supported pseudo selectors
================================

+ `:text` maps to `[@type="text"]` (useful for form inputs).
+ `:contains('Example')` maps to a text contains check.

Limitations
===========

Only the pseudo selectors listed above are implemented. If we use an unsupported pseudo selector, it is not translated into an XPath predicate.

---

Work with different document types with [[HTML mode and XML mode]].


HTML mode and XML mode
======================

`Translator` defaults to HTML mode:

```php
new Translator("[data-FOO='bar']");
```

In HTML mode (`htmlMode: true`):

+ Element names are treated case-insensitively.
+ Attribute names are lowered for matching.
+ Attribute values remain case-sensitive.

XML mode
========

When querying XML, pass `htmlMode: false` and usually use `prefix: "//"`.

```php
$translator = new Translator(
	"[data-FOO='bar']",
	prefix: "//",
	htmlMode: false
);
```

In XML mode:

+ Element names are case-sensitive.
+ Attribute names are case-sensitive.
+ Attribute values are case-sensitive.

Important loading note
======================

For XML behaviour, load content as XML (`load`, `loadXML`, or `loadXMLFile`) rather than HTML loaders (`loadHTML`, `loadHTMLFile`), because HTML loaders normalise names.

---

Continue to [[prefixes and advanced usage]].


Prefixes and advanced usage
===========================

Custom XPath prefix
===================

By default each translated selector starts with `.//`. We can customise this by passing `prefix`.

```php
echo new Translator("h1, p", prefix: "descendant-or-self::");
// descendant-or-self::h1 | descendant-or-self::p
```

This is useful when integrating into existing XPath strategies.

Using `asXPath()` vs casting
============================

Both of these are equivalent:

```php
$xpathA = (string)new Translator(".content");
$xpathB = (new Translator(".content"))->asXPath();
```

Use whichever reads better in your codebase.

Combining predicates
====================

Complex selectors can stack class, id, attribute, and pseudo predicates together.

```css
main article .content[data-categories~=test]:nth-child(2)
```

Here we can keep selectors readable while still producing a precise XPath query.

Current scope
=============

This repository is intentionally lightweight and dependency-free. It focuses on a practical subset of CSS selectors commonly used for DOM traversal and `querySelector`-style APIs.

---

Return to [[Home]].




---

# Documentation: Curl

cURL is a tool for transferring data to and from a server, and is widely available on most operating systems. It's most commonly used for making HTTP requests, such as downloading web pages, posting form data, or interacting with APIs.

PHP comes with bindings to **libcurl**, a library created by Daniel Stenberg, which directly calls the underlying C implementation in a very efficient manner.

This library wraps the PHP cURL functions with object oriented counterparts. The purpose is to ease the process of writing unit tests in other software that uses the library, along with normalising the way output is handled.

Output handling
===============

The only change introduced by this library to how the native cURL functions work is output handling. By default, cURL functions will output data they receive directly to `STDOUT`. It's common to use the `CURLOPT_RETURNTRANSFER` option to change this behaviour, but this starts to become complicated when using multiple concurrent `Curl` handles within a `CurlMulti` object.

This library manages the incoming data buffer for you, normalising the method of accessing the response content into two functions:

+ `output():string` - returns the response body as a string.
+ `outputJson():JsonObject` - returns the response body as a pre-parsed JsonObject

A [`JsonObject`](https://www.php.gt/json) provides type safe getter functions on the response, such as `getString()`, `getBool()`, etc. which is useful when working with well-formed JSON data.

```php
$curl = new Curl("https://catfact.ninja/fact");
$curl->exec();
$json = $curl->outputJson();
echo "Here's a cat fact: {$json->getString("fact")}";
echo PHP_EOL;
echo "The fact's length is {$json->getInt("length")} characters.";
echo PHP_EOL;
```

Read more about the JSON library used at https://www.php.gt/json.

HTTP clients and Web Standards
==============================

This library was first conceived when work started on [PHP.Gt/Fetch](https://www.php.gt/fetch), a PHP implementation of the [Fetch web standard](https://fetch.spec.whatwg.org/#fetch-method).

Fetch is an asynchronous HTTP client, and it made perfect sense to utilise the bulletproof CurlMulti capabilities of libcurl, but using native PHP functions was difficult to unit test.

In conclusion, feel free to use this library for your project's HTTP requests, but the intention behind the project is simply to act as the internal data transfer tool within Fetch.

***

If you would like to learn more about this library, continue to [[Basic Curl usage]].

The simplest possible usage of this library is to perform an HTTP GET request and display the response body:

```php
use GT\Curl\Curl;

$curl = new Curl("https://ipapi.co/country_name");
$curl->exec();
echo "Your country is: ";
echo $curl->output(), PHP_EOL;
```

Here's an example of how to upload a file by first downloading an image from a random cat image generator, then uploading it and sending to Postman's echo server:

```php
use GT\Curl\Curl;
use GT\Curl\UploadFile;

require(__DIR__ . "/../vendor/autoload.php");

$tmpFile = "/tmp/cat.jpg";

// Download a photo of a cat from cataas.com, save it to the $tmpFile
$curl = new Curl("https://cataas.com/cat");
file_put_contents($tmpFile, $curl->output());

// Now POST a form containing the cat photo to the Postman echo test server
$upload = new UploadFile($tmpFile);
$curl = new Curl("https://postman-echo.com/post");
$curl->setOpt(CURLOPT_POSTFIELDS, [
	"cat-photo" => $upload
]);
$curl->exec();
echo $curl->output();

// Remove the temporary file before finishing
unlink($tmpFile);
```

***

In the next section we will learn about [[working with JSON]].


Combining JSON with Curl is such a common task for web developers, the [PHP.GT/Json](https://www.php.gt/json) library is bundled by default, which allows you to work with JSON requests and responses in a type-safe way.

Where `Curl::output()` returns a `string` representation of the HTTP response body, `Curl::outputJson()` returns a well-formed `JsonObject` that can be traversed with type safety.

Here's an example that makes a request to the https://catfact.ninja/ API, then echoes the data and it receives as a `string` and an `int`:

```php
use GT\Curl\Curl;

$curl = new Curl("https://catfact.ninja/fact");
$curl->exec();
$json = $curl->outputJson();
echo "Here's a cat fact: " . $json->getString("fact");
echo PHP_EOL;
echo "The fact's length is " . $json->getInt("length") . " characters.";
echo PHP_EOL;
```

To learn more about the different ways you can work with JSON, take a look at https://www.php.gt/json.

***

Next up, learn how to execute multiple [[concurrent curl requests]].


So far we've only executed individual HTTP requests. We create a `Curl` object, execute it, then read the response.

If we want to execute multiple HTTP requests as part of our script, it can be inefficient to run multiple requests one after another. For example, if we have 10 HTTP requests to make that all take 1 second to execute, running them one after another will take 10 seconds to complete. However, if we ran all 10 requests concurrently, our script would only take 1 second to complete, because all HTTP requests can be executed in parallel.

The way to do this is to build each individual `Curl` object as usual, but instead of calling `exec()` on them directly, we add them to a new `CurlMulti` object, and call `exec` on that instead.

The `CurlMulti::exec()` function returns the number of requests still active, so while the returned number is greater than 0, there is still work to do - we should wait a while, then call `exec` again.

Here's an example that makes three individual requests, executes them concurrently within a `CurlMulti` object, waits for them all to complete, then outputs all the responses:

```php
use GT\Curl\Curl;
use GT\Curl\CurlMulti;

$curlCat = new Curl("https://catfact.ninja/fact");
$curlIp = new Curl("https://api.ipify.org/?format=json");
$curlTimeout = new Curl("https://this-domain-name-does-not-exist.example.com/nothing.json");

$multi = new CurlMulti();
$multi->add($curlCat);
$multi->add($curlIp);
$multi->add($curlTimeout);

$stillRunning = 0;
do {
	$multi->exec($stillRunning);
	usleep(100_000);
	echo ".";
}
while($stillRunning > 0);

echo PHP_EOL;
echo "Cat API response: " . $multi->getContent($curlCat) . PHP_EOL;
echo "IP API response: " . $multi->getContent($curlIp) . PHP_EOL;
echo "Timeout API response: " . $multi->getContent($curlTimeout) . PHP_EOL;
```

Streaming responses
-------------------

In the above example, we are running the three requests concurrently and echoing the responses after all the responses have completed. In some situations, it may be beneficial to receive the response as soon as **any** content is received, rather than having to wait for the entire response to complete its download.

For example, when large responses are expected, we can stream the incoming data somewhere to process the information in a memory efficient manner, rather than loading the entire response data into memory.

To do this, we can set a header/write function on the individual Curl objects. This function will be called whenever any bytes are received from the server.

To process each HTTP header as it's received, set the `CURLOPT_HEADERFUNCTION` option. To process the incoming response, whenever any bytes are received, set the `CURLOPT_WRITEFUNCTION` option.

The value of this option is a function or other `callable` that takes the following signature:

```php
function(CurlHandle $ch, string $buffer):int;
```

The first parameter is the native PHP `CurlHandle`. The second parameter is the most important - the incoming data.

The header callback is be called once for each header and only complete header lines are passed on to the callback, ending with a newline character.

The write callback is called as soon as there is data received that needs to be saved. For most transfers, this callback gets called many times and each invoke delivers another chunk of data.

Here's an example that uses the same three APIs, but this time echoes the response headers and body as soon as they are received. The echoes will likely execute out of order, so if this were being used for a real project, the CurlHandle would need to be kept track of to save the responses to the correct locations.

```php

use GT\Curl\Curl;
use GT\Curl\CurlMulti;

$urlArray = [
	"https://catfact.ninja/fact",
	"https://api.ipify.org/?format=json",
	"https://this-domain-name-does-not-exist.example.com/nothing.json",
];

$multi = new CurlMulti();

foreach($urlArray as $url) {
	$curl = new Curl($url);
	$curl->setOpt(CURLOPT_HEADERFUNCTION, function ($ch, string $rawHeader):int {
		echo "HEADER: $rawHeader";
		return strlen($rawHeader);
	});
	$curl->setOpt(CURLOPT_WRITEFUNCTION, function ($ch, string $rawBody):int {
		echo "BODY: $rawBody\n";
		return strlen($rawBody);
	});
	$curl->setOpt(CURLOPT_TIMEOUT, 10);
	$multi->add($curl);
}

$stillRunning = 0;
do {
	$multi->exec($stillRunning);
	usleep(10_000);
	echo ".";
}
while($stillRunning > 0);

echo PHP_EOL;
```

***

The Fetch API
-------------

This library was created to provide a solid foundation for [PHP.Gt/Fetch], which is a more featured library that is implemented to be compatible with web standards. Behind the scenes, Fetch uses this Curl library to manage the HTTP transport, but has a Promise-based interface that is familiar with web developers outside of the PHP community.

For more information, see https://www.php.gt/fetch.

[PHP.Gt/Fetch]: https://www.php.gt/fetch




---

# Documentation: Daemon

A software daemon is a background process that runs continuously on a system, often to perform tasks or provide services without direct user interaction. This repository provides a simple API to create and manage running processes, and allows you to bundle processes into pools to be interacted with as a single unit.

Daemon lets our PHP code start operating system commands, read their output while they run, and group several commands together as one pool.

This is useful when a PHP script needs to supervise another process without waiting for it to finish straight away. For example, we might start a development server, run a build step, or stream the output of several long-running commands into one CLI program.

> [!NOTE]
> This package can be used on its own with Composer, but is included by default in WebEngine projects, where it is normally used in higher-level commands, such as `gt start`, rather than instantiating `GT\Daemon\Process` from page logic.

## Requirements

Install the package with Composer:

```bash
composer require phpgt/daemon
```

The package requires PHP 8.1 or newer and the `pcntl` extension. It also uses PHP's built-in `proc_open` functions, so it needs to run in an environment where process execution is allowed.

## A small example

```php
use GT\Daemon\Process;

$process = new Process(PHP_BINARY, "-r", "echo 'Hello from the child process' . PHP_EOL;");
$process->exec();

while($process->isRunning()) {
	echo $process->getOutput();
	usleep(100_000);
}

echo $process->getOutput();
echo "Exit code: " . $process->getExitCode() . PHP_EOL;
```

The command is passed as separate arguments. In the example above, `PHP_BINARY` is the executable, `-r` is the first argument, and the inline PHP code is the second argument.

---

The [[overview]] page shows how to run one command and read its output.


In this guide we will start one command, read from it while it runs, then check how it ended.

## 1. Create a process

```php
use GT\Daemon\Process;

$process = new Process(
	"/usr/bin/ping",
	"-c",
	"3",
	"github.com",
);
```

The constructor accepts the command as separate arguments. The first argument is the executable. The remaining arguments are passed to that executable.

> [!IMPORTANT]
> Do not pass a whole shell command as one string unless the executable really has that name. For example, use `new Process("echo", "hello")`, not `new Process("echo hello")` wherever possible, so PHP can escape the arguments safely.

If we need shell features such as pipes, redirects or command chaining, run a shell explicitly:

```php
$process = new Process("sh", "-c", "printf 'Hello' | wc -c");
```

## 2. Execute the process

```php
$process->exec();
```

By default, `exec()` starts the process and returns while the child process is still running.

## 3. Read output while it runs

```php
do {
	echo $process->getOutput();
	usleep(100_000);
}
while($process->isRunning())
```

The output pipes are non-blocking, so `getOutput()` returns whatever is currently available. It can return an empty string when the process is still running but has not written anything new.

The last `getOutput()` call after the loop collects any remaining output written just before the process finished.

## 4. Check the exit code

```php
$exitCode = $process->getExitCode();
echo "Process ended with code $exitCode" . PHP_EOL;
```

`getExitCode()` returns `null` while the process is still running. Once it has ended, it returns the command's exit code.

## Reading errors

Standard error is kept separate from standard output:

```php
while($process->isRunning()) {
	echo $process->getOutput();
	fwrite(STDERR, $process->getErrorOutput());
	usleep(100_000);
}
```

This lets us decide whether error output should be shown, logged, filtered or ignored.

---

Continue with [[Process]] to see the options available on a single process.


`Process` represents one running command.

We create it with the command arguments, configure anything that needs to change, then call `exec()` to start it.

```php
use GT\Daemon\Process;

$process = new Process("php", "worker.php", "--queue", "emails");
$process->exec();
```

## Working directory

By default, the process starts in the current working directory of the PHP script. We can change that before calling `exec()`:

```php
$process = new Process("php", "worker.php");
$process->setExecCwd("/path/to/project");
$process->exec();
```

This is useful when a command expects relative file paths.

## Environment variables

The child process receives the current environment, plus any values we set:

```php
$process = new Process("printenv");
$process->setEnv("APP_ENV", "dev");
$process->setEnv("QUEUE", "emails");
$process->exec();
```

If the key already exists in the current environment, the value we set is used for the child process.

## Blocking mode

Most of the time we want `exec()` to return straight away. If we want `exec()` to wait until the command finishes, call `setBlocking()` first:

```php
$process = new Process("sleep", "1");
$process->setBlocking();
$process->exec();

echo $process->getExitCode();
```

Blocking mode is useful for short commands where we still want to use the same output and exit-code API.

## Process state

```php
if($process->isRunning()) {
	echo "Process " . $process->getPid() . " is still running";
}
```

`getPid()` returns the process ID while the process is running, or `null` once it has ended.

`getExitCode()` returns `null` while the process is running. After it ends, it returns the exit code.

## Completion callbacks

Completion callbacks run once when the process is observed to have finished:

```php
$process->onComplete(function(Process $process):void {
	echo "Finished with code " . $process->getExitCode() . PHP_EOL;
});

$process->exec();

while($process->isRunning()) {
	usleep(100_000);
}
```

The callback is dispatched when methods such as `exec()`, `isRunning()` or `getExitCode()` refresh the process status. If we register a callback after the process has already completed, it is called immediately.

Callbacks are not a separate event loop. Our code still needs to check the process state while it is running.

## Terminating a process

```php
use GT\Daemon\Signal;

$process->terminate(Signal::TERM);
```

`terminate()` sends a signal to the process and closes the input, output and error pipes. If the process has not been started, it does nothing.

The default signal is `Signal::TERM`. Other signal constants are listed on [[Reference]].

The process is also terminated when the `Process` object is destroyed.

## Command failures

If the executable cannot be started, `exec()` throws `CommandNotFoundException`:

```php
use GT\Daemon\CommandNotFoundException;

try {
	$process = new Process("/does/not/exist");
	$process->exec();
}
catch(CommandNotFoundException $exception) {
	echo "The command could not be started";
}
```

All package exceptions extend `DaemonException`.

---

Next, continue with [[Pool]] to run several processes together.


`Pool` gives names to several `Process` objects so we can start, read and close them together.

```php
use GT\Daemon\Pool;
use GT\Daemon\Process;

$pool = new Pool();
$pool->add("letters", new Process(PHP_BINARY, "letters.php"));
$pool->add("numbers", new Process(PHP_BINARY, "numbers.php"));

$pool->exec();
```

## Reading from the pool

`read()` collects standard output from every process and prefixes each line with the process name:

```php
while($pool->numRunning() > 0) {
	echo $pool->read();
	usleep(100000);
}

echo $pool->read();
```

Example output:

```text
[letters] A
[numbers] 1
[letters] B
[numbers] 2
```

The prefix is added by the pool. The process itself still writes plain output.

## Reading errors

Error output is handled separately:

```php
fwrite(STDERR, $pool->readError());
```

Error lines are prefixed with the process name and `ERROR`:

```text
[letters ERROR] Could not open dictionary.txt
```

We can also read from one named process:

```php
echo $pool->readOutputOf("letters");
fwrite(STDERR, $pool->readErrorOf("letters"));
```

If there is no process with that name, `readOutputOf()` and `readErrorOf()` throw `DaemonException`.

## Counting running processes

```php
while($pool->numRunning() > 0) {
	echo $pool->read();
	usleep(100000);
}
```

`numRunning()` checks every process and returns the number that are still running.

## Completion callbacks

A pool callback receives the `Process` that completed:

```php
$pool->onComplete(function(Process $process):void {
	echo "One process has finished with code " . $process->getExitCode() . PHP_EOL;
});
```

The callback is connected to each process when it is added to the pool.

Like process callbacks, pool callbacks run when the process status is checked. In most pool loops, that happens through `numRunning()`.

## Closing the pool

```php
$exitCodes = $pool->close();
```

`close()` sends the default termination signal to every process, waits until each one has an exit code, and returns an associative array of process name to exit code.

For example:

```php
[
	"letters" => 0,
	"numbers" => 9,
]
```

Use `close()` when our supervising script is finished with the child processes and needs to tidy them up.

---

Next, continue with [[Reference]] for a compact list of methods and signal constants.


This page lists the public classes and methods provided by the package.

## Process

```php
use GT\Daemon\Process;
```

`new Process(string ...$command)`
: Stores the executable and its arguments. The process does not start until `exec()` is called.

`setExecCwd(string $cwd): void`
: Sets the working directory used when the process starts.

`setEnv(string $key, string $value): void`
: Sets one environment variable for the child process.

`onComplete(callable $callback): void`
: Registers a callback that receives this `Process` once it has finished.

`setBlocking(bool $blocking = true): void`
: Controls whether `exec()` waits for the command to finish.

`exec(): void`
: Starts the process. Throws `CommandNotFoundException` if the command cannot be started.

`isRunning(): bool`
: Returns whether the process is still running.

`hasNotEnded(): bool`
: Returns `true` while the process is running, or after it has ended with exit code `0`.

`getCommand(): array`
: Returns the command array passed to the constructor.

`getOutput(int $pipe = Process::PIPE_OUT): string`
: Reads all currently available output from the selected pipe. By default, it reads standard output.

`getErrorOutput(): string`
: Reads all currently available output from standard error.

`getExitCode(): ?int`
: Returns `null` while the process is running, then the exit code after it has ended.

`getPid(): ?int`
: Returns the process ID while the process is running, otherwise `null`.

`terminate(int $signal = Signal::TERM): void`
: Sends a signal to the process and closes its pipes.

## Pool

```php
use GT\Daemon\Pool;
```

`add(string $name, Process $process): void`
: Adds a process to the pool under the supplied name.

`onComplete(callable $callback): void`
: Registers a callback that receives each `Process` as it finishes.

`exec(): void`
: Starts every process in the pool.

`numRunning(): int`
: Returns the number of processes still running.

`read(int $pipe = Process::PIPE_OUT): string`
: Reads currently available output from all processes, prefixing each line with the process name.

`readError(): string`
: Reads standard error from all processes.

`readOutputOf(string $name, int $pipe = Process::PIPE_OUT): string`
: Reads currently available output from one named process.

`readErrorOf(string $name): string`
: Reads standard error from one named process.

`close(): array`
: Terminates every process and returns an associative array of exit codes.

## Pipe constants

```php
Process::PIPE_IN
Process::PIPE_OUT
Process::PIPE_ERROR
```

Most code only needs `PIPE_OUT` and `PIPE_ERROR`.

## Signal constants

`Signal` exposes POSIX signal constants for use with `Process::terminate()`:

```php
use GT\Daemon\Signal;

$process->terminate(Signal::TERM);
```

Available constants are:

```text
ABRT, ALRM, BABY, BUS, CHLD, CLD, CONT, FPE, HUP, ILL, INT,
IO, IOT, KILL, PIPE, POLL, PWR, QUIT, URG, USR1, USR2, SEGV,
STKFLT, STOP, SYS, TSTP, TERM, TTIN, TTOU, TRAP, WINCH, XCPU,
XFSZ
```

These constants map directly to PHP's `SIG*` constants from the `pcntl` extension.

## Exceptions

`DaemonException`
: Base exception for this package.

`CommandNotFoundException`
: Thrown when a process command cannot be started.




---

# Documentation: DataObject

`DataObject` is a small immutable container for structured data.

It is designed for the common case where we want to move data around an application without exposing a mutable array or `stdClass` to every part of the codebase.

The public API is centred around two classes:

- `GT\DataObject\DataObject`, which stores and reads the data
- `GT\DataObject\DataObjectBuilder`, which creates `DataObject` instances from existing PHP structures

## What this library does

- Stores key/value data in an immutable object.
- Provides typed getters such as `getString()`, `getInt()` and `getDateTime()`.
- Supports nested `DataObject` instances.
- Converts back to arrays, plain objects and JSON.
- Builds data objects from associative arrays or standard objects.
- Checks array contents against primitive or class types when required.

## Where this library fits in

This package is fully standalone:

```bash
composer require phpgt/dataobject
```

It is also installed as a dependency of PHP.GT/WebEngine, so you can use it directly in WebEngine applications without extra setup. The examples in this guide stay framework-independent so the API is clear in isolation.

Other PHP.GT packages also build on the same idea. For example, [PHP.GT/Fetch][fetch] returns structured response objects, and [PHP.GT/Json][json] extends this package for JSON-specific behaviour.

## A tiny example

```php
use GT\DataObject\DataObject;

$user = (new DataObject())
	->with("id", 105)
	->with("name", "Cody")
	->with("active", true);

echo $user->getInt("id"), PHP_EOL;
echo $user->getString("name"), PHP_EOL;
echo $user->getBool("active") ? "yes" : "no", PHP_EOL;
```

Each call to `with()` returns a new object, leaving the previous instance unchanged.

---

Continue with [[Quick start]] to install the package and build the first `DataObject`.

[fetch]: https://www.php.gt/fetch
[json]: https://www.php.gt/json


In this guide we will install `phpgt/dataobject`, create a `DataObject` directly, then build one from an existing PHP structure.

> [!NOTE]
> In WebEngine, this package is already present as a dependency, so you can use `GT\DataObject\DataObject` and `GT\DataObject\DataObjectBuilder` directly from your page logic or application classes.

## 1. Install the package

```bash
composer require phpgt/dataobject
```

## 2. Create a `DataObject` directly

The simplest way to start is to create an empty object and add keys with `with()`:

```php
use GT\DataObject\DataObject;

$product = new DataObject()
	->with("name", "Notebook")
	->with("price", 7.99)
	->with("inStock", true);
```

`DataObject` is immutable, so `with()` does not modify the existing instance. It returns a new one with the extra key.

## 3. Read values back out

```php
echo $product->getString("name"), PHP_EOL;
echo $product->getFloat("price"), PHP_EOL;
echo $product->getBool("inStock") ? "yes" : "no", PHP_EOL;
```

The typed getters cast or convert where it makes sense:

- `getString()` casts scalars to strings
- `getInt()` casts strings, floats and booleans to integers
- `getFloat()` casts strings, integers and booleans to floats
- `getBool()` casts common PHP scalar values to booleans
- `getDateTime()` converts strings, integers and floats to `DateTimeImmutable`

## 4. Build from an associative array

If the data already exists in PHP, use `DataObjectBuilder`:

```php
use GT\DataObject\DataObjectBuilder;

$builder = new DataObjectBuilder();
$product = $builder->fromAssociativeArray([
	"id" => 105,
	"name" => "Notebook",
	"tags" => ["stationery", "paper"],
	"supplier" => [
		"name" => "Northwind",
		"country" => "UK",
	],
]);
```

Associative arrays are turned into nested `DataObject` instances. Indexed arrays stay as arrays.

## 5. Build from an object

The same builder can work from a plain object:

```php
$source = new StdClass();
$source->id = 105;
$source->name = "Notebook";
$source->supplier = new StdClass();
$source->supplier->name = "Northwind";

$product = $builder->fromObject($source);
echo $product->getObject("supplier")?->getString("name");
```

At this point we have the shape of the library: build an immutable object once, then pass it around safely.

---

Next, move on to [[Building]] to see exactly how arrays, objects, nesting and builder errors behave.


This page focuses on `DataObjectBuilder`, which turns existing PHP data into immutable `DataObject` instances.

## Building from associative arrays

Use `fromAssociativeArray()` when the source data is an array of key/value pairs:

```php
use GT\DataObject\DataObjectBuilder;

$builder = new DataObjectBuilder();
$order = $builder->fromAssociativeArray([
	"id" => 501,
	"status" => "packed",
	"customer" => [
		"name" => "Ada",
		"email" => "ada@example.com",
	],
]);
```

In the example above:

- `id` and `status` stay as scalar values
- `customer` becomes a nested `DataObject`

If a value is an indexed array, it remains an array:

```php
$order = $builder->fromAssociativeArray([
	"items" => [
		["sku" => "A1"],
		["sku" => "B2"],
	],
]);
```

Each associative array inside the indexed `items` array is converted into a `DataObject`.

## Building from objects

Use `fromObject()` when the source is a plain PHP object:

```php
$source = new StdClass();
$source->id = 501;
$source->customer = new StdClass();
$source->customer->name = "Ada";
$order = $builder->fromObject($source);
```

Nested objects are converted into nested `DataObject` instances.

If an object property contains an indexed array, the array stays an array. Any object elements inside that array are converted recursively.

## Empty arrays

Empty arrays are preserved in both builder methods:

```php
$settings = $builder->fromAssociativeArray([
	"enabled" => true,
	"flags" => [],
]);

var_dump($settings->getArray("flags")); // []
```

## Builder exceptions

The builder deliberately keeps the source shape consistent.

`fromObject()` expects objects and indexed arrays. If it finds an associative array inside an object structure, it throws `AssociativeArrayWithinObjectException`.

`fromAssociativeArray()` expects associative arrays and indexed arrays. If it finds an object directly inside an associative array structure, it throws `ObjectWithinAssociativeArrayException`.

These exceptions both extend `BuilderException`, which extends `DataObjectException`.

## Using your own subclass

`fromObject()` accepts an optional class name as its second argument:

```php
use GT\DataObject\DataObject;

class UserData extends DataObject {}

$source = new StdClass();
$source->name = "Ada";
$source->profile = new StdClass();
$source->profile->city = "Leeds";

$user = $builder->fromObject($source, UserData::class);
```

The root object and any nested objects built from that source will use `UserData`.

This custom-class option is only available on `fromObject()`. `fromAssociativeArray()` always returns `DataObject`.

---

Next, continue with [[Reading]] to see how values are read safely once the data is inside a `DataObject`.


Once the data is inside a `DataObject`, the public API is deliberately small.

## `get()`

`get()` returns the raw stored value:

```php
use GT\DataObject\DataObject;

$user = (new DataObject())
	->with("name", "Ada")
	->with("age", 27);

var_dump($user->get("name")); // "Ada"
var_dump($user->get("age"));  // 27
```

If the key does not exist, `get()` returns `null`.

## Typed getters

`DataObject` implements the `TypeSafeGetter` contract, so it provides:

- `getString()`
- `getInt()`
- `getFloat()`
- `getBool()`
- `getDateTime()`
- `getInstance()`

Example:

```php
use GT\DataObject\DataObject;

$user = new DataObject()
	->with("id", "105")
	->with("active", 1)
	->with("joined", "2024-03-01 09:30:00");

echo $user->getInt("id"), PHP_EOL;
echo $user->getBool("active") ? "yes" : "no", PHP_EOL;
echo $user->getDateTime("joined")?->format("Y-m-d"), PHP_EOL;
```

The typed getters return `null` when the key is missing or explicitly contains `null`.

## Working with nested objects

Use `getObject()` when you expect another `DataObject` of the same class:

```php
use GT\DataObject\DataObject;

$address = (new DataObject())
	->with("town", "Leeds");

$user = (new DataObject())
	->with("address", $address);

echo $user->getObject("address")?->getString("town");
```

Because `getObject()` uses `static`, it also works correctly with subclasses.

If you want a different object type, use `getInstance()`:

```php
$value = $user->getInstance("address", DataObject::class);
```

## `contains()` and `typeof()`

`contains()` tells you whether `isset()` succeeds for a key:

```php
use GT\DataObject\DataObject;

$data = new DataObject()
	->with("name", "Ada")
	->with("empty", null);

var_dump($data->contains("name"));  // true
var_dump($data->contains("empty")); // false
```

That means a key set to `null` counts as not contained. See [bug #54](https://github.com/phpgt/DataObject/issues/54).

If you need to distinguish between a missing key and a key explicitly set to `null`, use `typeof()`:

```php
var_dump($data->typeof("name"));
var_dump($data->typeof("empty"));
var_dump($data->typeof("missing"));
```

`typeof()` returns:

- primitive names such as `string`, `int`, `float`, `bool` and `null`
- the class name for objects
- `null` if the key does not exist at all

## Removing keys

`without()` is the inverse of `with()`:

```php
use GT\DataObject\DataObject;

$user = new DataObject()
	->with("name", "Ada")
	->with("email", "ada@example.com");

$publicUser = $user->without("email");
```

This is often useful when the same source data is passed to two different parts of the system but one of them should not see everything.

---

Next, move on to [[Converting]] to see how arrays, JSON and fixed-type array reads work.


There are two common reasons to convert a `DataObject` back out again:

- a caller expects an array or plain object
- one key contains an array and you want to read it with fixed element types

## `getArray()`

Use `getArray()` to read an array value:

```php
use GT\DataObject\DataObject;

$report = new DataObject()
	->with("scores", ["1", "2", "3.5"]);

$scores = $report->getArray("scores");
```

If the key is missing, `getArray()` returns `null`.

If the stored value is a nested `DataObject`, `getArray()` first converts it with `asArray()`.

## Fixed-type arrays

Pass a second argument to cast or validate each element:

```php
use GT\DataObject\DataObject;

$report = new DataObject()
	->with("scores", ["1", "2", "3.5"]);

$scores = $report->getArray("scores", "int");
var_dump($scores); // [1, 2, 3]
```

For built-in primitive checks, each element is cast individually. Common examples are:

- `"int"`
- `"float"`
- `"bool"`
- `"string"`

Class and interface names work too:

```php
use DateTimeImmutable;
use DateTimeInterface;
use GT\DataObject\DataObject;

$dates = new DataObject()
	->with("dates", [
		new DateTimeImmutable("2024-01-01"),
		new DateTimeImmutable("2024-02-01"),
	]);

$typedDates = $dates->getArray("dates", DateTimeInterface::class);
```

When a class or interface name is used, values are not cast. They must already be instances of the requested type, otherwise `TypeError` is thrown.

Passing a type name that does not exist also throws `TypeError`.

## `asArray()`

`asArray()` returns the whole object as a PHP array:

```php
use GT\DataObject\DataObject;

$user = new DataObject()
	->with("name", "Ada")
	->with("address", (new DataObject())->with("town", "Leeds"));

print_r($user->asArray());
```

Nested `DataObject` instances are converted recursively.

## `asObject()`

`asObject()` performs the same recursive conversion, but returns a plain object graph:

```php
$userObject = $user->asObject();
echo $userObject->address->town;
```

## JSON serialisation

`DataObject` implements `JsonSerializable`, and `jsonSerialize()` delegates to `asArray()`:

```php
echo json_encode($user), PHP_EOL;
```

That means a nested `DataObject` becomes nested JSON objects and arrays in the final output.

---

Next, have a look at [[Examples]] for a few complete patterns you can adapt in your own project.


This page collects a few small complete examples.

## 1. Build a DTO and serialise it to JSON

```php
use GT\DataObject\DataObject;

$user = (new DataObject())
	->with("id", 105)
	->with("name", "Cody")
	->with("roles", ["author", "editor"]);

echo json_encode($user), PHP_EOL;
```

Output:

```json
{"id":105,"name":"Cody","roles":["author","editor"]}
```

## 2. Start from decoded JSON

```php
use GT\DataObject\DataObjectBuilder;

$json = <<<'JSON'
{
	"name": "Cody",
	"address": {
		"town": "Leeds"
	},
	"food": [
		"biscuits",
		"mushrooms"
	]
}
JSON;

$builder = new DataObjectBuilder();
$user = $builder->fromObject(json_decode($json));

echo $user->getString("name"), PHP_EOL;
echo $user->getObject("address")?->getString("town"), PHP_EOL;
echo $user->getArray("food")[0], PHP_EOL;
```

## 3. Remove private fields before passing data on

```php
use GT\DataObject\DataObject;

$user = (new DataObject())
	->with("name", "Cody")
	->with("email", "cody@example.com")
	->with("creditCard", "4111 1111 1111 1111");

$shippingCopy = $user->without("creditCard");
```

`$user` still contains the original data. `$shippingCopy` is a separate immutable object without the sensitive key.

## 4. Cast each element of an array

```php
use GT\DataObject\DataObject;

$scores = (new DataObject())
	->with("scores", ["1", "2", "3.14159"]);

$wholeNumbers = $scores->getArray("scores", "int");
print_r($wholeNumbers);
```

Output:

```text
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
)
```

## 5. Build a custom subclass from an object

```php
use GT\DataObject\DataObject;
use GT\DataObject\DataObjectBuilder;

class UserData extends DataObject {}

$source = (object)[
	"name" => "Cody",
	"profile" => (object)[
		"town" => "Leeds",
	],
];

$builder = new DataObjectBuilder();
$user = $builder->fromObject($source, UserData::class);
```

Both `$user` and `$user->getObject("profile")` will be instances of `UserData`.




---

# Documentation: Database

This library gives us a tidy way to keep SQL close to the application, without mixing query strings throughout our PHP code.

 We can organise queries into collections, bind values safely, fetch predictable PHP types, and keep schema changes under version control.

> [!NOTE]
> If you are building with WebEngine, most of the setup is already done for you. The framework wires up the database service, reads configuration, and exposes the migration command through `gt migrate`. The WebEngine overview page is at https://www.php.gt/docs/webengine/database/.

## What this library does

- Stores queries in files or PHP query classes.
- Executes named queries through one `Database` object.
- Supports positional and named parameter binding.
- Returns rows and result sets through consistent helper types.
- Supports multiple named connections.
- Runs schema migrations with integrity checks.
- Supports branch-local development migrations as well as canonical migrations.

## Recommended reading order

1. [[Quick start guide]]
2. [[Configuration and connections]]
3. [[Query collections]]
4. [[Parameter binding]]
5. [[Raw SQL and result sets]]
6. [[Type-safe getters]]
7. [[Database migrations]]
8. [[Examples]]

## A tiny example

```php
use Gt\Database\Connection\Settings;
use Gt\Database\Database;

$settings = new Settings(
	"query",
	Settings::DRIVER_SQLITE,
	"app.sqlite"
);

$db = new Database($settings);
$userRow = $db->fetch("user/getById", 42);
echo "User email address: " . $userRow->getString("email");
```

In a nutshell: queries live on disk, the PHP code calls them by name, and the result comes back through a small type-safe API.

---

To see the full setup from scratch, move on to the [[Quick start guide]].


In this section we will build a tiny project that can run one query against a SQLite database.

> [!TIP]
> In WebEngine, the same query layout is used, but you usually do not instantiate `Database` yourself. You write queries in `query/`, configure the database in `config.ini`, and use the injected database service from your page logic. See https://www.php.gt/webengine/database/.

## 1. Install the library

```bash
composer require phpgt/database
```

## 2. Create a query directory

`mkdir -p query/user`

Create the file `query/user/getById.sql`:

```sql
select 
	id, 
	email
from 
	user
where 
	id = ?
limit 1
```

Calling `user/getById` later will resolve to this file.

## 3. Create a database connection

```php
use Gt\Database\Connection\Settings;
use Gt\Database\Database;

$settings = new Settings(
	"query",
	Settings::DRIVER_SQLITE,
	"app.sqlite"
);

$db = new Database($settings);
```

This example uses SQLite because it is simple to start with and does not need a running server.

## 4. Run the query

```php
$userRow = $db->fetch("user/getById", 105);
echo $userRow?->getString("email");
```

The first argument is always the query name. The remaining arguments are the values to bind.

## 5. Build out the rest of the CRUD layer

Once the first query works, it is natural to add more files:

- `query/user/insert.sql`
- `query/user/updateEmail.sql`
- `query/user/delete.sql`

Then we can call them in the same style:

```php
$newId = $db->insert("user/insert", [
	"email" => "dev@example.com",
]);

$rowsUpdated = $db->update("user/updateEmail", [
	"id" => $newId,
	"email" => "new@example.com",
]);

$rowsDeleted = $db->delete("user/delete", $newId);
```

At this point the basics are in place: query files, one connection, and a consistent PHP API.

---

Next, move on to [[Configuration and connections]] so we can see how the connection object is configured properly.


The `Settings` class describes where queries live and how to connect to the database.

## The constructor at a glance

The constructor arguments are:

1. base query directory
2. driver
3. schema or SQLite file path
4. host
5. port
6. username
7. password
8. connection name
9. collation
10. charset
11. initial SQL to run after connecting

In practice, most projects only need the first three for SQLite, or the first seven for a server database.

## Common driver examples

SQLite:

```php
$settings = new Settings(
	"query",
	Settings::DRIVER_SQLITE,
	"app.sqlite"
);
```

MySQL:

```php
$settings = new Settings(
	"query",
	Settings::DRIVER_MYSQL,
	"my_website",
	"localhost",
	3306,
	"app_user",
	"app_pass",
);
```

## Immutable configuration helpers

`Settings` uses an immutable style. If we change one value, we get back a new object.

```php
$reportingSettings = $settings
	->withConnectionName("reporting")
	->withHost("db.internal")
	->withPort(3307);
```

This keeps connection changes explicit and third parties cannot modify them.

## Multiple connections

If we add more than one `Settings` object to `Database`, each connection can have its own name.

```php
use Gt\Database\Database;

$db = new Database($mainSettings, $reportingSettings);

$rows = $db->queryCollection("event", "reporting")
	->fetchAll("listRecent");
```

For raw SQL, the connection name is the third argument:

```php
$db->executeSql("select 1", [], "reporting");
```

## PHP query namespace

If we use PHP query classes instead of SQL files, the default namespace is `\App\Query`.

```php
$db->setAppNameSpace("MyWebsite\\Query");
```

> [!NOTE]
> In WebEngine, most projects express these settings in `config.ini` rather than building `Settings` manually. The framework then constructs the database service for you. The WebEngine guide is at https://www.php.gt/docs/webengine/database.

---

Next, move on to [[Query collections]] to see how query names map cleanly to files and classes.


A query collection is simply a group of related queries, bundled within a directory of SQL or PHP files.

Most of the time, this means a directory in `query/`:

```text
query/
└── user/
    ├── getById.sql
    ├── insert.sql
    └── updateEmail.sql
```

## Calling SQL query files

If we create `query/user/getById.sql`, we call it like this:

```php
$row = $db->fetch("user/getById", 105);
```

The path maps directly to the query name, which makes it easy to find the SQL later.

These separators are supported:

- `user/getById`
- `user.getById`
- `user\\getById`

Using `/` is the clearest option and is the recommended style in these docs.

## Nested collections

Collections can be nested when that structure is useful.

```php
$db->fetch("admin/audit/listRecent");
```

That would resolve to `query/admin/audit/listRecent.sql`.

## Working with a `QueryCollection` object

Sometimes it is helpful to pass only part of the database API into another class. This allows the concept of encapsulation to be applied to the database layer.

```php
$userDb = $db->queryCollection("user");

$user = $userDb->fetch("getById", 105);
$allUsers = $userDb->fetchAll("listAll");
$newId = $userDb->insert("insert", [
	"email" => "dev@example.com",
]);
```

This is a tidy way to keep a repository or service focused on one area of the schema.

Note that only the query name is required to be passed as the first paramter to the fetch/fetchAll queries, and that the `$userDb` reference can now be passed to areas of code related to working with the user records - the code can call all of the queries within the provided query collection, but are unable to call queries outside of the collection. As an example of when this could be used: a `ShippingService` will need to query within the `shipping` query collection, but should be prohibited from calling queries within the `payment` collection. 

## PHP query collections

PHP query classes are also supported, for when SQL queries add limitations.

```php
namespace App\Query;

use Gt\SqlBuilder\SelectBuilder;

class Product {
	public function listAll():SelectBuilder {
		return new SelectBuilder()
			->select("id", "name")
			->from("product");
	}
	
	public function listByCategory():SelectBuilder {
		return $this->listAll()->where("category = :category");
	}
}
```

Then we can call:

```php
$db->fetchAll("Product/listByCategory", [
	"category" => "books",
]);
```

> [!TIP]
> PHP query classes are most helpful when we want to generate SQL programmatically, often with `phpgt/sqlbuilder`. The main SQL Builder docs live separately at https://www.php.gt/sqlbuilder.

> [!NOTE]
> In WebEngine, the same query collection layout is used under the project `query/` directory. This means the structure you learn here transfers directly into a WebEngine application.

---

Next, move on to [[Parameter binding]] so we can pass values into these queries safely and readably.


Parameter binding is what lets us keep SQL readable while passing values safely from PHP.

## Positional placeholders

Use `?` when the query only needs a small number of values and the order is obvious.

```sql
select 
	id, 
	name, 
	email
	
from 
	user
	
where 
	id = ?
	
limit 1
```

```php
$userRow = $db->fetch("user/getById", 105);
```

This style is compact and clear when there is only one or two values to bind.

## Named placeholders

Use named placeholders when the meaning of the values matters more than their order.

```sql
select 
	id, 
	name, 
	email
	
from 
	user
	
where 
	email = :email
and 
	isActive = :isActive
```

```php
$userRow = $db->fetch("user/getByEmail", [
	"email" => "dev@example.com",
	"isActive" => true,
]);
```

This tends to be the better choice once a query grows beyond a couple of values.

## Automatic value handling

The library helps with a few common conversions for us:

- `bool` becomes a database-friendly truthy value.
- `DateTimeInterface` is formatted as `Y-m-d H:i:s`.
- arrays expand into indexed placeholders such as `:ids__0`, `:ids__1` (for using within `in()` conditions, for example).

## Special bindings

Some placeholders are designed for safe structural SQL fragments:

- `:groupBy`
- `:orderBy`
- `:limit`
- `:offset`
- `:infileName`

Example:

```sql
select 
	id, 
	email
from 
	user
	
order by :orderBy
limit :limit
offset :offset
```

```php
$resultSet = $db->fetchAll("user/list", [
	"orderBy" => "id desc",
	"limit" => 20,
	"offset" => 40,
]);
```

## Dynamic bindings

For more dynamic query shapes, these reserved bindings are available:

- `:__dynamicValueSet`
- `:__dynamicIn`
- `:__dynamicOr`

These are useful when we want flexible SQL without dropping into manual string concatenation.

Example: https://github.com/PhpGt/Database/blob/master/example/04-dynamic-bindings.php

> [!TIP]
> In WebEngine, binding works in exactly the same way because the query execution still comes from this package. The WebEngine layer mainly saves you from connection setup and command wiring.

---

Next, move on to [[Raw SQL and result sets]] to see what comes back from the database layer and when `executeSql()` is appropriate.


Most of the time, query files are the best fit. Raw SQL is still available when we genuinely need it.

## `executeSql()`

```php
$result = $db->executeSql("select count(*) as total from user");
```

This is useful for one-off statements, administrative commands, or cases where creating a named query file would not improve clarity.

If we have multiple connections, the third argument is the connection name:

```php
$result = $db->executeSql(
	"select count(id) as total from user_page",
	[],
	"analytics"
);
```

## Working with `ResultSet`

The result object is consistent across both named queries and raw SQL:

- `fetch():?Row` returns one `Row` or `null`.
- `fetchAll():ResultSet<Row>` returns an iterable `ResultSet` of rows.
- `affectedRows():int` returns the changed row count.
- `lastInsertId():string` returns the inserted id as a string.
- `asArray():array<string, bool|int|float|string>` returns plain arrays.
- `ResultSet` is iterable and countable.

```php
$resultSet = $db->fetchAll("user/getAllActive");

foreach($resultSet as $row) {
	echo $row->getString("email"), PHP_EOL;
}
```

## Multi-statement SQL files

One query file may contain more than one SQL statement, separated by semicolons.

That means we can keep a tightly related set of setup statements in one place when it improves readability. The statements are split and executed in order.

> [!NOTE]
> For schema changes over time, migrations are still the better tool. Multi-statement query files are for query execution; migrations are for controlled schema history.

---

Next, move on to [[Type-safe getters]] to see the small helpers that turn common single-column queries into clean PHP values.


This library includes a small set of helpers for common cases where a query returns one column and we already know the PHP type we want.

## Single-value helpers

If a query returns one value, we can ask for that type directly:

- `fetchBool()`
- `fetchString()`
- `fetchInt()`
- `fetchFloat()`
- `fetchDateTime()`

```php
$username = $db->fetchString("user/getUsernameById", 105);
$score = $db->fetchFloat("score/calculateForUser", 8008);
$lastActivity = $db->fetchDateTime("user/getLatestActivity", 654);
```

This removes the usual "fetch row, then extract one column" boilerplate.

## Multiple typed values

If the query still returns one column, but many rows, there are matching array helpers:

- `fetchAllBool()`
- `fetchAllString()`
- `fetchAllInt()`
- `fetchAllFloat()`
- `fetchAllDateTime()`

```php
$userIds = $db->fetchAllInt("user/getAllIds");
```

## Typed access on `Row`

When we use `fetch()` or iterate over `fetchAll()`, each row also provides typed getters:

- `getString()`
- `getInt()`
- `getFloat()`
- `getBool()`
- `getDateTime()`
- `get()`
- `asArray()`

```php
$userRow = $db->fetch("user/getById", 105);

if($userRow) {
	echo $userRow->getString("email");
}
```

The `getDateTime()` helper accepts common database date strings as well as Unix timestamps.

Example: https://github.com/PhpGt/Database/blob/master/example/03-type-safe-getters.php

---

Next, move on to [[Database migrations]] to see how schema changes are tracked and applied safely.


Database migrations let us keep schema changes in version control and apply them in a predictable order, so development machines and production servers are ensured to be running the same schema.

> [!NOTE]
> In WebEngine, the same migrator is surfaced through `gt migrate`, so the file layout and flags on this page apply directly to a WebEngine project. The WebEngine overview is at https://www.php.gt/webengine/database/.

## Storing migration files

The default migration directory is:

```text
query/_migration/
```

Migration files must:

- end with `.sql` or `.php`.
- start with a numeric prefix.
- use a continuous numerical sequence with no gaps.
- keep the same contents once they have been run.

Examples:

- `0001-create-user.sql`
- `0002-add-created-at.sql`
- `0003-index-user-email.sql`

The numeric prefix must be at the start of the filename. A file like `a002-second.sql` is ignored rather than treated as migration `2`.

## What the migrator stores

The migrator keeps its state in a database table, `_migration` by default.

For each migration it records:

- the migration number.
- a hash of the file contents.
- when it was applied.

That hash is what makes integrity checks possible. If we edit a migration after it has already run, the migrator will stop and tell us the history has changed.

## Running migrations in code

```php
use Gt\Database\Connection\Settings;
use Gt\Database\Migration\Migrator;

$settings = new Settings(
	"query",
	Settings::DRIVER_SQLITE,
	"app.sqlite"
);

$migrator = new Migrator($settings, "query/_migration");
$migrator->createMigrationTable();

$files = $migrator->getMigrationFileList();
$migrator->checkFileListOrder($files);

$current = $migrator->getMigrationCount();
$migrator->checkIntegrity($files, $current);
$migrator->performMigration($files, $current);
```

That flow is safe to rerun. Only pending migrations will be applied. 

## CLI usage

The package ships with `bin/migrate`, and WebEngine exposes the same behaviour through `gt migrate`.

```bash
php bin/migrate execute
php bin/migrate execute --force
php bin/migrate execute --reset
php bin/migrate execute --reset 3
```

What the flags do:

- no flag: apply pending canonical migrations
- `--force`: drop the schema and run again from migration `1`
- `--reset`: rerun only the latest canonical migration
- `--reset 3`: rerun from migration `4` onwards

For SQLite, `--force` resets the database by removing the database file and rebuilding it from the migration set.

## Development migrations

For feature branches, there is also a dev migration flow:

```text
query/_migration/dev/
```

These files are tracked separately in the `_migration_dev` table, and are intended for branch-local schema changes while work is still in progress.

Use:

```bash
migrate --dev
migrate --dev-merge
```

- `--dev` runs canonical migrations first, then branch-local dev migrations.
- `--dev-merge` promotes applied dev migrations into canonical files in `query/_migration/`, automatically renaming to the numerical sequence.

This keeps feature branch work flexible, while still ending up with one canonical migration history in the main branch.

> [!TIP]
> A sensible workflow is to let each developer keep a local sequence in `query/_migration/dev/`, then have the feature author run `gt migrate --dev-merge` before the work is merged.

## Configuration keys

The CLI and migrators read these settings:

- `database.query_path`
- `database.migration_path`
- `database.migration_table`
- `database.dev_migration_path`
- `database.dev_migration_table`
- `database.driver`
- `database.schema`
- `database.host`
- `database.port`
- `database.username`
- `database.password`

Example: https://github.com/PhpGt/Database/blob/master/example/05-database-migrations.php

---

To see these features in runnable scripts, move on to [[Examples]].


The `example/` directory is the quickest way to see the library in action without creating a full project first.

Example index:

1. [example/01-quick-start.php](https://github.com/PhpGt/Database/blob/master/example/01-quick-start.php)
   A minimal connection and query call.
2. [example/02-parameter-binding.php](https://github.com/PhpGt/Database/blob/master/example/02-parameter-binding.php)
   Positional and named binding.
3. [example/03-type-safe-getters.php](https://github.com/PhpGt/Database/blob/master/example/03-type-safe-getters.php)
   Single-value helpers and typed row access.
4. [example/04-dynamic-bindings.php](https://github.com/PhpGt/Database/blob/master/example/04-dynamic-bindings.php)
   Dynamic binding helpers.
5. [example/05-database-migrations.php](https://github.com/PhpGt/Database/blob/master/example/05-database-migrations.php)
   Canonical migration flow.
6. [example/06-multiple-connections.php](https://github.com/PhpGt/Database/blob/master/example/06-multiple-connections.php)
   Multiple named database connections.
7. [example/07-php-query-collections.php](https://github.com/PhpGt/Database/blob/master/example/07-php-query-collections.php)
   PHP query collections.

Each example creates an isolated workspace, runs the demonstration, and cleans up afterwards. That makes them safe to run repeatedly while learning.

> [!NOTE]
> These examples show the Database component in isolation. In WebEngine, the same query and migration ideas are used, but the surrounding application wiring is handled for you. The WebEngine overview is at https://www.php.gt/webengine/database/.




---

# Documentation: Dom

The Document Object Model (DOM) is an object-oriented interface for interacting with HTML webpages and other XML documents. It's been made extremely popular by its use in JavaScript within the browser.

The DOM represents a document with a logical tree. Each branch of the tree ends in a node, and each node contains objects. DOM methods allow programmatic access to the tree. With them, you can change the document's structure, style, or content.

This project provides access to a DOM within your PHP scripts on the server, for use with HTML or XML Documents, allowing developers to take advantage of the well known web standards and widely understood DOM technologies to produce dynamic pages alongside, or instead of, a template engine.

This documentation does **not** try to re-document the whole browser DOM API. MDN already does that very well. Here we will focus on the parts that matter when using DOM on the server:

- how to construct documents and parse markup
- how the live collections behave
- where the implementation intentionally differs from the browser
- how to fit the library into WebEngine applications
- when DomTemplate is a better choice than manual DOM manipulation

> [!IMPORTANT]
> If you are building with WebEngine, you usually do not construct `HTMLDocument` yourself. WebEngine provides a pre-constructed HTML document for the page request.
> Within WebEngine applications, DomTemplate is also shipped by default, so it is worth understanding what that library already does before reaching for manual DOM manipulation.
> In many cases, binding data with DomTemplate is the cleaner option because it keeps PHP logic and HTML structure more loosely coupled.

## What this library gives us

- `HTMLDocument` and `XMLDocument` wrappers around PHP's native DOM classes.
- Modern selector-based traversal with `querySelector()` and `querySelectorAll()`.
- Browser-style helpers such as `classList`, `dataset`, `closest()`, `before()`, `after()`, `replaceWith()`, `innerHTML`, and `outerHTML`.
- Live `HTMLCollection` and live/static `NodeList` behaviour where the standard expects it.
- A large amount of element-specific IDL behaviour for forms, tables, media elements, and other HTML interfaces.
- Explicit exceptions when functionality only makes sense in the browser.

## A very small example

```php
use GT\Dom\HTMLDocument;

$html = <<<HTML
<!doctype html>
<h1>Hello, <span class="name">you</span>!</h1>
HTML;

$document = new HTMLDocument($html);
$document->querySelector(".name")->innerText = "Cody";

echo $document;
```

Output:

```html
<!doctype html>
<html><head></head><body><h1>Hello, <span class="name">Cody</span>!</h1></body></html>
```

The code feels very similar to browser DOM code, but it runs entirely on the server.

---

To see where this library fits in, continue to [[Overview]].


This package sits in a deliberately narrow space: it gives us a standards-shaped DOM in PHP, but it does not try to become a framework, router, or templating language.

That is useful when we want to work with HTML or XML documents directly and keep the code close to the web standards many of us already know from the browser.

## What to expect from the API

Most of the public API mirrors familiar DOM concepts:

- documents such as `HTMLDocument` and `XMLDocument`
- generic nodes such as `Element`, `Text`, `Comment`, and `DocumentFragment`
- traversal helpers such as `querySelector`, `children`, `closest`, and `parentElement`
- browser-like collection types such as `HTMLCollection`, `NodeList`, `DOMTokenList`, and `DOMStringMap`

For details of what those APIs do, MDN remains the best reference:

- [Document on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document)
- [Element on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element)
- [HTMLElement on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
- [Node on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Node)

## What this documentation covers instead

The more useful questions for this repository are usually integration questions rather than API catalogue questions:

- When should we construct a document manually?
- What gets added automatically to an `HTMLDocument`?
- Which collections are live?
- What happens when we call browser APIs that only make sense client-side?
- How should this fit into a WebEngine application?
- When should we stop manipulating nodes directly and use DomTemplate instead?

Those are the questions covered in this guide.

## DOM versus DomTemplate

It is perfectly valid to use this library directly:

```php
$price = $document->querySelector(".price");
$price->innerText = "£14.99";
```

But if the application is mainly binding data into HTML, repeating lists, expanding components, or composing page layouts, DOM manipulation can become too tightly coupled to the exact shape of the markup.

That is the gap filled by [DomTemplate](https://www.php.gt/domtemplate): the HTML says what can change, and PHP supplies the data. In WebEngine, DomTemplate is provided by default for precisely that reason.

## WebEngine context

This library is also a foundational part of WebEngine.

- WebEngine provides a pre-constructed `HTMLDocument` for the current page.
- The framework handles the page lifecycle around that document.
- DomTemplate is included by default, so many common page updates can happen declaratively without low-level DOM code.

If you are writing page logic in WebEngine, you will usually work on an existing document rather than instantiate one from scratch, and it would make sense to use DomTemplate's bind attributes rather than manipulating the DOM directly yourself.

## PHP 8.4's native HTMLDocument

Since PHP 8.4, a native `HTMLDocument` class has shipped which enhances the functionality of the old `DOMDocument` class, but still misses a lot of specification in terms of properties and functions. Discussions are being made about whether this native class can be used within this repository, to increase efficiency of code execution and standardise further, but the native class is declared `final` so none of PHP.GT/Dom enhancements can be applied.

That means that for now, the extension of the original `DOMDocument` will continue into the forseable future, but it's worth knowing about PHP's native HTMLDocument class in case you don't need any of this library's helpers.

A small subset of what PHP.GT/Dom has that PHP's native HTMLDocument doesn't: [`document.contentType`](https://developer.mozilla.org/en-US/docs/Web/API/Document/contentType), [`embeds`](https://developer.mozilla.org/en-US/docs/Web/API/Document/embeds), [`forms`](https://developer.mozilla.org/en-US/docs/Web/API/Document/forms), [`images`](https://developer.mozilla.org/en-US/docs/Web/API/Document/images), [`links`](https://developer.mozilla.org/en-US/docs/Web/API/Document/links), [`scripts`](https://developer.mozilla.org/en-US/docs/Web/API/Document/scripts), [`getElementsByName`](https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByName), [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText), [`dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset), [`hidden`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/hidden), [`title`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/title), [`tabIndex`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/tabIndex), `RadioNodeList`(https://developer.mozilla.org/en-US/docs/Web/API/RadioNodeList), and all properties are static (changing the document does not update a referenced NodeList's contents, whereas PHP.GT/Dom's document does).

---

Next, we will put together the smallest useful setup in [[Getting started]].


This section shows the smallest useful setup outside of WebEngine.

> [!TIP]
> In WebEngine, you usually do not need this setup code. The framework gives you a pre-constructed `HTMLDocument`, and DomTemplate is also available by default if the task is really data binding rather than low-level DOM work.

## 1. Install the package

```bash
composer require phpgt/dom
```

The package requires PHP's `dom`, `libxml`, and `mbstring` extensions.

## 2. Construct an `HTMLDocument`

```php
use GT\Dom\HTMLDocument;

$html = <<<'HTML'
<!doctype html>
<h1>Hello, <span class="name">you</span>!</h1>
HTML;

$document = new HTMLDocument($html);
```

At this point we have a document tree we can query and modify using familiar DOM calls.

## 3. Query the document

```php
$name = $document->querySelector(".name");
$name->innerText = "Cody";
```

These methods follow the same basic behaviour documented on MDN:

- [`querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/querySelector)
- [`querySelectorAll()`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/querySelectorAll)
- [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)

## 4. Serialise the document

```php
echo $document;
```

Casting the document to a string serialises it back to markup.

For `HTMLDocument`, the output always includes a doctype and the root document structure:

```html
<!doctype html>
<html><head></head><body><h1>Hello, <span class="name">Cody</span>!</h1></body></html>
```

## 5. Create nodes instead of concatenating HTML when practical

`innerHTML` and `outerHTML` are supported, but when we are constructing a few nodes programmatically it is often clearer to use DOM methods directly:

```php
$list = $document->createElement("ul");

foreach(["Tea", "Milk", "Biscuits"] as $item) {
	$li = $document->createElement("li");
	$li->innerText = $item;
	$list->appendChild($li);
}

$document->body->appendChild($list);
```

MDN references:

- [`createElement()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement)
- [`appendChild()`](https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild)
- [`append()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/append)

## 6. Keep the right level of abstraction

If you find yourself doing lots of this:

```php
$document->querySelector(".customer-name")->innerText = $customer->name;
$document->querySelector(".customer-email")->innerText = $customer->email;
$document->querySelector(".customer-tier")->innerText = $customer->tier;
```

it is worth pausing and asking whether the real problem is template binding rather than DOM manipulation. In WebEngine applications especially, DomTemplate is usually the better fit.

---

Now that we have a document on hand, move on to [[Parsing documents]].


There are three main entry points when working with markup in this library:

- `HTMLDocument` for HTML documents
- `XMLDocument` for XML documents
- `DOMParser` when the incoming content type decides which one to use

## `HTMLDocument`

`HTMLDocument` is the most common starting point.

```php
use GT\Dom\HTMLDocument;

$document = new HTMLDocument("<h1>Hello</h1>");
```

The constructor does a few useful things for us:

- it loads the HTML using PHP's DOM extension
- it ensures there is a root `<html>` element
- it ensures there is a `<head>`
- it ensures there is a `<body>`
- it preserves non-element child nodes where possible

That means even a small fragment ends up as a proper document tree when serialised.

## `XMLDocument`

For XML, use `XMLDocument` instead:

```php
use GT\Dom\XMLDocument;

$document = new XMLDocument('<?xml version="1.0"?><feed />');
```

`XMLDocument` is useful when we are working with XML semantics rather than HTML semantics. In particular, XML-specific features such as CDATA sections belong here, not in `HTMLDocument`.

MDN references:

- [XML DOM overview](https://developer.mozilla.org/en-US/docs/Web/XML/XML_introduction)
- [`createCDATASection()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/createCDATASection)

## `DOMParser`

If we receive markup together with a MIME type, `DOMParser` can choose the right document class:

```php
use GT\Dom\DOMParser;

$parser = new DOMParser();
$document = $parser->parseFromString($markup, "text/html");
```

Supported content types are effectively HTML and XML families. Unsupported MIME types throw a `MimeTypeNotSupportedException`.

MDN reference:

- [`DOMParser.parseFromString()`](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString)

## Character encoding

`HTMLDocument` defaults to `UTF-8`, and the constructor includes a workaround so UTF-8 HTML is parsed and serialised correctly by PHP's DOM layer.

In practice, that means content such as emoji and non-ASCII text can be loaded and emitted without requiring extra manual handling in normal cases.

## Document writing and stream behaviour

The `Document` classes also implement a stream-like interface compatible with PSR-7 style expectations.

```php
$document = new HTMLDocument("<h1>Example</h1>");
$document->open();
$document->write("More text");
echo $document->getContents();
```

This is mainly useful when a document needs to behave like a stream object in surrounding infrastructure.

A few things are worth knowing:

- writing is only supported for `HTMLDocument`
- calling `open()` is required before stream writing
- XML documents are not writable in this way
- `write()` appends to the document body rather than acting like a browser runtime parser

If what you need is normal DOM manipulation, the standard node APIs are usually clearer than the stream API.

## HTML versus XML: practical advice

- Use `HTMLDocument` for webpages, fragments, email markup, generated HTML, and most server-rendered output.
- Use `XMLDocument` for feeds, XML configuration, or XML-based interchange formats.
- Use `DOMParser` when the caller already gives you the content type and you want a standards-shaped entry point.

> [!NOTE]
> In WebEngine, the framework has already loaded the page into an `HTMLDocument`, so this whole document-construction step is usually skipped.

---

Next we will look at the parts of the API that are used to navigate around a document: [[Document traversal]].


## CSS selectors in PHP

The library supports selector-based traversal through:

- [`querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/querySelector)
- [`querySelectorAll()`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/querySelectorAll)
- [`closest()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest)
- [`matches()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches)

```php
$card = $document->querySelector(".product-card");
$buttons = $document->querySelectorAll("form[action] button");
$section = $card?->closest("section");
```

Internally, selectors are translated to XPath. In normal use that is an implementation detail, but it matters in one practical way: invalid selectors raise `XPathQueryException`.

## Live versus static collections

This library follows the DOM's distinction between live and static collections.

### `HTMLCollection` is live

Methods and properties such as these return a live `HTMLCollection`:

- [`children`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/children)
- [`getElementsByTagName()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByTagName)
- [`getElementsByClassName()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getElementsByClassName)
- document-wide properties such as `forms`, `images`, `links`, and `scripts`

```php
$forms = $document->forms;
$document->body->appendChild($document->createElement("form"));

echo $forms->length; // now includes the new form
```

### `querySelectorAll()` returns a static `NodeList`

This matches browser behaviour:

```php
$items = $document->querySelectorAll("li");
```

If the document changes afterwards, that particular result set does not update.

### `getElementsByName()` returns a live `NodeList`

This is one of the places where the return type is `NodeList`, but the behaviour is live.

## Collection helpers

The collection objects are intentionally array-like and iterable in PHP:

```php
foreach($document->images as $image) {
	$image->loading = "lazy";
}

$first = $document->links[0] ?? null;
```

Useful MDN references:

- [HTMLCollection](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection)
- [NodeList](https://developer.mozilla.org/en-US/docs/Web/API/NodeList)

## Child and parent helpers

The server-side API includes the browser-style convenience methods:

- [`append()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/append)
- [`prepend()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/prepend)
- [`before()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/before)
- [`after()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/after)
- [`replaceWith()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/replaceWith)
- [`remove()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove)

```php
$notice = $document->querySelector(".notice");
$notice?->before($document->createElement("hr"));
$notice?->after("Updated just now");
```

These are often more pleasant than the older `insertBefore()`-style calls when we are doing small structural edits.

> [!TIP]
> In WebEngine applications, it is worth checking whether DomTemplate can express the page update before writing repeated manual selectors.

---

With traversal covered, the next page looks at the HTML-specific conveniences and the places where server-side DOM naturally differs from browser DOM: [[Working with HTML-specific helpers]].


Beyond the generic DOM interfaces, this library implements a large amount of browser-style HTML behaviour on `HTMLElement`.

This page is not a catalogue of every element property. Instead, it highlights the pieces that are especially useful in server-side code.

## `classList`

[`classList`](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) behaves as a `DOMTokenList`, so we can add, remove, replace, and toggle class names in a clean way:

```php
$button = $document->querySelector("button");
$button->classList->add("is-ready");
$button->classList->remove("is-loading");
```

This is usually clearer than manual string concatenation on the `class` attribute.

## `dataset`

[`dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) is supported through `DOMStringMap`:

```php
$card = $document->querySelector(".card");
$card->dataset->productId = "42";
```

That becomes `data-product-id="42"` in the markup.

CamelCase property names are converted to kebab-case data attributes, which makes it pleasant to work with from PHP.

To help with static analysis, a non-standard `get` and `set` method is added to `DOMStringMap`, allowing for the following:

```php
$card = $document->querySelector(".card");
$card->dataset->set("productId", "42");
```

## `innerHTML`, `outerHTML`, and `innerText`

These properties are often the quickest way to make targeted changes:

- [`innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)
- [`outerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML)
- [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)

```php
$panel = $document->querySelector("#panel");
$panel->innerHTML = "<p>Updated content</p>";
```

For server-side use, the important distinction is this:

- use `innerText` when the value is text and should be escaped safely
- use `innerHTML` when the value is markup we intend to parse

This matters just as much in PHP as it does in the browser.

`innerText` also respects `[hidden]` ancestors when reading text, which makes it closer to the browser's rendered-text behaviour than plain `textContent`.

## Forms, tables, and document conveniences

This repository includes a substantial amount of HTML-specific IDL behaviour, including support around:

- forms and form controls
- select boxes and `selectedOptions`
- table sections, rows, and cells
- document shortcuts such as `forms`, `images`, `links`, and `scripts`

MDN is the right reference for the precise browser semantics:

- [HTMLFormElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement)
- [HTMLSelectElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement)
- [HTMLTableElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableElement)

The practical point for this library is that we can usually write the same kind of code we would expect in browser JavaScript:

```php
$table = $document->querySelector("table");
$row = $table->insertRow();
$row->insertCell()->innerText = "Ada";
$row->insertCell()->innerText = "Admin";
```

## Browser-only properties

Some parts of the DOM specification simply do not make sense on the server. Anything that depends on user interaction, layout, media playback state, browsing context, or browser UI cannot be implemented in PHP.

In those cases, this library throws `ClientSideOnlyFunctionalityException`.

Examples include behaviour around:

- file inputs and selected files
- media playback state
- iframe browsing contexts
- style/layout information that depends on a rendering engine

That is intentional. It is better to fail explicitly than to pretend the browser state exists on the server when it does not.

## Practical advice

- Use the browser-shaped helpers when they make code clearer.
- Prefer `innerText` or node construction over `innerHTML` for plain text, to avoid [cross-site-scripting](https://owasp.org/www-community/attacks/xss/) attacks.
- Treat `ClientSideOnlyFunctionalityException` as a sign that the job belongs in browser JavaScript rather than server PHP.

---

Next, we will place this library in its most common real-world context: [[WebEngine and DomTemplate]].


For many PHP.GT applications, this is the page that matters most.

`phpgt/dom` is a standalone library and can be used anywhere, but in practice a large amount of usage happens inside WebEngine applications.

## What WebEngine already does for us

WebEngine provides a pre-constructed `HTMLDocument` for the current request. That means:

- the page HTML has already been loaded
- the document lifecycle is already in motion
- your page logic can work on the document immediately

So, in WebEngine, we usually do **not** do this:

```php
$document = new HTMLDocument(file_get_contents("page.html"));
```

because the framework has already done it.

## Manipulating pages using DomTemplate

WebEngine also ships with [DomTemplate](https://www.php.gt/domtemplate) by default.

That is important because many problems that look like DOM problems are actually template-binding problems:

- putting scalar values into the page
- binding object properties
- repeating lists
- composing pages from partials and components
- cleaning up optional elements

When we solve those jobs with direct DOM manipulation, the PHP logic can become tightly coupled to the exact shape of the HTML.

For example:

```php
$document->querySelector(".customer-name")->innerText = $customer->name;
$document->querySelector(".customer-email")->innerText = $customer->email;
$document->querySelector(".customer-status")->innerText = $customer->status;
```

works, but it means changes to the view structure often force changes in the PHP too.

DomTemplate is designed to reduce that coupling. Read more at https://www.php.gt/domtemplate

## A useful division of responsibility

In WebEngine, a practical split is:

- use DomTemplate for binding application data into the page
- use DOM directly when we need structural document operations that are genuinely DOM-shaped

Examples where direct DOM is still a good fit:

- inserting or moving nodes based on parsing or transformation logic
- sanitising or post-processing imported markup
- generating fragments from existing nodes
- working with XML documents or document fragments outside the normal page template flow

Examples where DomTemplate is usually the better fit:

- filling headings, paragraphs, and form values from data
- rendering rows, cards, or menu items from lists
- composing reusable page sections and components

## If you are not using WebEngine

Outside WebEngine, `phpgt/dom` still stands perfectly well on its own. The main difference is that you become responsible for:

- loading the source HTML
- constructing the document
- wiring your own request lifecycle around it

That is completely fine for libraries, scripts, generators, crawlers, email renderers, or bespoke applications.

---

The final page covers the behaviour that is closest to "know this before it catches you out": [[Specification notes and quirks]].


This repository aims to stay very close to the DOM specification, but server-side PHP is not a browser, and PHP's own DOM extension has some constraints of its own.

These are the main points worth keeping in mind.

## 1. Some browser functionality is intentionally unavailable

Anything that depends on browser runtime state, rendering, media playback, user input devices, or browsing context cannot be implemented faithfully on the server.

When code reaches one of those areas, the library throws `ClientSideOnlyFunctionalityException`.

That is expected behaviour, not an incomplete edge case.

## 2. Element typing is specification-shaped, but still PHP-friendly

The library exposes HTML element types through `ElementType`, rather than through a huge inheritance tree of concrete PHP element subclasses that you would check with `instanceof`.

In practice that means we often write:

```php
if($element->elementType === GT\Dom\ElementType::HTMLInputElement) {
	// ...
}
```

instead of depending on a separate PHP class per HTML tag.

## 3. `tagName` casing needs care

One of the long-standing unavoidable differences documented in the project is element name casing.

In normal HTML usage, the library creates HTML elements in lowercase and works consistently with that form. The broader point is that tag-name casing should not be treated as a portability boundary in application logic. Prefer selectors, element type checks, and DOM structure over casing assumptions.

## 4. `HTMLDocument` normalises the document shape

If the incoming HTML does not contain full document structure, the constructor ensures the document still has:

- `<html>`
- `<head>`
- `<body>`

That is helpful for server-side work, but it also means serialised output may be more complete than the input string you started with.

## 5. Some collections are live

This catches people out more in PHP than in JavaScript because we are often less used to keeping long-lived collection objects around.

- `HTMLCollection` is live
- `querySelectorAll()` returns a static `NodeList`
- `getElementsByName()` returns a live `NodeList`

If a collection appears to change "by itself", that is usually just the expected DOM behaviour, and completely consistent with using the document in a browser with JavaScript.

## 6. Invalid selectors fail explicitly

Selector methods are translated internally to XPath. If the selector string is malformed, the library throws `XPathQueryException`.

That is usually preferable to silent failure because it makes bad selectors obvious during development.

## 7. Writing to documents is not a general replacement for DOM manipulation

`Document::open()` and `write()` exist, but in this implementation they are mainly stream-oriented helpers for HTML documents.

For most application code, direct DOM calls such as `append`, `replaceWith`, `innerText`, `innerHTML`, and `createElement` are clearer and less surprising.

## 8. MDN remains the reference for DOM semantics

This guide deliberately does not duplicate the whole DOM API surface.

When you need exact behaviour for a property or method, use MDN:

- [Document](https://developer.mozilla.org/en-US/docs/Web/API/Document)
- [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)
- [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
- [HTML DOM API index](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API)




---

# Documentation: DomTemplate

Built on top of [PHP.GT/Dom][dom], this project provides dynamic data binding to DOM Documents, document templating, and reusable HTML components.

Directly manipulating the DOM in your PHP code can lead to tightly coupling the logic and view. Binding data using custom elements and data attributes leads to highly readable, maintainable view files that are loosely coupled to the application logic.

HTML can be made dynamic with `data-bind` and `data-list` attributes, placeholders such as `{{name}}`, reusable `<custom-components>`, and partial page templates.

Why not just use DOM to manipulate the page?
--------------------------------------------

The layers of your application should ideally have a strong separation of concerns. The layers are often described as the Model, View, and Controller - referred to as [MVC architecture][wiki-mvc]. In MVC, the _Model_ represents the application's data, the _View_ is the HTML user interface, and the _Controller_ contains the PHP application logic that binds data from the Model to the View.

A strong [separation of concerns][wiki-separation-of-concerns] means that HTML view and PHP logic are not tightly coupled. Changes to the HTML structure should not require changes to the PHP data-binding logic. When PHP code directly manipulates the DOM, the HTML and PHP become closely tied together. As a result, even small changes to the HTML can break existing PHP code and force updates whenever the page structure is edited. Data binding helps avoid this problem.

By binding data through the `data-bind:*` attributes introduced by DomTemplate, we can create HTML view files that are more readable, maintainable, and loosely coupled to the PHP controller logic. This means the layout and structure of the HTML can change signifciantly without requiring changes to the PHP code.

An example of what using this project looks like in your HTML:

```html
<!-- 
extends=base-page

[vars]
title=Your order 
-->

<!--
The INI syntax at the start of an HTML file can be used to configure "partial" views.
You can quickly see that this page extends the template provided by base-page.html and
that the `title` is set to Your order. This var can be referred to by the base-page,
setting the page title, for example.
-->

<h1>Your order</h1>

<!-- here is a custom element maintained in its own checkout-list.html -->
<checkout-list />

<p>The order total is <span data-bind:text="priceFormatted">£0.00</span></p>
<p>Items in your order:</p>
<ul>
<!-- the li is marked with data-list so it repeats for every row of a data source -->
	<li data-list>
<!-- the content of the li is clearly marked to show what data to bind -->
		<span data-bind:text="name">Item Name</span>
		<span data-bind:text="priceFormatted">£0.00</span>
	</li>
</ul>
```

In the above example, the HTML can be maintained completely separately to the PHP, promoting a strong separation of concerns. The entire HTML structure can change, without having to communicate this to PHP, as long as the `data-bind:*` and `data-list` attributes are applied to the appropriate elements. This is what's referred to as _loosely coupled_ code - the page logic is loosely coupled to the page view, leading to highly maintainable systems.

> [!NOTE]
> If you are building with WebEngine, this library is provided ready to use without setup. The framework constructs the binder objects, expands partials and components automatically, and cleans the document after your page logic runs.

## What this library does

- Binds scalar values and key/value data to HTML elements.
- Repeats sections of markup from iterable data.
- Binds nested objects and iterable objects to corresponding HTML structure.
- Builds tables from several compatible data structures.
- Expands custom HTML components from separate files.
- Extends page templates using partial HTML documents.

## Recommended reading order

1. [[Overview]]
2. [[Getting started]]
3. [[Binding basics]]
4. [[Bind properties and modifiers]]
5. [[Binding lists]]
6. [[Binding objects]]
7. [[Binding tables]]
8. [[Conditional and optional elements]]
9. [[HTML components]]
10. [[Partials]]
11. [[Debugging]]
12. [[API reference]]

## A simple example

```html
<!doctype html>
<h1>Hello, <span data-bind:text="name">you</span>!</h1>
```

```php
use GT\Dom\HTMLDocument;
use GT\DomTemplate\BindableCache;
use GT\DomTemplate\DocumentBinder;

function example(DocumentBinder $binder):void {
	$binder->bindKeyValue("name", "Cody");
	$binder->cleanupDocument();
	echo $document;
}
```

Output HTML:

```html
<!doctype html>
<h1>Hello, <span>Cody</span>!</h1>
```

In a nutshell: the HTML says what can change, the PHP supplies the data, and DomTemplate joins the two together.

---

To see the whole shape of the library before we start wiring it up, move on to [[Overview]].

[dom]: https://www.php.gt/dom
[domtemplate]: https://www.php.gt/domtemplate
[wiki-mvc]: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
[wiki-separation-of-concerns]: https://en.wikipedia.org/wiki/Separation_of_concerns


DomTemplate falls into three ideas: 

1) bind data into HTML, 
2) repeat bits of HTML from lists of data,
3) compose whole pages from reusable pieces.

In this guide we will build those ideas up one at a time, starting with the smallest useful examples and then gradually moving into the more advanced behaviour.

## 1. Bind data to HTML elements

```html
<p>Welcome back, <span data-bind:text="firstName">friend</span>!</p>
<input name="email" data-bind:value="email" />
```

```php
$binder->bindData([
	"firstName" => "Ada",
	"email" => "ada@example.com",
]);
```

Here we can see the basic pattern of the library: the HTML already contains sensible defaults, and the binder only replaces the pieces we have marked.

## 2. Repeat markup from iterable data

```html
<ul>
	<li data-list data-bind:text>Item</li>
</ul>
```

```php
$binder->bindList([
	"Tea",
	"Milk",
	"Biscuits",
]);
```

If we do this, the original `<li>` is treated as a template and cloned once for each list item.

## 3. Inject partial values with placeholders

```html
<a href="/user/{{id}}">View {{name ?? this user}}</a>
```

```php
$binder->bindData([
	"id" => 210,
	"name" => "Cody",
]);
```

This is handy when we only want to replace part of an attribute or bit of text rather than the whole property.

## 4. Expand components

```html
<profile-summary />
```

If there is a matching component file, DomTemplate will replace the contents of the custom element with that component's HTML.

## 5. Extend partial page templates

```html
<!--
extends=base-page
[vars]
title=Orders
-->

<h1>Orders</h1>
<ul>
	<li data-list>
		<order-item data-bind:id="id" />
	</li>
</ul>
```

A partial template allows us to provide reusable outer page layout in a flexible way that can be extended in other pages.

> [!NOTE]
> In WebEngine applications, the use of _header.html and _footer.html files might be simple enough for your page template needs - consider using this before reaching for partial page templates - it might be a simpler solution that works for you.

---

Now that we know what the library is for, move on to [[getting started]] so we can wire up a working binder.


In this section we will build the smallest useful DomTemplate setup from scratch.

The main thing to know is that `DocumentBinder` is the public entry point, but it relies on a few smaller helper objects behind the scenes. Once those are wired together, we can bind values, lists, tables, components, and partials in a consistent way.

> [!TIP]
> In WebEngine, you usually do not instantiate these objects yourself. The framework builds and injects them for you.

## 1. Install the library

```bash
composer require phpgt/domtemplate
```

## 2. Create an `HTMLDocument`

```php
use Gt\Dom\HTMLDocument;

$html = <<<'HTML'
<!doctype html>
<h1>Hello, <span data-bind:text="name">you</span>!</h1>
HTML;

$document = new HTMLDocument($html);
```

DomTemplate works with `HTMLDocument` from `phpgt/dom`, so this is always our starting point.

## 3. Construct the binder's dependency tree

Each piece of functionality within DomTemplate is controlled by a separate class. Here we'll build up the dependency tree, so all classes are aware of each other in a way that respects object oriented encapsulation:

```php
use GT\DomTemplate\BindableCache;
use GT\DomTemplate\DocumentBinder;
use GT\DomTemplate\ElementBinder;
use GT\DomTemplate\HTMLAttributeBinder;
use GT\DomTemplate\HTMLAttributeCollection;
use GT\DomTemplate\ListBinder;
use GT\DomTemplate\ListElementCollection;
use GT\DomTemplate\PlaceholderBinder;
use GT\DomTemplate\TableBinder;

$elementBinder = new ElementBinder();
$placeholderBinder = new PlaceholderBinder();
$tableBinder = new TableBinder();
$listBinder = new ListBinder();
$listElementCollection = new ListElementCollection($document);
$bindableCache = new BindableCache();
$htmlAttributeBinder = new HTMLAttributeBinder();
$htmlAttributeCollection = new HTMLAttributeCollection();

$elementBinder->setDependencies(
	$htmlAttributeBinder,
	$htmlAttributeCollection,
	$placeholderBinder,
);
$htmlAttributeBinder->setDependencies($listBinder, $tableBinder);
$listBinder->setDependencies(
	$elementBinder,
	$listElementCollection,
	$bindableCache,
	$tableBinder,
);
$tableBinder->setDependencies(
	$listBinder,
	$listElementCollection,
	$elementBinder,
	$htmlAttributeBinder,
	$htmlAttributeCollection,
	$placeholderBinder,
);

$binder = new DocumentBinder($document);
$binder->setDependencies(
	$elementBinder,
	$placeholderBinder,
	$tableBinder,
	$listBinder,
	$listElementCollection,
	$bindableCache,
);
```

That looks like quite a lot at first glance, but we only have to set it up once. After that, all normal binding goes through `$binder`.

## 4. Bind some data

```php
$binder->bindKeyValue("name", "Cody");
```

At this point the document contains the updated text, but it still contains the original DomTemplate attributes too.

## 5. Clean the document

```php
$binder->cleanupDocument();
echo $document;
```

`cleanupDocument()` removes helper attributes such as `data-bind`, `data-list`, `data-template`, and `data-element` from the output. It also removes unbound optional elements marked with `data-element`.

Output HTML:

```html
<!doctype html>
<h1>Hello, <span>Cody</span>!</h1>
```

## 6. Know which binder to use

Most of the time, `DocumentBinder` is the right tool.

- Use `DocumentBinder` when working on the whole page.
- Use `ComponentBinder` when working inside a single expanded component.

`ComponentBinder` has the same binding methods, but it automatically limits the bind scope to one component element.

> [!NOTE]
> In WebEngine, you can just use `Binder` instead of `ComponentBinder` or `DocumentBinder` and you'll be given the correct instance depending on the context in which you're using it.
> Within a page's PHP you'll get the `DocumentBinder` and within a component's PHP you'll get the `ComponentBinder`.

## 7. Optional page composition helpers

If we are also using component files or partial templates, there are two extra helpers:

- `ComponentExpander` expands custom HTML elements from a component directory.
- `PartialExpander` applies a page template from a partial directory.

Those are covered properly later in [[HTML components]] and [[Partials]].

---

Our binder is now wired up. Next we can learn the core public API in [[Binding basics]].


This section covers the main public API of DomTemplate.

Here we will look at the three most common operations:

- bind one value everywhere it's needed
- bind a single named key/value pair
- bind a whole map or object in one operation

Along the way we'll also look at bind contexts, selector strings, and placeholders.

## The `data-bind:*` pattern

At the HTML level, the basic idea is always the same:

```html
<span data-bind:text="name">Guest</span>
<a data-bind:href="#">View profile</a>
```

The bit after `data-bind:` is the **bind property** (e.g. the property of the HTML Element that we'll be setting), and the attribute's value is known as the **bind key** (e.g. the key of the data structure we'll use for the value).

When we bind the key `name`, the first element changes. When we bind the key `profileUrl`, the second element changes - only elements with a matching bind key will be affected, allowing you to keep default values stored within the HTML page itself.

### `bindValue`

`bindValue($value, $context = null)` binds one value to every matching `data-bind:*` attribute that has no key.

HTML:

```html
<p data-bind:text>Hello</p>
<p data-bind:text>Goodbye</p>
```

PHP:

```php
$binder->bindValue("Welcome");
```

Output HTML:

```html
<p>Welcome</p>
<p>Welcome</p>
```

This is especially useful for simple repeated text, scalar list items, or placeholders without named keys.

### `bindKeyValue`

`bindKeyValue(string $key, $value, $context = null)` binds one named key/value pair.

HTML:

```html
<h1>Hello, <span data-bind:text="name">you</span>!</h1>
<p>Signed in as <strong data-bind:text="name">guest</strong>.</p>
```

PHP:

```php
$binder->bindKeyValue("name", "Cody");
```

Output HTML:

```html
<h1>Hello, <span>Cody</span>!</h1>
<p>Signed in as <strong>Cody</strong>.</p>
```

### `bindData`

`bindData($data, $context = null)` binds a whole key/value data source in one call.

HTML:

```html
<h1 data-bind:text="username">Guest</h1>
<p>Email: <span data-bind:text="email">guest@example.com</span></p>
<p>Status: <span data-bind:text="status">Offline</span></p>
```

PHP:

```php
$binder->bindData([
	"username" => "Ada",
	"email" => "ada@example.com",
	"status" => "Reviewing pull requests",
]);
```

If we do this, DomTemplate iterates over each key and applies it anywhere that key is used within the current scope.

## Bind contexts

All the main binding methods accept an optional context.

### Pass an element

```php
$profileSection = $document->querySelector("#profile");
$binder->bindData($profileData, $profileSection);
```

This keeps the binding local to one part of the page.

### Pass a selector string

```php
$binder->bindData($profileData, "#profile");
```

This is often a little more convenient when we already know the selector we want.

> [!NOTE]
> If no element matches the selector string, DomTemplate throws `ContextElementNotFoundException`.

## Placeholders with `{{curly braces}}`

Sometimes we do not want to replace the whole text node or the whole attribute value. We only want to inject part of it.

HTML:

```html
<a href="/user/{{id}}">View {{name ?? this user}}</a>
```

PHP:

```php
$binder->bindData([
	"id" => 42,
	"name" => "Cody",
]);
```

Output HTML:

```html
<a href="/user/42">View Cody</a>
```

If `name` is `null` or an empty string, the default text `this user` is used instead.

## `bindValue` vs placeholders

As a rule of thumb:

- use `data-bind:text`, `data-bind:href`, and friends when we want to replace a whole property
- use `{{placeholder}}` when we only want to replace part of a string

That keeps the HTML easy to read and makes the default state obvious to anyone scanning the template.

## When to clean the document

After binding is finished, call:

```php
$binder->cleanupDocument();
```

That strips DomTemplate's helper attributes from the output and removes any unbound `data-element` nodes.

---

We now have the core mental model in place. Next, move on to [[bind properties and modifiers]] so we can see the different ways an element can be mutated.


Most `data-bind:*` attributes set an element attribute or property, but some bind properties and modifier characters add extra behaviour.

## Common bind properties

Here are the bind properties we will use most often:

- `text` sets `textContent`
- `html` sets `innerHTML`
- `value` sets form values
- `class` adds or toggles class names
- `list` binds a nested iterable into a contained list template
- `table` binds table data into a `<table>`
- `remove` removes an element conditionally
- any other property name is treated as a normal attribute name

## `text` and `html`

HTML:

```html
<p data-bind:text="name">Guest</p>
<div data-bind:html="bioHtml">Plain text bio</div>
```

If we bind `name`, the element's text content changes. If we bind `bioHtml`, the element's inner HTML changes.

> [!IMPORTANT]
> `html` inserts HTML, so it should only be used with trusted content to avoid [cross-site scripting (XSS)][xss]. If we're only using plain text, stick to `text`.

## `class`

Without a modifier, `data-bind:class` adds one or more class names.

HTML:

```html
<div class="panel" data-bind:class="extraClass"></div>
```

If we bind `extraClass` to `featured`, the element ends up with `class="panel featured"`.

If the bound value contains multiple class names separated by spaces, each one is added individually.

HTML:

```html
<div class="panel" data-bind:class="stateClasses"></div>
```

PHP:

```php
$binder->bindKeyValue("stateClasses", "featured compact");
```

Output HTML:

```html
<div class="panel featured compact"></div>
```

Arrays of strings are supported here too, so you can pass an array such as `["featured", "compacts"]` and DomTemplate will add the class names in the array.

### The `:` token modifier

The colon modifier toggles a token within a token list, most commonly a class name.

HTML:

```html
<li data-bind:class=":isSelected selected"></li>
```

If `isSelected` is truthy, `selected` is added. If it is falsey, `selected` is removed.

We can also toggle several classes together:

```html
<li data-bind:class=":isSelected selected featured"></li>
```

If `isSelected` is truthy, both `selected` and `featured` are added. If it is falsey, they are both removed.

If we omit the explicit token name:

```html
<li data-bind:class=":status"></li>
```

the bound value itself becomes the token. This also works with several class names:

```php
$binder->bindKeyValue("status", "featured compact");
```

In that case, both `featured` and `compact` are toggled together.

#### The inverse token modifier

If we want to toggle a token when a value is falsey rather than truthy, we can add `!` alongside `:`.

HTML:

```html
<li data-bind:class=":!isVisible hidden"></li>
```

Here we can read it as: "add `hidden` when `isVisible` is not truthy".

The order of the modifier characters does not matter, so `!:` works in the same way as `:!`:

```html
<li data-bind:class="!:isVisible hidden"></li>
```

### The `?` boolean modifier

The question mark toggles an attribute based on truthiness.

HTML:

```html
<button data-bind:disabled="?isArchived">Archive</button>
```

If `isArchived` is truthy, the button gets `disabled`. Otherwise, that attribute is removed.

#### The `?!` inverse boolean modifier

HTML:

```html
<button data-bind:disabled="?!isEditable">Save</button>
```

Here we can read it as: "disable the button when `isEditable` is not truthy".

The order does not matter here either, so `!?` works in the same way as `?!`:

```html
<button data-bind:disabled="!?isEditable">Save</button>
```

## Boolean equality checks with `=`

We can also make the boolean modifier compare against a specific string value.

HTML:

```html
<label>
	<input type="radio" name="size" value="s" data-bind:checked="?size=s" />
	<span>Small</span>
</label>
<label>
	<input type="radio" name="size" value="m" data-bind:checked="?size=m" />
	<span>Medium</span>
</label>
<label>
	<input type="radio" name="size" value="l" data-bind:checked="?size=l" />
	<span>Large</span>
</label>
```

If `size` is `"m"`, the middle radio becomes checked.

This is especially handy for radios, tab state, and selected options.

### The `@` attribute reference modifier

The `@` modifier lets us reuse an existing attribute value instead of repeating ourselves.

HTML:

```html
<input name="email" data-bind:value="@name" />
```

This behaves as though we had written:

```html
<input name="email" data-bind:value="email" />
```

There is also a shorthand:

```html
<input name="email" data-bind:value="@" />
```

which means the same thing as `@name`.

## Combining modifiers

Modifiers can be combined in one expression.

HTML:

```html
<input
	name="size"
	value="m"
	data-bind:checked="?@name=@value"
	data-rebind />
```

Here we are saying:

- look up the bind key from `name`
- compare it with the current element's `value`
- add `checked` when they match

We can also bundle several modifier expressions for the same property by separating them with semicolons:

```html
<div data-bind:class=":isSelected selected; :isAdmin admin"></div>
```

## `data-rebind`

By default, once a bind attribute has been used, DomTemplate removes it to prevent any further bind functions from affecting the element again.

If we want the property to remain bindable, add `data-rebind`.

HTML:

```html
<button data-bind:disabled="?isBusy" data-rebind>Save</button>
```

This is useful when we bind the same area more than once during one request.

## `data-bind:remove`

`remove` is a special bind property that removes the element itself rather than mutating one of its attributes.

HTML:

```html
<p>
	<span data-bind:remove="?isDay">It's night-time.</span>
	<span data-bind:remove="?!isDay">It's daytime.</span>
</p>
```

If `isDay` is true, the first span disappears. If `isDay` is false, the second span disappears.

## `data-bind:list`

This property binds a nested iterable into a child list template.

HTML:

```html
<section data-bind:list="orderList">
	<ul>
		<li data-list data-bind:text="id">Order</li>
	</ul>
</section>
```

When the key `orderList` is bound, the contained list template is used.

We will cover that properly in the [[binding lists]] section.

## `data-bind:table`

This property tells DomTemplate where table-shaped data should go.

HTML:

```html
<table data-bind:table="sales"></table>
```

We will go through the supported table data shapes in the [[binding tables]] section.

---

Now that the element-level behaviour is clear, move on to [[binding lists]] for the part of the library that does the heavy lifting with repeated markup.

[xss]: https://owasp.org/www-community/attacks/xss/


Binding lists to the document allows us to take any iterative data such as an array of objects from the database, and clone an element in the document for each item in the list. Each cloned element will also have any `data-bind:*` attributes bound at the point of cloning.  

Any element can be marked as a list element with `data-list`, then DomTemplate can clone it once for each item in an iterable data source.

## A simple scalar list

HTML:

```html
<ul>
	<li data-list data-bind:text>Item</li>
</ul>
```

PHP:

```php
$binder->bindList([
	"Tea",
	"Milk",
	"Biscuits",
]);
```

Output HTML:

```html
<ul>
	<li>Tea</li>
	<li>Milk</li>
	<li>Biscuits</li>
</ul>
```

Because the list items are simple strings, we do not need any named bind keys here.

## A list of associative arrays or objects

HTML:

```html
<ul>
	<li data-list>
		<a href="/product/{{id}}">
			<strong data-bind:text="name">Product name</strong>
			<span data-bind:text="price">0.00</span>
		</a>
	</li>
</ul>
```

PHP:

```php
$binder->bindList([
		["id" => 67, "name" => "Pot plant", "price" => 12.99],
		["id" => 20, "name" => "Umbrella", "price" => 9.50],
	]);
]);
```

Here we can see the two list systems working together: the `<li>` repeats, and each clone then receives its own key/value data.

An array of associative arrays is used in this example, but wherever possible it is preferred to have a class representation of the data structure - the benefits will become clear as you read on.

## Associative scalar lists and the reserved key `{{}}`

When the iterable keys matter, DomTemplate exposes the current list key through the reserved bind key `{{}}`.

HTML:

```html
<section>
	<div class="currency" data-list>
		<p data-bind:text="{{}}">CODE</p>
		<p data-bind:text>Name</p>
	</div>
</section>
```

PHP:

```php
$binder->bindList([
	"GBP" => "Pound sterling",
	"EUR" => "Euro",
]);
```

Output HTML: 

```html
<section>
	<div class="currency">
		<p>GBP</p>
		<p>Pound sterling</p>
	</div>
	<div class="currency">
		<p>EUR</p>
		<p>Euro</p>
	</div>
</section>
```

## Named list templates

If a page contains more than one list template, it is often clearer to name them.

HTML:

```html
<section>
	<ul>
		<li data-list="languages" data-bind:text>Language</li>
	</ul>

	<ul>
		<li data-list="games" data-bind:text>Game</li>
	</ul>
</section>
```

PHP:

```php
$binder->bindList(["PHP", "TypeScript", "SCSS"], templateName: "languages");
$binder->bindList(["Portal", "Celeste", "Terraria"], templateName: "games");
```

This is a little easier to reason about than relying on context alone.

## Using a context instead of a template name

An alternative approach is to pass the document context of where the list should be bound: 

```php
$binder->bindList(["PHP", "TypeScript"], "#language-panel");
$binder->bindList(["Portal", "Celeste"], "#game-panel");
```

In this example, we would have un-named `data-list` elements within the individual elements with ID `language-panel` and `game-panel`. If more than 1 unnamed list element exists in the same context, a `ListElementNotFoundInContextException` will be thrown.

## Nested lists

DomTemplate can recurse through nested iterable data.

HTML:

```html
<ul>
	<li data-list>
		<h2 data-bind:text>Artist name</h2>

		<ul>
			<li data-list>
				<h3 data-bind:text>Album title</h3>

				<ol>
					<li data-list data-bind:text>Track</li>
				</ol>
			</li>
		</ul>
	</li>
</ul>
```

PHP:

```php
$binder->bindList([
	"A Band From Your Childhood" => [
		"This Album is Good" => [
			"The Best Song You‘ve Ever Heard",
			"Another Cracking Tune",
			"Top Notch Music Here",
			"The Best Is Left ‘Til Last",
		],
		"Adequate Collection" => [
			"Meh",
			"‘sok",
			"Sounds Like Every Other Song",
		],
	],
	"Bongo and The Bronks" => [
		"Salad" => [
			"Tomatoes",
			"Song About Cucumber",
			"Onions Make Me Cry (but I love them)",
		],
		"Meat" => [
			"Steak",
			"Is Chicken Really a Meat?",
			"Don‘t Look in the Sausage Factory",
			"Stop Horsing Around",
		],
		"SnaxX" => [
			"Crispy Potatoes With Salt",
			"Pretzel Song",
			"Pork Scratchings Are Skin",
			"The Peanut Is Not Actually A Nut",
		],
	],
]);
```

If we do this, the outer list binds artists, the next list binds albums, and the innermost list binds tracks.

## `data-bind:list` for nested object properties

For richer data, `data-bind:list` lets us point at a nested list property.

HTML:

```html
<article>
	<h2 data-bind:text="name">Customer</h2>

	<section data-bind:list="orderList">
		<ul>
			<li data-list>
				<strong data-bind:text="id">Order ID</strong>
				for customer <span data-bind:text="customer.email">you@example.com</span>
			</li>
		</ul>
	</section>
</article>
```

If the bound customer object contains an `orderList` property, DomTemplate binds that sub-list into the nested template automatically.

Within the bind operations, nested properties can be addressed with dot notation - in the example above `customer.email` will set the text of the HTML element to the email property of the customer object from the current bound object.

When a custom element is used as the list container, the list name can be inferred from the tag name:

```html
<order-list data-bind:list>
	<ul>
		<li data-list data-bind:text="id">Order ID</li>
	</ul>
</order-list>
```

`order-list` maps to the key `orderList` on the bound object. // TODO: Link to unit test to show this in action.

## `bindListCallback`

`bindListCallback` works like `bindList`, but gives us a hook for each iteration.

```php
$binder->bindListCallback(
	$productList,
	function(\GT\Dom\Element $template, array $row, int|string $key):array {
		if(($row["stock"] ?? 0) === 0) {
			$template->classList->add("out-of-stock");
		}

		$row["price"] = number_format((float)$row["price"], 2);
		return $row;
	}
);
```

This is useful when we want to tweak the cloned element, adjust the data shape, or skip pre-processing elsewhere.

## `<template data-list>`

List templates do not have to be ordinary visible elements. We can also use real HTML `<template>` elements, which will be unwrapped and removed after binding.

HTML:

```html
<dl>
	<template data-list>
		<dt data-bind:text="{{}}">Key</dt>
		<dd data-bind:text>Value</dd>
	</template>
</dl>
```

PHP: 

```php
$binder->bindList([
	"GBP" => "Pound sterling",
	"EUR" => "Euro",
]);
```

By default, DomTemplate unwraps the template contents and inserts the child nodes into the document.

Output HTML:

```html
<dl>
	<dt>GBP</dt>
	<dd>Pound sterling</dd>

	<dt>EUR</dt>
	<dd>Euro</dd>
</dl>
```

## `data-list-keep-template`

If we want the `<template>` wrapper itself to remain in the output, add `data-list-keep-template`. This is useful if you are planning to [register the template on the client side][client-side-template].

HTML:

```html
<template data-list data-list-keep-template>
	<dt data-bind:text="{{}}">Key</dt>
	<dd data-bind:text>Value</dd>
</template>
```

## Supported iterable types

DomTemplate is happy with:

- arrays
- `Iterator`
- `IteratorAggregate`
- `ArrayIterator`
- iterable objects that also expose bindable properties

That means we can often pass domain objects directly instead of flattening everything into arrays first.

---

When binding lists, we could use associative arrays, but [[binding objects]] opens up many more possibilities.

[client-side-template]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/template


Associative arrays are fine for quick examples, but in real applications we often already have proper objects representing our data.

DomTemplate can bind those objects directly, which means we can keep the type safety and behaviour of our domain model instead of flattening everything into arrays first, and objects also come with additional benefits when binding.

## Public properties are bindable by default

```php
readonly class Customer {
	public function __construct(
		public string $id,
		public string $name,
		public DateTime $createdAt,
	) {}
}
```

HTML:

```html
<h1 data-bind:text="name">Customer name</h1>
<p>Customer ID: <span data-bind:text="id">000</span></p>
<time data-bind:text="createdAt">2000-01-01</time>
```

PHP:

```php
$binder->bindData(new Customer(
	id: "abc123",
	name: "Cody",
	createdAt: new DateTime("2016-07-06 15:04:00"),
));
```

If a public property can be turned into a string, DomTemplate can use it as a bind value.

## `#[Bind]` for explicit bindable methods

Sometimes the value that will be bound to the page needs calculating, rather than setting it as a public property.

```php
use GT\DomTemplate\Bind;

readonly class Customer {
	public function __construct(
		public string $name,
		private DateTime $createdAt,
	) {}

	#[Bind("yearsActive")]
	public function calculateYearsActive():int {
		return $this->createdAt->diff(new DateTime())->y;
	}
}
```

HTML:

```html
<p><span data-bind:text="name">Customer</span> has been with us for <span data-bind:text="yearsActive">0</span> years.</p>
```

Here we can expose exactly the value the template needs without teaching the template how to calculate it.

## `#[BindGetter]` for inferred names

If the method is already shaped like a getter, we can skip the explicit key name.

```php
use GT\DomTemplate\BindGetter;

readonly class Country {
	public function __construct(
		public string $code,
	) {}

	#[BindGetter]
	public function getName():string {
		return match($this->code) {
			"GB" => "United Kingdom",
			"JP" => "Japan",
			default => "Unknown",
		};
	}
}
```

`getName()` becomes the bind key `name` when using the `BindGetter` attribute.

For example:

- `getName()` -> `name`
- `getTotalCost()` -> `totalCost`
- `getFormattedDate()` -> `formattedDate`

## Nested object keys

Objects can reference other bindable objects, and DomTemplate can follow that chain with dot notation.

```php
readonly class Address {
	public function __construct(
		public string $street,
		public Country $country,
	) {}
}

readonly class Customer {
	public function __construct(
		public string $name,
		public Address $address,
	) {}
}
```

HTML:

```html
<h1 data-bind:text="name">Customer</h1>
<p data-bind:text="address.street">Street</p>
<p data-bind:text="address.country.name">Country</p>
```

If we bind a `Customer`, DomTemplate walks through the nested objects and resolves the final value.

> [!NOTE]
> Remember, all of these practices apply when binding lists of objects too. Each `data-list` element can have bind properties referencing object properties within the current iteration.

## Iterable objects

An object can also be made to represent a list.

If the object is iterable, `bindData($object)` can do two jobs in one go:

- bind the object's own key/value data
- bind list templates from the object as an iterable

This is useful for things like a `CalendarDay` object that has properties such as `dateString`, but also yields `CalendarEvent` objects.

## `asArray()`

If an object defines an `asArray()` method, DomTemplate will use that as a key/value representation before looking any deeper.

That gives us a predictable override when we want to control exactly how an object is flattened for the template.

## A practical rule of thumb

- use public properties when the object is already a tidy view model
- use `#[Bind]` for computed values with custom names
- use `#[BindGetter]` for ordinary getter-style methods
- use nested objects when the page naturally follows the domain structure

---

Objects and lists often overlap, but tables have their own rules. Read about it in the [[binding tables]] section.


Tables are a special case because the HTML structure itself carries meaning: headings define columns, rows define records, and sometimes cells already contain their own markup.

DomTemplate's table binder supports a few different shapes so we can choose the level of control we need.

## 1. Binding to an empty table

HTML:

```html
<table data-bind:table="weather"></table>
```

PHP:

```php
$binder->bindTable([
	["Day", "Weather"],
	["Mon", "Rain"],
	["Tue", "Cloud"],
	["Wed", "Sunny"],
], bindKey: "weather");
```

If we do this, DomTemplate creates the `<thead>`, `<tbody>`, rows, and cells for us.

Output HTML:

```html
<table>
	<thead>
		<tr>
			<th>Day</th>
			<th>Weather</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>Mon</td>
			<td>Rain</td>
		</tr>
		<tr>
			<td>Tue</td>
			<td>Cloud</td>
		</tr>
		<tr>
			<td>Mon</td>
			<td>Sunny</td>
		</tr>
	</tbody>
</table>
```

## 2. Using column-oriented data

The same table can also be expressed with headings as keys:

```php
$binder->bindTable([
	"Day" => ["Mon", "Tue", "Wed"],
	"Weather" => ["Rain", "Cloud", "Sunny"],
], bindKey: "weather");
```

This is often a natural fit when data already arrives from another layer grouped by column.

## 3. Binding to a table with existing headings

HTML:

```html
<table data-bind:table>
	<thead>
		<tr>
			<th>Name</th>
			<th>Email</th>
		</tr>
	</thead>
</table>
```

If a table already has a `<thead>`, those heading cells define which columns are shown and in what order.

That means we can safely bind a wider data set and only expose the columns we actually want in the view.

## 4. `data-table-key`

Similarly to above, the table's existing headers can be used to define which columns are shown, but the heading's text is not the same as the data's key.

HTML:

```html
<th data-table-key="firstName">First name</th>
<th data-table-key="email">Email address</th>
```

This lets us keep friendly UI copy while still mapping the correct data fields.

## 5. Binding to existing row markup

For more complex tables, we can define the row markup ourselves and let DomTemplate clone it.

HTML:

```html
<table>
	<thead>
		<tr>
			<th>Delete</th>
			<th data-table-key="id">ID</th>
			<th data-table-key="name">Name</th>
			<th>Flag</th>
		</tr>
	</thead>
	<tbody>
		<tr data-list>
			<td>
				<form method="post">
					<input type="hidden" name="id" data-bind:value="@" />
					<button name="do" value="delete">Delete</button>
				</form>
			</td>
			<td></td>
			<td></td>
			<td>
				<form method="post">
					<input type="hidden" name="id" data-bind:value="@name" />
					<button name="do" value="flag">Flag</button>
				</form>
			</td>
		</tr>
	</tbody>
</table>
```

Note that the `tr` has the `data-list` attribute, indicating that it is the `tr` within the `tbody` that we want to repeat for each record. Here we can see table binding and ordinary element binding working together. The data fills the ID and name cells, but the surrounding forms remain in place.

## 6. Double-header tables

DomTemplate also supports what the tests call a "double header" structure: one heading row across the top, and another heading value at the start of each body row.

PHP:

```php
$binder->bindTable([
	["Item", "Price", "Stock"],
	[
		"Washing machine" => ["698.00", "24"],
		"Television" => ["998.00", "7"],
		"Laptop" => ["799.99", "60"],
	],
]);
```

In this shape:

- the first inner array is the top heading row
- each subsequent associative row uses its key as a body `<th>`
- the remaining values become body `<td>` cells

That is useful when the left-most column is itself a row heading rather than ordinary cell data.

## Supported input shapes

The public `bindTable()` method accepts any iterable that can be normalised into one of these shapes:

- row-oriented arrays where the first row contains headings
- associative row lists
- heading => value-list maps
- double-header data
- traversable equivalents

If the structure is not compatible, DomTemplate throws `IncorrectTableDataFormat`.

## Bind key matching

If multiple tables exist in the same document, give them explicit bind keys:

```html
<table data-bind:table="sales"></table>
<table data-bind:table="returns"></table>
```

```php
$binder->bindTable($salesTable, bindKey: "sales");
$binder->bindTable($returnsTable, bindKey: "returns");
```

The bind key can also live on an ancestor wrapper instead of the table itself.

---

We have now covered the three major data shapes. Next, move on to [[conditional and optional elements]] to tidy up the output and deal with parts of the page that may disappear completely.


When using the plain HTML to structure your pages, the default state and the optional state are both stored in a single place.

This page describes how state can be managed within the HTML itself by explaining the following concepts:

- placeholders with defaults
- `data-element`
- `cleanupDocument()`

## Placeholders with defaults

We have already seen basic placeholders:

```html
<a href="/profile/{{username}}">Go to profile</a>
```

DomTemplate also supports defaults:

```html
<a href="/profile/{{username ?? me}}">Go to profile</a>
```

If `username` is `null` or an empty string, the fallback text is used instead.

This is handy when the default state should still work naturally before any data is bound.

## `data-element`

`data-element` marks an element as optional.

If the element is never bound, and we later call `cleanupDocument()`, the element is removed from the final output.

### Example: optional error messages

HTML:

```html
<form method="post">
	<div data-element data-bind:text="error">Something went wrong.</div>
	<input name="email" />
	<button>Save</button>
</form>
```

PHP:

```php
try {
	$database->saveForm(); // just as an example of doing some work.
}
catch(Throwable $exception) {
	$binder->bindKeyValue("error", $exception->getMessage());
}

$binder->cleanupDocument();
```

If there is no error, the `<div>` disappears completely. If there is an error, the element stays and shows the message.

## `data-element="someKey"`

Sometimes we want to toggle an element's presence even though there is no separate `data-bind:*` attribute on it.

HTML:

```html
<p data-element="isAdmin">You are an administrator.</p>
<button data-element="isAdmin" name="do" value="delete">Delete record</button>
```

PHP:

```php
$binder->bindKeyValue("isAdmin", $user->isAdmin());
$binder->cleanupDocument();
```

Only truthy values keep those elements in the document.

## `cleanupDocument()`

`cleanupDocument()` is the final tidy-up step.

It does three main things:

- removes `data-bind`, `data-list`, `data-template`, `data-table-key`, and `data-element` attributes
- removes internal `data-bound` markers
- removes optional elements that never became bound

That means we can keep the source HTML expressive without leaking framework markup into the final response.

## When to call cleanup

Call `cleanupDocument()` after all binding is finished.

That includes:

- scalar binds
- list binds
- table binds
- component-scoped binds
- partial variable binds

If we call it too early, later binding operations will have fewer markers to work with.

> [!NOTE]
> There's no need to call `cleanupDocument` in WebEngine applications as this is handled automatically for you.

## A good workflow

In most plain PHP usage, the recommended order of execution is:

1. expand partials
2. expand components
3. bind data
4. call `cleanupDocument()`
5. echo the document

---

This covers all the binding operations. Next, move on to [[HTML components]] so we can split larger HTML structures into reusable files.


Components let us keep a chunk of HTML in its own file and pull it into the page using a custom element such as `<profile-summary>`.

This is particularly helpful when a section of UI becomes awkward to maintain inline, or when the same structure appears on several pages.

## A first component

Page HTML:

```html
<h2>Account details</h2>
<profile-summary />
```

Component file:

`_component/profile-summary.html`

```html
<dl>
	<dt>Name</dt>
	<dd data-bind:text="name">Guest</dd>

	<dt>Email</dt>
	<dd data-bind:text="email">guest@example.com</dd>
</dl>
```

PHP:

```php
use GT\DomTemplate\ComponentExpander;
use GT\DomTemplate\PartialContent;

$expander = new ComponentExpander(
	$document,
	new PartialContent(__DIR__ . "/_component"),
);

$expandedComponents = $expander->expand();
```

If we do this, the `<profile-summary>` element stays in the document, but its inner HTML is replaced with the component file contents.

## Component names

[The W3C have decided][w3c-custom-elements] that custom component names **must contain a hyphen**.

Good examples:

- `<profile-summary>`
- `<calendar-control>`
- `<shop-item-card>`

This keeps custom elements distinct from native HTML elements.

## Components in subdirectories

The `src` attribute lets us load from a subdirectory.

Page HTML:

```html
<date-picker src="calendar" />
<date-picker src="christmas" />
```

Component files:

- `_component/calendar/date-picker.html`
- `_component/christmas/date-picker.html`

That gives us a tidy way to organise larger component libraries without inventing a separate naming system.

## Recursive components

Components can contain other components.

So if `profile-summary.html` itself contains `<avatar-image />`, DomTemplate will keep expanding until there are no more matching component files.

This makes it practical to build layered interfaces from smaller pieces.

## `ComponentBinder`

Once a component has been expanded, we often want to bind data only within that one component, and not leak data binding out to the rest of the document. That is what `ComponentBinder` is for.

```php
use GT\DomTemplate\ComponentBinder;

$componentElement = $document->querySelector("profile-summary");
$componentBinder = new ComponentBinder($document);
$componentBinder->setDependencies(
	$elementBinder,
	$placeholderBinder,
	$tableBinder,
	$listBinder,
	$listElementCollection,
	$bindableCache,
);
$componentBinder->setComponentBinderDependencies($componentElement);

$componentBinder->bindData([
	"name" => "Ada",
	"email" => "ada@example.com",
]);
```

The API is intentionally the same as `DocumentBinder`, but the scope is locked to one component subtree.

> [!NOTE]
> In WebEngine applications, you can use the `Binder` helper class, which will be automatically instantiated as a `DocumentBinder` when in page context, and `ComponentBinder` when in component context. 

## Selector contexts inside a component

`ComponentBinder` also accepts selector string contexts:

```php
$componentBinder->bindKeyValue("title", "Orders", ".heading");
```

If the selector does not match inside the component, it throws `ContextElementNotFoundException`.

## Hidden `__component` fields in POST forms

When a component contains a `<form method="post">`, DomTemplate automatically prepends a hidden input named `__component` with the component tag name.

That gives server-side code a tidy way to tell which component submitted the form, and makes custom routing easier.

---

Components handle reusable fragments of HTML, but [[Partials]] are used for whole-page templates.

[w3c-custom-elements]: https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements


Partials let us build page templates in plain HTML using INI syntax at the top of the file.

The everyday use case is straightforward: one page contains its own content, and a comment at the top says which base template it extends.

## A simple partial extension

Page HTML:

```html
<!--
extends=base-page
-->

<h2>Welcome</h2>
<p>This page body will be injected into the template.</p>
```

Base template:

`_partial/base-page.html`

```html
<!doctype html>
<html>
<head>
	<title>My site</title>
</head>
<body>
	<header>
		<h1>My site</h1>
	</header>

	<main data-partial></main>
</body>
</html>
```

PHP:

```php
use GT\DomTemplate\PartialContent;
use GT\DomTemplate\PartialExpander;

$partialExpander = new PartialExpander(
	$document,
	new PartialContent(__DIR__ . "/_partial"),
);

$partialExpander->expand();
```

If we do this, the page's body content is moved into the template's `data-partial` element.

> [!NOTE]
> WebEngine applications automatically expand any partial content added to pages so the only thing you need to do in WebEngine is place the HTML files in the correct directory. All PHP is automated for you.

## Template variables with `[vars]`

The opening comment can also contain a `[vars]` section.

Page HTML:

```html
<!--
extends=base-page

[vars]
title=Orders
heading=Order history
-->

<p>Your recent orders are shown below.</p>
```

Base template:

```html
<!doctype html>
<html>
<head>
	<title>{{title ?? Home}}</title>
</head>
<body>
	<h1 data-bind:text="heading">Default heading</h1>
	<main data-partial></main>
</body>
</html>
```

If we pass a `DocumentBinder` into `expand()`, those variables are bound automatically:

```php
$partialExpander->expand(binder: $binder);
```

## Recursive partials

Partials can extend other partials.

That means we can have:

- a page extending a section layout
- that section layout extending a global site layout

DomTemplate expands that chain from the inside out until the final page is assembled.

## Rules for the opening comment

The comment is parsed as INI syntax.

That means:

- it must be the leading meaningful node in the document
- `extends` names the partial file to load
- `[vars]` provides simple string variables for binding

If the comment is in the wrong place, DomTemplate throws `CommentIniInvalidDocumentLocationException`.

## Injection point rules

The target partial must contain exactly one element marked with `data-partial`.

- If there's no `data-partial` element -> `PartialInjectionPointNotFoundException`
- If there's more than one `data-partial` element -> `PartialInjectionMultiplePointException`

That keeps the template structure explicit and avoids guesswork.

## Partial file lookup

`PartialContent` resolves partial files from the directory we gave it:

```php
$partialContent = new PartialContent(__DIR__ . "/_partial");
```

Then:

- `extends=base-page` -> `_partial/base-page.html`

The same `PartialContent` helper is also used by components.

---

The page composition story is now complete. Next, move on to [[debugging]] so we can see how to inspect where binds came from.


DomTemplate is small, but when a larger page has many binds it is still helpful to know where a given value came from.

That is where `data-bind-debug` comes in.

## Enable bind debugging in the HTML

Add `data-bind-debug` to a scope element:

```html
<section data-bind-debug>
	<h1 data-bind:text="name">Guest</h1>
	<p><a data-bind:href="emailLink" data-bind:text="email">guest@example.com</a></p>
</section>
```

Now when a bind happens within that scope, DomTemplate records the source file and line number on the affected elements.

## What the output looks like

After binding, an element might end up with:

```html
<h1 data-bind-debug="text=app/Controller.php:10">Cody</h1>
```

Or for multiple properties:

```html
<a data-bind-debug="text=app/Controller.php:10,href=app/Controller.php:10" href="mailto:cody@example.com">cody@example.com</a>
```

This makes it much easier to answer the question, "which bind call wrote this?"

## Scope behaviour

Only elements inside a `data-bind-debug` scope collect debug entries.

That means we can add it to a single section of the page while leaving the rest untouched, or even just add the debug attribute to the single element we want to inspect.

## Cleanup behaviour

`cleanupDocument()` removes an empty `data-bind-debug` marker from scope elements, but it keeps populated debug attributes on elements that actually recorded bind information, so we get useful debug output without leaking empty marker attributes.

## Tables and lists

Debug information also works with generated content such as:

- list items produced by `bindList`
- table cells produced by `bindTable`

That is particularly handy when the final nodes did not even exist in the original HTML.

## Selector context errors

Another useful debugging improvement is selector-based bind contexts.

If we write:

```php
$binder->bindKeyValue("name", "Cody", "#missing");
```

and the selector does not match, DomTemplate throws `ContextElementNotFoundException` instead of a low-level type error.

That usually gives us a much faster route to the actual mistake in the template or controller code.

---

This is the end of the guide. Read the [[API reference]] for the method and exception cheat sheet.


This page is a compact reference for the public API of the library.

For walkthroughs and examples, use the earlier pages in the guide.

## Main binding methods

### `DocumentBinder`

- `bindValue(mixed $value, null|string|Element $context = null): void`
- `bindKeyValue(string $key, mixed $value, null|string|Element $context = null): void`
- `bindData(mixed $kvp, null|string|Element $context = null): void`
- `bindTable(mixed $tableData, null|string|Element $context = null, ?string $bindKey = null): void`
- `bindList(iterable $listData, null|string|Element $context = null, ?string $templateName = null): int`
- `bindListCallback(iterable $listData, callable $callback, null|string|Element $context = null, ?string $templateName = null): int`
- `cleanupDocument(): void`

### `ComponentBinder`

`ComponentBinder` exposes the same binding methods as `DocumentBinder`, but confines all binding to one expanded component element.

## Context arguments

Most binding methods accept:

- `null` for the whole document or whole component
- an `Element` instance
- a selector `string`

If the selector string does not match, DomTemplate throws `ContextElementNotFoundException`.

## Data shapes

### Values

Suitable for `bindValue` and `bindKeyValue`:

- strings
- integers
- floats
- booleans
- `Stringable` objects
- callables returning a bindable value

### Key/value data

Suitable for `bindData`:

- associative arrays
- objects with public properties
- objects with `#[Bind]` or `#[BindGetter]`
- objects with `asArray()`

### Lists

Suitable for `bindList` and `bindListCallback`:

- arrays
- `Iterator`
- `IteratorAggregate`
- `ArrayIterator`
- iterable objects

### Tables

Suitable for `bindTable`:

- row-oriented arrays with a heading row
- associative row lists
- heading => value-list maps
- double-header structures
- traversable equivalents

## Composition helpers

- `ComponentExpander::expand(?Element $context = null): array`
- `PartialExpander::expand(?Element $context = null, ?DocumentBinder $binder = null): array`
- `PartialContent::getContent(string $name, string $extension = "html", ?string $src = null): string`
- `PartialContent::getHTMLDocument(string $name): HTMLDocument`

## Key HTML attributes

- `data-bind:*`
- `data-list`
- `data-template`
- `data-bind:list`
- `data-bind:table`
- `data-table-key`
- `data-rebind`
- `data-element`
- `data-bind-debug`
- `data-list-keep-template`
- `data-partial`

## Common exceptions

- `ContextElementNotFoundException`
- `IncompatibleBindDataException`
- `InvalidBindPropertyException`
- `ListElementNotFoundInContextException`
- `IncorrectTableDataFormat`
- `TableElementNotFoundInContextException`
- `ComponentDoesNotContainContextException`
- `PartialContentDirectoryNotFoundException`
- `PartialContentFileNotFoundException`
- `PartialInjectionPointNotFoundException`
- `PartialInjectionMultiplePointException`
- `CommentIniInvalidDocumentLocationException`
- `CyclicRecursionException`

---

That is the end of the main guide. If you want to jump back into the walkthrough flow, return to [[Home]].




---

# Documentation: DomValidation

`phpgt/domvalidation` lets us reuse the validation rules that are already present in our browser's HTML forms and enforce them on the server.

Built on top of [PHP.GT/Dom](https://php.gt/dom), this library provides server side HTML form validation of user input. It automatically enforces validation rules defined by web standards, such as required inputs, allowed input ranges, and valid select options, but can be extended to validate custom rules such as password complexity.

Many form validation rules are enforced by the browser on the client side, providing a rich user experience across devices, but these rules can be maliciously bypassed and have to be duplicated on the server - but having a DOM document available on the server means the validation rules you've already added to your HTML forms can be enforced automatically without having to replicate any validation logic.

If an `<input>` is marked `required`, or has `type="email"`, or a `<select>` only contains certain options, the browser can already use that information on the client side. DomValidation brings the same idea to PHP by checking submitted data against the actual form element in a server-side `HTMLDocument`.

That means we do not need to maintain one set of validation rules in HTML and another hand-written version somewhere else in our PHP.

> [!NOTE]
> DomValidation is automatically included in WebEngine applications. The framework already works with server-side HTML documents, and the validation object is available to you pre-constructed via the ServiceLoader.

## A small example

```html
<form id="signup" method="post">
	<label>
		<span>Email address</span>
		<input name="email" type="email" required />
	</label>

	<label>
		<span>Password</span>
		<input name="password" type="password" minlength="12" required />
	</label>

	<button name="do" value="register">Create account</button>
</form>
```

```php
use GT\Dom\HTMLDocument;
use GT\DomValidation\ValidationException;
use GT\DomValidation\Validator;

$document = new HTMLDocument($html);
$form = $document->querySelector("#signup");
$validator = new Validator();

try {
	$validator->validate($form, $_POST);
}
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$input = $form->querySelector("[name='$name']");
		$input?->parentElement?->dataset->validationError = $message;
	}
}
```

In that example, the validator reads the rules from the HTML itself. If the email address is malformed, or the password is too short, or either field is empty, the error list contains the matching messages for us.

---

To see the simplest end-to-end flow first, start with the [[Quick start guide]].


In this guide we will validate one simple form, stop invalid data on the server, and add an error message back into the document.

The aim is not to cover every feature yet. It is to get the full request/validate/respond loop working first.

## 1. Install the package

```bash
composer require phpgt/domvalidation
```

## 2. Mark up the form with normal HTML validation attributes

```html
<form id="signup" method="post">
	<label>
		<span>Email address</span>
		<input name="email" type="email" required />
	</label>

	<label>
		<span>Password</span>
		<input name="password" type="password" minlength="12" required />
	</label>

	<button name="do" value="register">Create account</button>
</form>
```

At this point the browser already knows some useful things:

- the email must look like an email address
- both fields are required
- the password must be at least twelve characters long

DomValidation will reuse those same rules on the server.

## 3. Create the validator and run it

```php
use GT\Dom\HTMLDocument;
use GT\DomValidation\ValidationException;
use GT\DomValidation\Validator;

$document = new HTMLDocument($html);
$form = $document->querySelector("#signup");
$validator = new Validator();

try {
	$validator->validate($form, $_POST);
}
catch(ValidationException) {
	// We will display the errors in the next step.
}

echo $document; // display the page to the browser, unchanged, or with errors appended.
```

If all submitted values are valid, `validate()` returns normally. If any field is invalid, it throws `ValidationException`.

## 4. Add the errors back into the document

```php
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$field = $form->querySelector("[name='$name']");
		$field?->parentElement?->dataset->validationError = $message;
	}
}
```

Now the relevant label elements have a `data-validation-error` attribute. We can show that with CSS:

```css
label[data-validation-error]::before {
	content: attr(data-validation-error);
	display: block;
	color: crimson;
	font-weight: bold;
}
```

## 5. Return early when validation fails

This keeps invalid input out of the rest of the application logic.

```php
try {
	$validator->validate($form, $_POST);
}
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$field = $form->querySelector("[name='$name']");
		$field?->parentElement?->dataset->validationError = $message;
	}

	echo $document;
	return;
}

// Continue with valid input only.
```

## 6. Form complete

At this point:

- the browser still handles client-side validation as usual
- the server re-checks the same form constraints
- the error messages come back from the validator already matched to field names
- invalid data stops before it reaches the rest of the application

> [!NOTE]
> In WebEngine, this same pattern usually sits inside a `do_*()` function. The framework already provides the current `HTMLDocument` and request input object, so the main job is just to find the form and call `validate()`.

---

From here, read the [[Default validation rules]] so we know exactly which built-in constraints are currently supported.


DomValidation ships with a default set of rules that are based on common HTML form constraints.

This is an important point: the library does **not** try to implement every possible piece of browser form validation. It implements a practical subset that maps cleanly onto the current codebase.

If we need more than that, we can extend the library with our own rules, which we will cover later in [[Extending custom rules]].

## Required fields

- `required`

If a field marked `required` is empty, validation fails.

The exact message depends on the kind of control:

- ordinary inputs: `This field is required`
- required `<select>` elements: `Please select an item in the list`
- required radio groups: `Please select one of these options`

Example:

```html
<label>
	<span>Your name</span>
	<input name="name" required />
</label>
```

## Text length

- `minlength`
- `maxlength`

These rules apply to the number of characters in a submitted value.

Example:

```html
<label>
	<span>New password</span>
	<input name="password" type="password" minlength="12" maxlength="128" />
</label>
```

If the value is too short, the hint is:

```text
This field's value must contain at least 12 characters
```

If the value is too long, the hint is:

```text
This field's value must contain 128 characters or less
```

## Pattern matching

- `pattern`

The `pattern` attribute is compiled as a regular expression with the `u` flag, so it is treated as Unicode-aware.

Example:

```html
<label>
	<span>Username</span>
	<input name="username" pattern="\w{3,16}" />
</label>
```

If the pattern does not match, the default hint is:

```text
This field does not match the required pattern
```

If the element also has a `title` attribute, that text is appended to the hint. This is a good way to explain the rule in human language:

```html
<input
	name="pin"
	type="password"
	pattern="\d{4}"
	title="Use exactly four digits"
/>
```

Resulting hint:

```text
This field does not match the required pattern: Use exactly four digits
```

## Input types

The following `type` values are validated by the built-in rules:

- `email`
- `url`
- `date`
- `month`
- `week`
- `time`
- `datetime-local`
- `number`
- `range`

### Email and URL

`email` and `url` are validated using PHP's filter functions.

```html
<input name="email" type="email" />
<input name="website" type="url" />
```

### Date and time formats

These types are validated against specific formats:

Input type | Expected format | Example
-- | -- | --
`date` | `Y-m-d` | `2026-05-07`
`month` | `Y-m` | `2026-05`
`week` | `Y-\WW` | `2026-W19`
`time` | `H:i` | `14:30`
`datetime-local` | `Y-m-d\TH:i` | `2026-05-07T14:30`

For `week`, the week number must currently be between `1` and `52`.

### Number and range

`number` and `range` support:

- numeric value checking
- `min`
- `max`
- `step`

Example:

```html
<input name="amount" type="number" min="0" max="100" step="5" />
```

If the value is not numeric, the hint is:

```text
Field must be a number
```

If it is outside the allowed range, the hint explains whether it is too low or too high. If the step is wrong, the hint explains whether the value should be a multiple of the step or a value offset from `min`.

## Available option checking

DomValidation also validates whether submitted values actually exist in the form markup for three common cases.

### `<select>`

For `<select>` elements, submitted values must match one of the available option values.

```html
<select name="currency" required>
	<option></option>
	<option value="GBP">Pound sterling</option>
	<option value="EUR">Euro</option>
</select>
```

### Radio groups

For radio inputs, the submitted value must match one of the radio buttons in the same form with the same `name`.

```html
<input type="radio" name="sort" value="asc" />
<input type="radio" name="sort" value="desc" />
```

### Checkbox groups

For checkbox groups, every submitted value must match one of the available checkboxes.

```html
<input type="checkbox" name="interest[]" value="php" />
<input type="checkbox" name="interest[]" value="css" />
<input type="checkbox" name="interest[]" value="sql" />
```

If a submitted value is not one of the available choices, the hint is:

```text
This field's value must match one of the available options
```

## What is not covered by default

A few examples of things that are **not** separate built-in rules in the current library:

- `type="tel"` format validation
- `type="color"` validation
- browser-specific constraint validation behaviour outside the implemented rules
- cross-field rules such as "confirm password must match password"
- domain-specific rules such as username uniqueness

Those are exactly the kinds of things custom rules are for. If you want to request that a rule becomes part of the standard set, please [raise an issue on GitHub](https://github.com/phpgt/DomValidation/issues).

---

Next, move on to [[Enforcing validation on user input]] to see how these rules are triggered in PHP.


Client-side validation in the browser is useful, but it is not enough on its own. Requests can be replayed, forged, edited, or submitted from code that never touched the browser at all.

DomValidation is the server-side step: we pass it the form element and the submitted data, and it checks the input against the rules declared in the HTML.

## The basic flow

1. Get a reference to the `<form>` element in a server-side `HTMLDocument`.
2. Create a `Validator`.
3. Call `validate($form, $input)`.
4. Catch `ValidationException` if anything is invalid.
5. Read the error messages from `getLastErrorList()`.

## Minimal example

```php
use GT\Dom\HTMLDocument;
use GT\DomValidation\ValidationException;
use GT\DomValidation\Validator;

// In this example, $input is a key-value-pair of values from the POST data.
function handleSubmit(HTMLDocument $document, array $input):void {
	$form = $document->querySelector("#example-form");
	$validator = new Validator();

	try {
		$validator->validate($form, $input);
	}
	catch(ValidationException) {
		foreach($validator->getLastErrorList() as $name => $message) {
			$field = $form->querySelector("[name='$name']");
			$field?->parentElement?->dataset->validationError = $message;
		}

		return;
	}

	// Carry on processing the valid input here.
}
```

## What `validate()` expects

The `Validator::validate()` method takes two arguments:

### 1. The form element

The first argument must be the form element we want to validate against.

```php
$form = $document->forms[0];
```

Use the actual form element, because the library reads the rule definitions from the current DOM:

- attributes such as `required`, `pattern`, `type`, `min`, `max`, and `step`
- `<option>` values in a `<select>`
- available values in radio and checkbox groups

### 2. The submitted input

The second argument may be:

- an associative array
- any iterable object
- an object with public properties
- an object that provides an `asArray()` method

That makes the validator easy to use with plain `$_POST`, with PHP.GT/Input, and with other request wrappers.

There is more detail on accepted input shapes in [[Working with input data]].

## What happens on failure

If one or more fields are invalid, `validate()` throws a `ValidationException`.

The exception message is intentionally broad:

- `There is 1 invalid field`
- `There are 2 invalid fields`

The useful detail lives in the validator's `ErrorList`, which is available immediately afterwards through:

```php
$validator->getLastErrorList()
```

That object can be iterated like this:

```php
foreach($validator->getLastErrorList() as $name => $message) {
	// ...
}
```

The key is the form field's `name`. The value is the combined human-readable hint for that field.

## Plain PHP example

```php
use GT\Dom\HTMLDocument;
use GT\DomValidation\ValidationException;
use GT\DomValidation\Validator;

$document = new HTMLDocument(file_get_contents("payment-form.html"));

if(($_POST["do"] ?? "") === "buy") {
	$form = $document->querySelector("#payment-form");
	$validator = new Validator();

	try {
		$validator->validate($form, $_POST);
		echo "Payment succeeded!";
		exit;
	}
	catch(ValidationException) {
		foreach($validator->getLastErrorList() as $name => $message) {
			$field = $form->querySelector("[name='$name']");
			$field?->parentElement?->dataset->validationError = $message;
		}
	}
}

echo $document;
```

## WebEngine example

> [!NOTE]
> In WebEngine, the current `HTMLDocument` and the request `Input` object are already part of the usual page-logic workflow, which makes DomValidation a natural fit.

```php
use GT\Dom\HTMLDocument;
use GT\DomValidation\ValidationException;
use GT\DomValidation\Validator;
use GT\Input\Input;

function do_submit(
	HTMLDocument $document,
	Input $input,
):void {
	$form = $document->querySelector("#example-form");
	$validator = new Validator();

	try {
		$validator->validate($form, $input);
	}
	catch(ValidationException) {
		foreach($validator->getLastErrorList() as $name => $message) {
			$field = $form->querySelector("[name='$name']");
			$field?->parentElement?->dataset->validationError = $message;
		}

		return;
	}

	// Continue with the valid submission.
}
```

## A practical habit

Once validation fails, return early.

That keeps the code simple and avoids accidentally continuing with invalid data.

```php
catch(ValidationException) {
	// display errors...
	return;
}
```

---

Once the basic flow is clear, continue with [[Working with input data]] to see how field names and submitted values are matched.


The validator does not require one special request object. Instead, it accepts several useful input shapes and normalises them into a simple key/value structure internally.

That makes it easy to use with plain PHP, with PHP.GT/Input, and with custom request wrappers.

## Accepted input types

`Validator::validate()` accepts:

- associative arrays
- iterable objects
- ordinary objects with public properties
- objects that implement an `asArray()` method

In practice, all of these are valid:

```php
$validator->validate($form, $_POST);
```

```php
$validator->validate($form, $input);
```

```php
$validator->validate($form, (object)[
	"email" => "dev@example.com",
	"name" => "Ada Lovelace"
]);
```

## Using PHP.GT/Input

If the application uses `GT\Input\Input`, we can pass it directly:

```php
use GT\Input\Input;

function do_submit(Input $input):void {
	$validator->validate($form, $input);
}
```

That works because the validator can consume iterable objects and objects that expose array-like request data.

## Field names must match form names

The validator matches submitted values to inputs by the `name` attribute.

```html
<input name="email" type="email" required />
```

```php
$validator->validate($form, [
	"email" => "dev@example.com",
]);
```

If the field name and the submitted key do not match, the validator will treat the field as empty or missing.

## Checkbox names with `[]`

Checkbox groups are commonly named like this:

```html
<input type="checkbox" name="interest[]" value="php" />
<input type="checkbox" name="interest[]" value="css" />
```

The submitted PHP data is usually:

```php
[
	"interest" => ["php", "css"],
]
```

DomValidation normalises the `name` attribute by stripping the trailing `[]` when looking up the submitted input, so this works naturally.

That means:

- DOM name: `interest[]`
- submitted key: `interest`

## Multiple values

If the submitted value is an array, the validator converts each entry to a string internally.

That is mainly useful for checkbox groups and other repeated field names.

## Object input

If an object is passed in, the validator checks it in this order:

1. if it has an `asArray()` method, that is used
2. if it is traversable, it is converted with `iterator_to_array()`
3. otherwise its public properties are read

Non-scalar object properties are treated as empty strings.

This allows simple request DTOs to work without extra mapping glue.

## A practical rule

Keep the submitted structure close to what the HTML form actually emits.

That way:

- required checks behave as expected
- checkbox arrays stay grouped correctly
- custom rules that inspect other fields are easier to write

---

Once the input is accepted and validation fails, the next useful topic is [[Understanding validation errors]].


DomValidation deliberately does **not** prescribe one fixed way to render errors.

Forms vary a lot between projects: sometimes the error belongs inside a `<label>`, sometimes after a `<fieldset>`, sometimes in a summary list at the top of the page.

The library's job is to tell us:

- which fields are invalid
- what message should be shown

Our job is to decide how that should appear in the document.

## Reading the error list

After catching a `ValidationException`, iterate over the validator's last error list:

```php
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		// ...
	}
}
```

For each item:

- `$name` is the field name
- `$message` is the user-facing hint text

## Pattern 1: add a data attribute and let CSS show the message

This is often the lightest approach because it keeps the HTML structure intact.

```php
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$field = $form->querySelector("[name='$name']");
		$field?->parentElement?->dataset->validationError = $message;
	}
}
```

```css
label[data-validation-error]::before {
	content: attr(data-validation-error);
	display: block;
	color: crimson;
	font-weight: bold;
	margin-bottom: 0.25rem;
}
```

This works well when each input sits neatly inside its own label or wrapper element.

## Pattern 2: insert an element into the document

If we would rather produce a real element, we can do that too:

```php
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$field = $form->querySelector("[name='$name']");
		if(!$field) {
			continue;
		}

		$error = $document->createElement("span");
		$error->classList->add("error-message");
		$error->textContent = $message;

		$field->before($error);
	}
}
```

This gives us more freedom if we want icons, ARIA attributes, or a stricter layout structure.

## Pattern 3: build a summary list as well as field-level messages

Some forms benefit from both local messages and a top-level summary.

```php
$summary = $document->createElement("ul");
$summary->classList->add("validation-summary");

foreach($validator->getLastErrorList() as $name => $message) {
	$item = $document->createElement("li");
	$item->textContent = "$name: $message";
	$summary->appendChild($item);
}

$form->prepend($summary);
```

This is especially useful for longer forms where the first invalid field may not be visible immediately.

## When one field has more than one problem

The `ErrorList` combines multiple messages for the same field into one string, separated by `; `.

For example, a required password field with a minimum length might produce:

```text
This field is required; This field's value must contain at least 12 characters
```

That means we can treat each iteration item as the full message to show for that field.

## Matching the right element

The simplest lookup is:

```php
$field = $form->querySelector("[name='$name']");
```

That works well for normal inputs and selects. For checkbox groups, remember that the DOM element name may include `[]`, while the submitted input key may not. In practice, it is often easiest to attach the message to the surrounding fieldset or container for the group rather than to one checkbox in isolation.

## Keep the user on the same path

The best validation messages help the user continue without confusion:

- put the message close to the field when possible
- keep the wording plain and direct
- avoid showing the same message in too many places
- return early after adding the errors so invalid data is not processed

---

For the shape of the error data itself, continue with [[Understanding validation errors]].


When validation fails, there are two layers of information:

1. the thrown exception
2. the validator's `ErrorList`

The exception tells us that validation failed. The `ErrorList` tells us which fields failed and what message to show.

## The thrown exception

`Validator::validate()` throws a `ValidationException` when one or more fields are invalid.

The message is intentionally broad:

- `There is 1 invalid field`
- `There are 2 invalid fields`

That message is useful for logging or for a general summary, but not for field-by-field display.

## The `ErrorList`

The detailed information is available through:

```php
$validator->getLastErrorList()
```

The returned object is iterable and countable.

```php
catch(ValidationException) {
	$errorList = $validator->getLastErrorList();

	foreach($errorList as $name => $message) {
		// ...
	}
}
```

## Keys and values of `getLastErrorList()`

During iteration:

- the key is the field name
- the value is the message to show for that field

Example:

```php
foreach($validator->getLastErrorList() as $name => $message) {
	echo "$name => $message\n";
}
```

Possible output:

```text
password => This field is required; This field's value must contain at least 12 characters
```

## Multiple problems on one field

One field may fail more than one rule.

For example:

```html
<input name="password" minlength="12" required />
```

If the submitted value is empty, both rules fail:

- `required`
- `minlength`

The `ErrorList` combines those messages into one string using `; ` as a separator.

That means the library gives us **one display message per field**, even if several rules contributed to it.

## Specific exception classes

Internally, the library also tracks more specific exception classes such as:

- `ValueMissingException`
- `PatternMismatchException`
- `TypeMismatchException`
- `RangeUnderflowException`
- `RangeOverflowException`
- `StepMismatchException`
- `BadInputException`

If every invalid field belongs to the same category, the validator throws that specific exception class.

If the invalid fields belong to mixed categories, it throws the broader `ValidityStateException`.

For most applications, the field-level messages are the part we act on most often. The exception type becomes useful when a higher-level handler needs to distinguish one family of validation problems from another.

## Counting invalid fields

The `ErrorList` count is the number of invalid **fields**, not the number of individual failed rules.

So if one field fails both `required` and `minlength`, it still counts as one invalid field.

## A practical pattern

Use the exception to branch the control flow, and use the error list to render the response:

```php
try {
	$validator->validate($form, $input);
}
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		// Render field-level errors.
	}

	return;
}
```

---

Now that the error data shape is clear, continue with [[Displaying error messages]] or move on to [[Extending custom rules]].


The built-in rules cover common HTML constraints, but real applications usually need a few rules that are specific to their own data and workflows.

Typical examples include:

- a password must not contain the username
- a username must not already exist
- one date must be later than another
- an invite code must match a value stored elsewhere

These are all beyond what a generic HTML attribute can express, which is why DomValidation lets us add our own rule objects.

## The `Rule` and `ValidationRules` classes

Custom validation uses two related types:

- `Rule`: a single validation rule
- `ValidationRules`: a collection of rules used by the validator

Most projects will start from `DefaultValidationRules` so that the standard HTML rules still apply.

## A small custom rule

This example makes a password invalid if it contains the submitted username.

```php
use GT\Dom\Element;
use GT\DomValidation\Rule\Rule;

class UsernameNotWithinPassword extends Rule {
	public function isValid(
		Element $element,
		string|array $value,
		array $inputKvp,
	):bool {
		if($element->type !== "password") {
			return true;
		}

		if(!is_string($value)) {
			return true;
		}

		return !str_contains($value, $inputKvp["username"] ?? "");
	}

	public function getHint(Element $element, string $value):string {
		return "The password must not contain the username";
	}
}
```

There are three things to notice here:

1. The rule receives the current element.
2. It also receives the current field value.
3. It receives the whole submitted input array, which makes cross-field checks possible.

## Adding the custom rule to the defaults

```php
use GT\DomValidation\DefaultValidationRules;

$rules = new DefaultValidationRules();
$rules->addRule(new UsernameNotWithinPassword());
```

Then pass that rule collection to the validator:

```php
use GT\DomValidation\Validator;

$validator = new Validator($rules);
```

## Full example

```php
use GT\Dom\HTMLDocument;
use GT\DomValidation\DefaultValidationRules;
use GT\DomValidation\ValidationException;
use GT\DomValidation\Validator;

$document = new HTMLDocument($html);
$form = $document->forms[0];

$rules = new DefaultValidationRules();
$rules->addRule(new UsernameNotWithinPassword());

$validator = new Validator($rules);

try {
	$validator->validate($form, [
		"username" => "cody",
		"password" => "cody-password",
	]);
}
catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		// Render the error message however the application prefers.
	}
}
```

## When to override `getExceptionClass()`

Every rule may optionally return a more specific exception class.

If we do not override `getExceptionClass()`, the base `Rule` class returns `ValidityStateException`.

That is usually enough if we only care about the error messages. Override it when we want to distinguish one category of validation problem from another at exception level.

## A good rule-writing habit

Try to keep each custom rule small and easy to name.

This is better:

- `UsernameNotWithinPassword`
- `EndDateAfterStartDate`
- `InviteCodeIsKnown`

Than one large rule object that tries to validate half the form at once.

Small rules are easier to test, easier to reuse, and easier to explain when someone reads the code later.

---

If you want to understand the exception types and grouped messages that come back from the validator, go to [[Understanding validation errors]].




---

# Documentation: Fetch

The [Fetch API] is a web standard for making HTTP requests in a promise-based way. If you have used `fetch()` in the browser, the core idea will already feel familiar: make a request, work with a `Response`, and choose whether to wait for one request or run many at the same time.

This project brings that workflow to PHP. Behind the scenes it uses cURL (specifically `curl_multi` for concurrency), but the public API is designed to feel as close to the browser's fetch API as possible.

Why do we need yet another HTTP library?
----------------------------------------

There is no shortage of HTTP clients in PHP, and if you already have a preferred tool there is no need to replace it. The purpose of this project is to bring the consistency of web standards to your server-side code.

PHP.GT focuses on bringing familiar web standards to server-side PHP. With Fetch, we can use a very similar mental model on both the client and the server:

+ create a request
+ receive a `Response`
+ process the body as text, JSON or a blob
+ run multiple requests concurrently
+ optionally cancel a request with an abort signal

That makes code easier to move between environments, and easier to reason about when we are building systems that span browser and server code.

What does the library provide?
------------------------------

At the centre of the library is the `GT\Fetch\Http` object. It provides:

+ `fetch()` for non-blocking HTTP requests that return a Promise
+ `awaitFetch()` for a blocking style when we just want the `Response`
+ `wait()` to complete all queued requests
+ `all()` to run all queued requests and resolve when everything has finished

Requests may be configured with familiar fetch-style options such as:

+ `method`
+ `headers`
+ `body`
+ `redirect`
+ `referrer`
+ `integrity`
+ `keepalive`
+ `signal`

There is also support for passing a PSR-7 `RequestInterface` directly to `fetch()`, which makes interop straightforward if the request has already been built elsewhere in your application.

*****

If you are new to the library, start with the [[overview]]. From there we will look at constructing `Http` objects, making requests, choosing how to wait for them, and using the request options that are currently implemented.

When you want to see complete scripts, take a look at the [[usage examples]] page, which mirrors the runnable files in the repository's `example/` directory.

[Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API


The easiest way to understand Fetch is to see the overall shape of the code first.

### 1. Create an `Http` object

```php
use GT\Fetch\Http;

$http = new Http();
```

### 2. Call `fetch()` and work with the `Response`

```php
use GT\Http\Response;

$http->fetch("https://api.github.com/orgs/phpgt/repos")
	->then(function(Response $response) {
		if(!$response->ok) {
			throw new RuntimeException("Unexpected status: $response->status");
		}

		return $response->json();
	})
	->then(function($json) {
		echo "Repository count: ", count($json->getPrimitiveValue()), PHP_EOL;
	});
```

### 3. Finish the queued work

```php
$http->wait();
```

This is the basic pattern we will use throughout the rest of the documentation:

+ create one `Http` object
+ queue one or more requests
+ attach `then()` and `catch()` handlers as needed
+ call `wait()` or `all()`

The `Response` object
---------------------

The first promise returned from `fetch()` resolves with a `GT\Http\Response`. From there we can inspect headers and status immediately, and then choose how to read the body.

The most common body helpers are:

+ `$response->text()`
+ `$response->json()`
+ `$response->blob()`
+ `$response->formData()`

Each of these returns another Promise. This means we can keep chaining work in a natural way.

```php
$http->fetch("https://example.com/data.json")
	->then(function(Response $response) {
		return $response->json();
	})
	->then(function($json) {
		// Work with decoded JSON here.
	});
```

If we prefer a blocking flow, we can use `awaitFetch()` and the matching `await...` methods on the response body:

```php
$response = $http->awaitFetch("https://example.com/data.json");
$json = $response->awaitJson();
```

Concurrency by default
----------------------

One of the most useful parts of this library is that we can queue multiple requests on the same `Http` object before calling `wait()`.

```php
$http->fetch("https://example.com/a.json");
$http->fetch("https://example.com/b.json");
$http->fetch("https://example.com/c.json");

$http->wait();
```

Here we can see the intent clearly: set up all of the work first, then wait for it to complete. This is often much easier to read than deeply nested synchronous request code.

*****

In the next section we will look at [[constructing Http objects]].


In most cases, constructing the main `Http` object can be done without any parameters:

```php
use GT\Fetch\Http;

$http = new Http();
```

That is enough for the majority of applications. There are however a couple of constructor arguments worth understanding.

## Constructor arguments

The constructor signature is:

```php
public function __construct(
	array $curlOptions = [],
	float $interval = 0.01,
	string $curlClass = Curl::class,
	string $curlMultiClass = CurlMulti::class
)
```

### cURL options

The first argument allows us to provide default cURL options that apply to every request made by that `Http` instance.

```php
$http = new Http([
	CURLOPT_TIMEOUT => 10,
	CURLOPT_CONNECTTIMEOUT => 5,
]);
```

This is useful when we want to establish application-wide defaults in one place rather than repeating them on every request.

Some default options are already provided internally, including the request method and user agent. Per-request options passed to `fetch()` will override these defaults where appropriate.

### Interval

The second argument is the loop interval used by the internal async timer. In normal use there is rarely a need to change this, but it can be useful during testing or when tuning behaviour in a very specific environment.

### cURL classes

The final two arguments exist mainly for testing and specialised integration. They allow custom cURL wrapper classes to be injected instead of the standard `GT\Curl\Curl` and `GT\Curl\CurlMulti`.

## One `Http` object or many?

In general, it makes sense to use one `Http` object for a group of related requests, especially when we want those requests to run concurrently and complete together.

```php
$http = new Http();

$http->fetch("https://example.com/profile");
$http->fetch("https://example.com/messages");
$http->fetch("https://example.com/notifications");

$http->wait();
```

If two sets of requests are unrelated, it is perfectly reasonable to use separate `Http` objects for clarity.

*****

In the next section we will make our first request with [[making HTTP requests with fetch]].


The `fetch()` function is the heart of the library. It accepts either a URL-like input or a PSR-7 request object, and returns a Promise that resolves with a `GT\Http\Response`.

## A basic request

Here is the smallest useful example:

```php
use GT\Fetch\Http;
use GT\Http\Response;

$http = new Http();

$http->fetch("https://api.github.com/orgs/phpgt/repos")
	->then(function(Response $response) {
		if(!$response->ok) {
			throw new RuntimeException("Unable to load repositories");
		}

		return $response->json();
	})
	->then(function($json) {
		echo "Loaded ", count($json->getPrimitiveValue()), " repositories.", PHP_EOL;
	})
	->catch(function(Throwable $reason) {
		echo $reason->getMessage(), PHP_EOL;
	});

$http->wait();
```

Here we can see three distinct stages:

+ `fetch()` creates the HTTP request
+ the first `then()` works with the `Response`
+ the second `then()` works with the decoded body

## What does the first Promise resolve with?

The first Promise resolves with a `GT\Http\Response`. This allows us to inspect:

+ `status`
+ `ok`
+ headers
+ URI information

The response body can then be consumed using one of the response helper methods:

+ `text()`
+ `json()`
+ `blob()`
+ `formData()`

For example:

```php
$http->fetch("https://example.com/message.txt")
	->then(function(Response $response) {
		return $response->text();
	})
	->then(function(string $text) {
		echo $text;
	});
```

## Passing a PSR-7 request object

If the request has already been constructed elsewhere in the application, we do not need to rebuild it as an init array. `fetch()` accepts any PSR-7 `RequestInterface`.

```php
use GT\Http\Header\RequestHeaders;
use GT\Http\Request;
use GT\Http\Uri;

$request = new Request(
	"GET",
	new Uri("https://api.github.com/orgs/phpgt/repos"),
	new RequestHeaders()
);

$http->fetch($request)
	->then(function(Response $response) {
		return $response->json();
	})
	->then(function($json) {
		echo "Done.", PHP_EOL;
	});
```

This is especially useful when another library, framework component or application layer is already speaking PSR-7.

## Error handling

Any exception thrown in the chain can be handled with `catch()`.

```php
$http->fetch("https://example.com/api")
	->then(function(Response $response) {
		if(!$response->ok) {
			throw new RuntimeException("Status was $response->status");
		}

		return $response->json();
	})
	->catch(function(Throwable $error) {
		echo "Request failed: ", $error->getMessage(), PHP_EOL;
	});
```

*****

For longer examples, take a look at [[usage examples]].

The next section covers the supported [[request options]].


The second argument to `fetch()` is the init array. This follows the browser Fetch style where possible, but because this is server-side PHP, not every browser option has a meaningful implementation.

```php
$http->fetch("https://example.com/api", [
	"method" => "POST",
	"headers" => [
		"Accept" => "application/json",
	],
]);
```

Below we will look at each supported option in turn.

## `method`

Use `method` to set the HTTP method.

```php
$http->fetch("https://postman-echo.com/post", [
	"method" => "POST",
]);
```

If omitted, the default request method is `GET`.

## `headers`

Headers are supplied as an associative array.

```php
$http->fetch("https://example.com/api", [
	"headers" => [
		"Accept" => "application/json",
		"X-Request-Id" => "abc123",
	],
]);
```

If a header has multiple values, an array of values may be provided.

## `body`

The request body may be a `string`, associative `array`, or `GT\Http\FormData`.

### Sending a string body

```php
$http->fetch("https://example.com/api", [
	"method" => "POST",
	"headers" => [
		"Content-Type" => "application/json",
	],
	"body" => json_encode(["name" => "Ada"]),
]);
```

### Sending form data

```php
use GT\Http\FormData;

$formData = new FormData();
$formData->set("name", "Mark Zuckerberg");
$formData->set("email", "zuck@fb.com");

$http->fetch("https://postman-echo.com/post", [
	"method" => "POST",
	"body" => $formData,
]);
```

### Uploading files

If a `FormData` item contains a `SplFileObject` or `GT\Http\File`, it will be prepared for cURL file upload automatically.

See [[usage examples]] for a complete upload example.

## `redirect`

The following redirect modes are supported:

+ `follow`
+ `manual`
+ `error`

`follow` will follow redirects automatically. This is the default behaviour.

`manual` disables automatic redirect following, allowing us to inspect the redirect response ourselves.

`error` will throw a `FetchException` if the response attempts to redirect.

```php
$http->fetch("https://example.com/redirect", [
	"redirect" => "error",
])->catch(function(Throwable $error) {
	echo $error->getMessage(), PHP_EOL;
});
```

## `referrer`

The `referrer` option controls the `Referer` header.

```php
$http->fetch("https://example.com/api", [
	"referrer" => "https://www.example.com/from-here",
]);
```

To omit the referrer:

```php
$http->fetch("https://example.com/api", [
	"referrer" => "no-referrer",
]);
```

## `integrity`

The `integrity` option allows subresource integrity checking against the completed response body.

```php
$http->fetch("https://example.com/app.js", [
	"integrity" => "sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=",
]);
```

This is useful when we want to assert that a fetched resource matches a known hash before continuing.

## `keepalive`

`keepalive` maps to cURL's TCP keepalive support.

```php
$http->fetch("https://example.com/api", [
	"keepalive" => 1,
]);
```

## `signal`

`signal` is used to abort a request before it completes.

```php
use GT\Fetch\AbortController;

$controller = new AbortController();

$http->fetch("https://example.com/large-file.zip", [
	"signal" => $controller->signal,
]);

$controller->abort();
```

This is covered in more detail in [[cancelling requests]].

## Options that are recognised but not available server-side

Some browser fetch options do not currently have a meaningful implementation here and will throw a `NotAvailableServerSideException` when used:

+ `mode`
+ `credentials`
+ `referrerPolicy`

The `cache` option is recognised, but is not currently implemented.

That means the safest approach is to treat this library as _fetch-inspired_ rather than as a byte-for-byte browser implementation. Only the options that make sense server-side are active.

*****

In the next section we will look at [[waiting for responses]].


Once requests have been queued, we need to decide how we want execution to continue. This library offers three main ways to do that:

+ `wait()`
+ `all()`
+ `awaitFetch()`

## `wait()`

`wait()` runs the internal event loop until all queued requests are complete.

```php
$http->fetch("https://example.com/a");
$http->fetch("https://example.com/b");

$http->wait();
```

This is the most direct and most commonly used option.

## `all()`

`all()` is similar to `wait()`, but returns a Promise that resolves when the final request has completed.

```php
$http->fetch("https://example.com/a");
$http->fetch("https://example.com/b");

$http->all()->then(function(float $seconds) {
	echo "All requests completed in $seconds seconds.", PHP_EOL;
});
```

This is helpful when we want the completion of the whole batch to become part of the promise chain itself.

## `awaitFetch()`

Sometimes we do not want to think in terms of chained promises at all. For that case there is `awaitFetch()`, which blocks until the response object is available and returns it directly.

```php
$response = $http->awaitFetch("https://example.com/api");
echo $response->status, PHP_EOL;
```

Once we have the response, we can continue in the same blocking style:

```php
$response = $http->awaitFetch("https://example.com/data.json");
$json = $response->awaitJson();
```

## Which should we use?

As a rule of thumb:

+ use `fetch()` with `wait()` when we want concurrent requests and promise chains
+ use `all()` when we want one promise for the completion of the whole batch
+ use `awaitFetch()` when a blocking style is clearer

None of these approaches is more "correct" than the others. It is mostly about choosing the clearest expression for the job at hand.

*****

The next section looks specifically at [[concurrent requests]].


One of the main reasons to use this library is the ability to queue several requests and let them complete together.

## Queue first, wait later

Here is the important pattern:

```php
$http = new Http();

$http->fetch("https://example.com/profile");
$http->fetch("https://example.com/messages");
$http->fetch("https://example.com/notifications");

$http->wait();
```

Each `fetch()` call registers more work, but the script only blocks once `wait()` is called.

## Independent promise chains

Each request can have its own chain of handlers.

```php
$http->fetch("https://example.com/profile.json")
	->then(function(Response $response) {
		return $response->json();
	})
	->then(function($profile) {
		echo "Loaded profile", PHP_EOL;
	});

$http->fetch("https://example.com/avatar.jpg")
	->then(function(Response $response) {
		return $response->blob();
	})
	->then(function($blob) {
		echo "Loaded avatar", PHP_EOL;
	});

$http->wait();
```

There is no guarantee about the order in which those responses will complete, and usually that is exactly what we want.

## Waiting for the whole batch

If we want one final callback after everything is done, `all()` makes that clear:

```php
$http->fetch("https://example.com/a");
$http->fetch("https://example.com/b");

$http->all()->then(function() {
	echo "Done!", PHP_EOL;
});
```

## Cancelling selected requests

Concurrent work becomes especially useful when combined with abort signals. We can give each request its own controller and then cancel only the ones we no longer need.

```php
use GT\Fetch\AbortController;

$first = new AbortController();
$second = new AbortController();

$http->fetch("https://example.com/a.zip", ["signal" => $first->signal]);
$http->fetch("https://example.com/b.zip", ["signal" => $second->signal]);

$first->abort();
$http->wait();
```

*****

The abort behaviour is described in more detail in [[cancelling requests]].


Long-running downloads are not always supposed to finish. Sometimes the user navigates away, sometimes another request supersedes the first one, and sometimes we only want the fastest result from a group of alternatives.

For those cases, the library supports abort signals.

## `AbortController`

To cancel a request, create an `AbortController` and pass its signal to the request:

```php
use GT\Fetch\AbortController;
use GT\Fetch\Http;

$http = new Http();
$controller = new AbortController();

$http->fetch("https://example.com/large-file.zip", [
	"signal" => $controller->signal,
]);
```

When we decide the request should stop, call `abort()`:

```php
$controller->abort();
$http->wait();
```

## Cancelling one request out of many

If several downloads are happening concurrently, give each one its own controller.

```php
$a = new AbortController();
$b = new AbortController();

$http->fetch("https://example.com/file-a.zip", [
	"signal" => $a->signal,
]);

$http->fetch("https://example.com/file-b.zip", [
	"signal" => $b->signal,
]);

$a->abort();
$http->wait();
```

Here we can see that only the first request is cancelled.

## Cancelling several requests together

If we want a single action to cancel more than one request, reuse the same controller:

```php
$controller = new AbortController();

$http->fetch("https://example.com/a.zip", ["signal" => $controller->signal]);
$http->fetch("https://example.com/b.zip", ["signal" => $controller->signal]);

$controller->abort();
$http->wait();
```

## Comparison with the browser API

The usage pattern is deliberately close to browser fetch:

+ create an `AbortController`
+ pass `signal`
+ call `abort()`

The important difference is in behaviour after cancellation. In browser fetch, aborting produces a well-defined `AbortError` rejection. In this library, the transfer is stopped through cURL's progress callback. That means the cancellation mechanism is present, but it is not currently modelled as a dedicated browser-style abort exception.


The repository contains a small `example/` directory with runnable scripts. This page walks through them and explains what each one demonstrates.

If you prefer to learn by reading complete scripts rather than isolated snippets, this is the best place to start.

## Example 1: Basic fetch

File: `example/01-basic-fetch.php`

This example performs a simple GET request to the GitHub API and then decodes the JSON response.

Here we can see the standard fetch workflow very clearly:

+ queue the request with `fetch()`
+ inspect the `Response`
+ decode the body with `json()`
+ finish the request batch with `wait()`

```php
use GT\Fetch\Http;
use GT\Http\Response;
use GT\Json\JsonKvpObject;
use GT\Json\JsonPrimitive\JsonArrayPrimitive;

$http = new Http();

$http->fetch("https://api.github.com/orgs/phpgt/repos")
	->then(function(Response $response) {
		echo "Got a response. Processing JSON... ", PHP_EOL;

		if(!$response->ok) {
			throw new RuntimeException("Can't retrieve Github's API on $response->uri");
		}

		return $response->json();
	})
	->then(function(JsonArrayPrimitive $json) {
		echo "SUCCESS: Json promise resolved!", PHP_EOL, PHP_EOL;
		echo "PHP.Gt has the following repositories: ";
		$repoList = [];
		/** @var JsonKvpObject $item */
		foreach($json->getPrimitiveValue() as $item) {
			array_push($repoList, $item->getString("name"));
		}

		echo wordwrap(implode(", ", $repoList)) . ".";
		echo PHP_EOL, PHP_EOL;
	})
	->catch(function(Throwable $reason) {
		echo "There was an error!",
			PHP_EOL,
			get_class($reason),
			" - ",
			$reason->getMessage(),
			" ",
			$reason->getFile(),
			":", $reason->getLine(),
			PHP_EOL, PHP_EOL;
	});

$http->wait();
```

## Example 2: POST request

File: `example/02-post-request.php`

This example posts `FormData` to [Postman Echo](https://docs.postman-echo.com/) and then reads the JSON representation of what the server received.

It shows:

+ setting the request method
+ sending a request body
+ decoding JSON in the response
+ working with type-safe getters from `GT\Json`

```php
use GT\Fetch\Http;
use GT\Http\FormData;
use GT\Http\Response;
use GT\Json\JsonObject;

$formData = new FormData();
$formData->set("name", "Mark Zuckerberg");
$formData->set("dob", "1984-05-14");
$formData->set("email", "zuck@fb.com");

$http = new Http();
$http->fetch("https://postman-echo.com/post", [
	"method" => "POST",
	"body" => $formData,
])
	->then(function(Response $response) {
		if(!$response->ok) {
			throw new RuntimeException("Error posting to Postman Echo.");
		}

		return $response->json();
	})
	->then(function(JsonObject $json) {
		echo "The Postman Echo server received the following form fields:";
		echo PHP_EOL;

		$formObject = $json->getObject("form");
		foreach($formObject->asArray() as $key => $value) {
			echo "$key = $value" . PHP_EOL;
		}
	});

$http->wait();
```

## Example 3: Download a JPG

File: `example/03-download-jpg.php`

This example fetches a binary response from Cat as a Service and saves it to disk.

It demonstrates:

+ checking response headers
+ converting the body to a `Blob`
+ handling binary downloads

```php
use GT\Fetch\Http;
use GT\Http\Blob;
use GT\Http\Response;

$http = new Http();
$http->fetch("https://cataas.com/cat")
->then(function(Response $response) {
	if(!$response->ok) {
		throw new RuntimeException("Error getting a cat. (ERROR $response->status)");
	}

	echo "Cat as a Service responded with a binary file with the following attributes:" . PHP_EOL;
	echo "Response size: " . $response->getHeaderLine("Content-Length") . PHP_EOL;
	echo "File type: " . $response->getHeaderLine("Content-Type") . PHP_EOL;
	return $response->blob();
})
->then(function(Blob $blob) {
	$file = new SplFileObject("/tmp/cat.jpg", "w");
	$bytesWritten = $file->fwrite($blob);
	echo "Written $bytesWritten bytes." . PHP_EOL;
	echo "Photo written to " . $file->getPathname() . PHP_EOL;
});

$http->wait();
```

## Example 4: Multiple concurrent fetch

File: `example/04-multiple-concurrent-fetch.php`

This script queues several unrelated requests and lets them resolve together.

It is a good example of the main async advantage of the library: we can declare all of the work first and then allow the internal loop to complete it.

## Example 5: Upload a file

File: `example/05-upload-file.php`

Here we build a `FormData` object that includes a file upload. The file is posted to Postman Echo, which returns the uploaded content in the response body.

This demonstrates:

+ multipart form uploads
+ using `FormData` with files
+ handling the JSON response afterwards

## Example 6: Passing a request object

File: `example/06-request-object.php`

This example shows that `fetch()` does not need to be given a URL string. We can pass a PSR-7 `RequestInterface` instead.

```php
use GT\Fetch\Http;
use GT\Http\Header\RequestHeaders;
use GT\Http\Request;
use GT\Http\Response;
use GT\Http\Uri;

$request = new Request(
	"GET",
	new Uri("https://api.github.com/orgs/phpgt/repos"),
	new RequestHeaders()
);

$http = new Http();
$http->fetch($request)
	->then(function(Response $response) {
		echo "Status: ", $response->status, PHP_EOL;
		return $response->json();
	})
	->then(function($json) {
		echo "Received ", count($json->getPrimitiveValue()), " repositories.", PHP_EOL;
	});

$http->wait();
```

## Example 7: Cancelling a download

File: `example/07-abort-request.php`

This example introduces `AbortController`. It starts a request, aborts it, and then finishes the batch.

```php
use GT\Fetch\AbortController;
use GT\Fetch\Http;

$http = new Http();
$controller = new AbortController();

$http->fetch("https://example.com/large-file.zip", [
	"signal" => $controller->signal,
]);

$controller->abort();
$http->wait();
```

The point of the example is the control flow rather than the output. When we need to stop one request out of several, or stop several with one shared signal, this is the mechanism to use.




---

# Documentation: FileCache

Making slow operations like HTTP calls or database queries can be minimised by caching the result of the operations in local files. This can improve performance, reduce network usage, and avoid rate limiting, to name some common benefits. This library provides a single function to define where to cache, what to cache, and when to cache. A validity of 1 hour is set by default.

We provide a cache directory, a cache key, and a callback that knows how to produce the value. If a fresh cached value already exists, the callback is skipped. If the entry is missing or expired, the callback runs and its return value is written to disk.

## Example usage: get the latitude/longitude of the user's IP address

It's an expensive operation to make an HTTP call for every page view, but in this example we want to use a remote service to provide us with the estimated latitude/longitude of the current IP address.

The first time we see the IP address will have to make an HTTP call, but subsequent calls will be able to take advantage of the cache.

```php
use GT\FileCache\Cache;

$ipAddress = $_SERVER["REMOTE_ADDR"];
$cache = new Cache("/tmp/ip-address-geolocation", 60 * 10);

$location = $cache->get("ipinfo:$ipAddress", function()use($ipAddress):string {
	$json = file_get_contents("https://ipinfo.io/$ipAddress");
	$data = json_decode($json);
	return $data->loc;
});

echo $location;
```

In this example, each IP address gets its own cache entry, the cache lives for 10 minutes, and repeated requests for the same address reuse the file until it expires.

---

Start with the [[Quick start guide]] to set up a cache directory and your first cache lookup.


## 1. Install the package

```bash
composer require phpgt/filecache
```

## 2. Construct a `Cache`

```php
use GT\FileCache\Cache;

$cache = new Cache(
	__DIR__ . "/cache",
	60 * 5
);
```

The first argument is the directory where cache files will be stored. The second argument is the lifetime, in seconds. In this example, entries remain fresh for 5 minutes.

If we omit the second argument, the default lifetime is 1 hour.

There is also a third optional constructor argument for supplying a `FileAccess` instance directly. Most applications do not need that, but it is available for advanced integration and testing.

## 3. Load data via the cache

```php
$weather = $cache->get("weather:london", function():array {
	return [
		"summary" => "Cloudy",
		"temperature" => 14,
	];
});
```

On the first call, the callback runs and its return value is written to a cache file. On later calls with the same key, the cached value is returned immediately until the entry expires.

## 4. Use a meaningful cache key

The cache key is the logical name of the entry:

```php
$user = $cache->get("user:105:profile", fn() => loadUserProfile(105));
```

Keys do not need to be limited to filenames. The library safely escapes characters that would otherwise affect paths, so values like URLs can be used directly:

```php
$page = $cache->get("https://example.com/products/105", fn() => fetchPage());
```

The stored filename still remains readable for debugging because it uses URL-style escaping rather than an opaque hash.

## 5. Adjust the getter to match your expected type

If we know the value should be a string, integer, float, boolean, date, array, or class instance, there are typed getters available:

```php
$username = $cache->getString("user:105:name", fn() => "Cody");
$count = $cache->getInt("dashboard:visits", fn() => 0);
```

---

The full set of getters is covered in [[Type safety]].


`GT\FileCache\Cache` exposes one untyped getter and several typed getters.

The untyped `get()` method returns whatever value was cached. The typed methods either cast, convert, or validate the cached value before returning it.

## The available getters

- `get(string $name, callable $callback):mixed`
- `getString(string $name, callable $callback):string`
- `getInt(string $name, callable $callback):int`
- `getFloat(string $name, callable $callback):float`
- `getBool(string $name, callable $callback):bool`
- `getDateTime(string $name, callable $callback):DateTimeInterface`
- `getArray(string $name, callable $callback):array`
- `getTypedArray(string $name, string $className, callable $callback):array`
- `getInstance(string $name, string $className, callable $callback):object`

## Basic getter

```php
$value = $cache->get("username", fn() => "guest");
```

This method is useful when the calling code already knows how to handle the cached value.

## Scalar getters

`getString()`, `getInt()`, `getFloat()`, and `getBool()` follow PHP's normal scalar casting behaviour:

```php
$count = $cache->getInt("visits", fn() => "105"); // String "105" will be cast to int `105`.
$enabled = $cache->getBool("feature-flag", fn() => "1"); // String "1" will be cast to `true`
```

That means these methods do not perform strict validation. If the cached value can be cast by PHP, the cast result is returned.

## Date and time getter

`getDateTime()` accepts several common cached forms:

- an existing `DateTimeInterface` instance
- an integer Unix timestamp
- a string accepted by `DateTimeImmutable`

```php
$publishedAt = $cache->getDateTime("article:publishedAt", fn() => "2026-04-19 09:30:00");
```

The return value is always a `DateTimeInterface`.

## Array getter

`getArray()` only checks that the cached value is an array:

```php
$config = $cache->getArray("app:config", fn() => ["debug" => false]);
```

If the cached value is not an array, a `TypeError` is thrown.

## Typed arrays

`getTypedArray()` validates every value in the array and returns a converted array of the requested type:

```php
$ids = $cache->getTypedArray("user:ids", "int", fn() => ["1", 2, 3.0]);
$files = $cache->getTypedArray("files", SplFileInfo::class, fn() => []);
```

The supported scalar type names are:

- `"int"` or `"integer"`
- `"float"` or `"double"`
- `"string"`
- `"bool"` or `"boolean"`

We can also pass a class name to require every element to be an instance of that class.

If any element cannot be converted or validated, a `TypeError` is thrown.

## Single object instances

`getInstance()` ensures that the cached value is an instance of the class we ask for:

```php
$file = $cache->getInstance("report:file", SplFileInfo::class, function():SplFileInfo {
	return new SplFileInfo("/tmp/report.txt");
});
```

---

Now move on to [[Callback handling]] to see when the callback runs and how cache population failures are handled.


Every call to `GT\FileCache\Cache` is built around a callback.

The callback tells the cache how to produce a fresh value if the cached entry is missing or expired. If a fresh cached value already exists, the callback is not executed.

```php
$profile = $cache->get("user:105:profile", fn() => loadUserProfile(105));
```

## When the callback runs

The callback is executed when:

- there is no cache file for the key
- the cache file exists but is older than the configured lifetime

If the cache file exists and is still fresh, the callback is skipped and the cached value is returned immediately.

## What happens to the return value

When the callback runs successfully, its return value is:

1. serialised and written to the cache directory
2. returned to the caller

That means the callback should always return a value that PHP can serialise safely.

## Handling generation failures

If generating a replacement value fails, the callback can throw `GT\FileCache\CacheValueGenerationException`:

```php
use GT\FileCache\CacheValueGenerationException;

$content = $cache->get("remote:feed", function():string {
	$response = file_get_contents("https://example.com/feed");
	if($response === false) {
		throw new CacheValueGenerationException("Feed request failed");
	}

	return $response;
});
```

When that exception is thrown during cache generation, FileCache returns `null` and does not write a replacement file.

## `null` is still a valid cached value

Returning `null` from the callback is different from throwing `CacheValueGenerationException`.

```php
$value = $cache->get("optional:value", fn() => null);
```

In that case, `null` is written to the cache and treated as a normal cached value on later reads.

## Keep callbacks focused

In practice, callbacks are easiest to reason about when they only fetch or compute the value and then return it. If the logic is more than a few lines, it is usually clearer to move it into a separate function or method and pass a callable reference.

```php
$profile = $cache->get("user:105:profile", $userRepository->loadProfile(...));
```

---

Next, move on to [[Cache invalidation]] for the cache lifetime model.


FileCache uses time-based invalidation.

Each `Cache` instance is constructed with a lifetime in seconds. Once a cached entry is older than that lifetime, it is treated as invalid and the next read will regenerate it through the callback.

## Configuring the lifetime

```php
use GT\FileCache\Cache;

$cache = new Cache(
	__DIR__ . "/cache",
	60 * 30
);
```

In this example, every entry created by that `Cache` instance remains valid for 30 minutes.

If no lifetime is provided, the default is 1 hour.

## How invalidation happens

There is no background cleanup job and no proactive refresh process in the library. Invalidation happens when we attempt to read a key:

1. FileCache checks whether the cache file exists.
2. FileCache compares the file modification time with the configured lifetime.
3. If the entry is too old, the callback is executed to generate a replacement value.

This keeps the implementation simple and means expired entries are only refreshed when they are actually needed again.

## Manual invalidation

The high-level `Cache` API exposes `invalidate()` for removing one cached entry by key:

```php
$cache->invalidate("user:105:profile");
```

This deletes the stored cache file for that key if it exists. If the key is already missing, the call has no effect.

The next time that key is requested through `get()` or any typed getter, the callback will run again to repopulate the cache.

For lower-level control, the library also includes `GT\FileCache\FileAccess`, which exposes:

- `getData()`
- `setData()`
- `checkValidity()`
- `invalidate()`

That class is also the optional third constructor argument to `Cache`, so applications with custom cache management requirements can work at the lower level when needed.

---

For details on how keys map to filenames on disk, continue with [[Cache keys and storage]].


When we call a getter, the cache key is escaped before it is appended to the cache directory path. This prevents path traversal while still keeping the stored filename understandable during debugging.

## Readable escaping

For example, this cache key:

```php
$cache->get("https://example.com/test", fn() => "ok");
```

is stored using a URL-escaped filename inside the cache directory:

```text
https%3A%2F%2Fexample.com%2Ftest
```

That is easier to inspect than a hash, while still ensuring the key cannot create nested paths such as `../outside-cache`.

## Choosing cache keys

Good cache keys are:

- stable for the same logical resource
- specific enough to avoid collisions
- easy for developers to recognise when inspecting cache files

Examples:

- `user:105:profile`
- `product:blue-shirt:availability`
- `https://example.com/api/feed?page=2`

## Choosing a cache directory

The cache directory is supplied when the `Cache` object is constructed:

```php
$cache = new GT\FileCache\Cache(__DIR__ . "/cache");
```

Choose a location that:

- is writable by the PHP process
- is safe to persist cached data in
- can be cleared without affecting source code or user uploads

For web applications, it is usually better to keep the directory outside the public document root unless exposing cache files intentionally.




---

# Documentation: Flux

Flux gives server-rendered applications a _fluid user experience_ without asking us to abandon plain HTML forms, links, and full-page responses.

Flux respects Hypermedia - if your page is HTML, you should always serve HTML pages to the browser, without the need for computer languages like JSON to update the page state.

> [!IMPORTANT]
> Flux is built as a standalone library, but the main intention is to be used with PHP.GT/WebEngine - Flux is shipped by default in WebEngine applications. 
> All examples and server-side code **use plain PHP**, but any language or framework could be used.
> For more information about how WebEngine takes full advantage of Flux, see https://www.php.gt/docs/webengine/flux/

In this guide, we will start with a simple form, then steadily add more of Flux's behaviour until we have covered the whole library. The examples in this repository all follow the same idea: we keep rendering complete HTML on the server, and Flux automatically swaps the right part of the page in the browser.

## What we'll build up to

- Background form submissions using ordinary `<form>` elements.
- Scoped page updates using `data-flux` directives.
- Link navigation without a full-page refresh.
- Live polling regions that keep themselves up to date.
- Autosave, attribute refreshes, and request rate limiting.
- Drag-and-drop ordering backed by ordinary server-side form handling.
- Reattaching our own JavaScript event handlers after Flux swaps DOM elements.

> [!NOTE]
> Flux expects the server response to be a full HTML document. We do not need to build bespoke JSON APIs or partial templates just to use it.

## The guiding idea

Flux is a progressive enhancement library - it enhances normal client/server browser usage rather than replacing it.

- A Flux form is still a real form, that still makes the same POST request to your server-side code.
- A Flux link is still a real link, that still makes the same GET request.
- A live region is still rendered by the server, without having to change any server-side code.

That means our application should be written to work without JavaScript first, and then Flux will automatically enhance the user experience to make it more fluid.

## Quick preview

```html
<form method="post" data-flux="update-inner">
	<output>0</output>
	<button name="do" value="increment" data-flux="submit">Increment</button>
</form>

<textarea>Type something into this textarea - the state will be persisted after clicking the increment button above.</textarea>
```

Here we let the button submit in the background, then tell Flux to replace only the form's inner HTML with the matching form from the returned document. The textarea on the page is just for show - without Flux, clicking the button would cause a full-page refresh, losing any state within the textarea.

Scale this up to a full fledged web application, and you can imagine many forms with multiple live-updating elements, all working with the richness of a Single Page Application. 

---

Start by [[Installing]], so the library is loaded correctly before we add any directives.


Before we can use Flux, we need to load it into the browser as an ES module.

## Install from npm

Add the package to the project:

```bash
npm install github:phpgt/Flux
```

If we want a specific release, we can pin the tag:

```bash
npm install "github:phpgt/Flux#v1.2.3"
```

## Import Flux in JavaScript

In most projects, we will import Flux from the main browser entry point:

```js
import "@phpgt/flux";
```

The package exports `src/main.es6`, which creates a `new Flux()` instance immediately. As soon as the script runs, Flux scans the page for any elements with `data-flux`.

## Import Flux directly in HTML

If we are not bundling JavaScript, we can serve the built file directly from `node_modules/@phpgt/flux/dist/flux.js`:

```html
<script type="module" src="/flux.js" defer></script>
```

## Turn on debug mode when developing Flux itself

There is no runtime configuration object for normal usage, but there is a debug export that enables internal logging:

```js
// Add this FluxDebug line above your usual import to enable debug mode.
import { FluxDebug } from "@phpgt/flux";
import "@phpgt/flux";
```

With that import in place, Flux logs extra detail to the console while it initialises and reattaches behaviour.

> [!INFO]
> Flux inserts a `<style id="flux-style">` tag when it starts, for minimal hiding/showing of controlled elements. In the browser tests, that is used as the signal that initialisation has completed.

---

Now that the script is loaded, let's build [[your first Flux form]].


We will begin with the smallest useful Flux interaction: a form that submits in the background and updates itself with the server-rendered result.

The repository's first example is a session-backed counter at [`example/01-counter.php`](https://github.com/PhpGt/Flux/blob/master/example/01-counter.php). The page contains a `<textarea>` outside the form so we can see the difference immediately: a normal page reload would cause the whole page to refresh, losing the state of the textarea - but Flux keeps the page state unchanged.

## Start with plain HTML

```html
<form method="post">
	<output>0</output>
	<button name="do" value="increment">Increment</button>
	<button name="do" value="decrement">Decrement</button>
</form>
```

On the server, we can handle the buttons exactly as we always would. Example 01 stores the count in the session, changes the value, and responds with a redirected full HTML page.

> [!IMPORTANT]
> Flux is built as a standalone library, but the main intention is to be used with PHP.GT/WebEngine - Flux is shipped by default in WebEngine applications.
> All examples and server-side code **use plain PHP**, but any language or framework could be used.
> For more information about how WebEngine takes full advantage of Flux, see https://www.php.gt/docs/webengine/flux/

## Add Flux

To make the form submit in the background, we have two options.

### Option 1: mark the form as a Flux container

```html
<form method="post" data-flux>
	<output>0</output>
	<button name="do" value="increment">Increment</button>
	<button name="do" value="decrement">Decrement</button>
</form>
```

On a `<form>`, bare `data-flux` tells Flux to listen for submit events on that form.

### Option 2: mark individual buttons to submit, and mark just the elements to update

```html
<form method="post">
	<output data-flux="update">0</output>
	<button name="do" value="increment" data-flux>Increment</button>
	<button name="do" value="decrement" data-flux>Decrement</button>
</form>

<textarea>Type something into this textarea - the state will be persisted after clicking the increment button above.</textarea>
```

> [!NOTE]
> `data-flux` is a shorthand attribute on some types of element.
> On forms, `data-flux` converts the form into a Flux container.
> On buttons, `data-flux` is short for `data-flux="submit"` - handling the single button click instead of the whole form submission.
> On links, `data-flux` is short for `data-flux="link" - but we haven't got to links yet.
> For more information, see the [[list of flux attributes]].

## What the response should look like

Flux expects a complete HTML page in response. We do not need to return state in JSON or anything like that, and we do not need a separate partial render just for the counter element. Remember, we're just enhancing an already-working server-first application. The server can redirect or render the normal route as usual, and Flux will do the rest.

## What changes in the browser

When the button is pressed:

1. Flux prevents the browser's default submit.
2. Flux gathers `FormData`, including the clicked button name and value.
3. Flux sends the request using `fetch`, in the background (also known as "ajax").
4. Flux parses the returned HTML document.
5. Flux updates whichever targets we registered on the current page with attributes like `data-flux="update"`

That is why the `<textarea>` in the example keeps its content: only the Flux target updates, not the whole page.

> [!INFO]
> If the form has an `action`, Flux treats the response like navigation and also updates the browser history. If there is no `action`, Flux updates in place without pushing a history entry.

> [!INFO]
> While a Flux form submission is in flight, Flux adds the class `flux-form-waiting` to both the submitting `<form>` and the page `<body>`. If a specific submit button triggered the request, that button also gets `flux-button-waiting` until the request finishes. We can use those classes to dim the interface, show a spinner, or disable pointer interactions in our own CSS.

---

Our form now submits in the background. Next we will decide exactly what gets replaced when [[updating part of the page]].


Once a request comes back from the server, Flux needs to know which elements on the current page should be refreshed. This is where the update directives come in.

## Replace the whole element with `data-flux="update"`

The `update` directive replaces the target element itself using the matching element from the returned document. `data-flux="update"` is shorthand for `data-flux="update-outer"` (meaning update the outer HTML, including all attributes, of the element).

```html
<form method="post" data-flux="update">
	<output>0</output>
	<button name="do" value="increment" data-flux="submit">Increment</button>
</form>
```

This is a good default when the element's own attributes may change between responses.

## Replace only the contents with `data-flux="update-inner"`

If we want to keep the wrapper element in place and only swap its children, we can use `update-inner` instead:

```html
<form method="post">
	<ul class="example-list" data-flux="update-inner">
		<li>First item</li>
	</ul>
	<input name="new-item" />
	<button name="do" value="add" data-flux="submit">Add</button>
</form>
```

This is similar to how [`example/02-list.php`](https://github.com/PhpGt/Flux/blob/master/example/02-list.php) works. The form remains the target, but its contents refresh after each add or delete.

## When to choose each one

- Use `update` when the container itself may change.
- Use `update-inner` when the outer shell should stay put.

Both patterns still rely on the returned HTML document containing the corresponding element in the same DOM position.

## Matching happens by DOM position

If a Flux element has an `id` attribute, the matching `id` of subsequent responses will be used when replacing. However, flux **does not require you to add an `id` to elements** that need replacing. Instead, it records the current element's path through the DOM and looks up the element at that same path in the new document.

That means this style of server rendering works well if:

- the page returns the same overall document structure
- the Flux target is still in the same place
- the content inside that target changes normally on the server

> [!IMPORTANT]
> If the surrounding layout moves around dramatically between requests, Flux may no longer find the intended replacement node, so an `id` attribute is required.

## Preserving focus and custom listeners

When Flux swaps content, it also does some repair work for us:

- it restores focus and text selection where possible
- it reinitialises newly inserted `data-flux` elements
- it reattaches event listeners that were added through `addEventListener`

That last point matters if we add our own JavaScript behaviour to elements inside a Flux target, because when the new response replaces the element, any event listeners that had already been added to the element will no longer be attached to the new element.

It's important to import Flux before any other JavaScript executs on the page, so Flux can intercept the `Element.addEventListener` function.

---

With a single update target in place, we can look at pages that refresh several related elements together in [[coordinating multiple updates]].


Flux is not limited to one target at a time. If multiple elements on the current page are registered for updates, Flux will refresh all of them from the same returned document.

[`example/03-multiple-forms.php`](https://github.com/PhpGt/Flux/blob/master/example/03-multiple-forms.php) is the clearest demonstration. The page has two independent counters and a third `<output>` showing their sum.

## Register several targets

```html
<form method="post" data-flux>
	<h1>Counter A</h1>
	<output data-flux="update" class="a">0</output>
	<button name="do" value="incrementA">Increment A</button>
</form>

<form method="post" data-flux>
	<h1>Counter B</h1>
	<output data-flux="update" class="b">0</output>
	<button name="do" value="incrementB">Increment B</button>
</form>

<output data-flux="update" class="ab">0</output>
```

When either form submits, Flux parses the new HTML document once and refreshes every registered target that applies to that kind of response.

## Respect hypermedia

By building our app with traditional server-rendered techniques, we can keep our server code simple, predictable, traceable, and testable.

- update state on the server
- render the normal page
- have a single and predictable [[distinct logic authority]]
- let Flux manipulate the matching pieces on the client

## Mixing forms and passive targets

A Flux target does not have to be the form that triggered the request. Any element can be updated, including:

- `<output>`
- `<section>`
- `<main>`
- a single card in a dashboard
- the site's navigation menu
- all of the above

As long as the new document contains the corresponding element in the same position, or an element with matching `id`, Flux can refresh it.

## Choosing container vs child targets

In practice, we often choose one of these two patterns:

- make the form itself the target when the whole form should rerender
- mark specific child elements with `update` when only a few values need refreshing

Example 03 uses the second style so the two forms remain stable while the outputs change.

---

So far we have only submitted forms. Next we will make ordinary links feel fluid in [[link navigation]].


Flux can intercept ordinary links and fetch the destination document in the background. This keeps navigation fluid while we still serve complete HTML pages from the server.

[`example/04-links.php`](https://github.com/PhpGt/Flux/blob/master/example/04-links.php), [`example/04a-page1.php`](https://github.com/PhpGt/Flux/blob/master/example/04a-page1.php), and [`example/04b-page2.php`](https://github.com/PhpGt/Flux/blob/master/example/04b-page2.php) form a small three-page walkthrough of this behaviour.

## Turn an anchor into a Flux link

We can either write `data-flux="link"` explicitly or use shorthand `data-flux` on the `<a>` element:

```html
<a href="/reports" data-flux>Reports</a>
```

When the link is clicked, Flux:

1. prevents the browser's default navigation
2. fetches the linked document in the background
3. pushes a history state with the new URL
4. applies any link-capable update targets

## Link-only update targets

When a link is clicked, the expected behaviour of the browser is distinctively different from when a form submits: a link should replace the content of the _page_, not just small components of the page.

We can mark which element contains the page content with `data-flux="update-link"`. This element will be updated only when a link is clicked.

```html
<main data-flux="update-link">
	<nav>
		<a href="./04-links.php" data-flux>Landing page</a>
		<a href="./04a-page1.php" data-flux>Page 1</a>
		<a href="./04b-page2.php" data-flux>Page 2</a>
	</nav>
</main>
```

That means the `<main>` element refreshes for Flux links, but not for ordinary Flux form submissions inside the page.

There's also `data-flux="update-link-inner"` if we want to keep the outer element and replace only its contents.

## Mixing link navigation with forms

The link example deliberately mixes both behaviours on the same page:

- the page shell uses `update-link`
- the small cards use `update-inner`
- the scratchpad `<textarea>` sits outside both targets

This lets us preserve some state across navigation while still allowing local in-page updates.

## Scrolling and browser history

Flux scrolls to the top after link navigation and pushes a history state for the fetched URL. If the browser `popstate` event fires, Flux reloads the document so the back and forward buttons do not leave us with stale partial state.

Flux also stores the scroll position for each Flux link entry:

- when we follow a Flux link, the new page is stored at the top
- when we press Back, Flux restores the previous page's scroll position
- when we press Forward again, Flux restores the link destination to the top

This keeps Flux link navigation close to the behaviour we expect from ordinary browser navigation, while still allowing part of the page to stay outside the update target.

By default, Flux restores scroll positions immediately. To make link scrolling and history restoration smooth, add `data-flux-scroll="smooth"` to the element whose scroll position should be managed:

```html
<main data-flux="update-link" data-flux-scroll="smooth">
	<nav>
		<a href="/reports" data-flux>Reports</a>
	</nav>
</main>
```

Flux uses the nearest `data-flux-scroll` ancestor of the clicked link. If that element is a normal page wrapper, Flux scrolls that element. If the attribute is on `<body>` or `<html>`, Flux scrolls the window instead, which is useful for page-wide behaviour.

`data-flux-scroll="auto"` keeps the immediate behaviour. This means we can make one scrolling panel smooth without changing the rest of the page.

> [!INFO]
> Forms whose `<form>` element has an `action` attribute are also treated as navigation-style responses, so they use the link document handler and update history as well.

> [!INFO]
> While a Flux link request is in flight, Flux adds the class `flux-link-waiting` to both the clicked link and the page `<body>`. We can style global navigation loading states, or just the active link, with that class in CSS.

---

With links working, we can learn about [[live updates]] that keep elements constantly up to date.


Live regions let us keep server-rendered HTML fresh by polling the current page URL in the background.

[`example/05-live-clock.php`](https://github.com/PhpGt/Flux/blob/master/example/05-live-clock.php) shows the pattern with a clock that is rendered on the server and refreshed every second.

## The simplest live region

```html
<time data-flux="live">12:00:00</time>
```

`data-flux="live"` is shorthand for `data-flux="live-outer"`, so the whole `<time>` element is replaced each time the poll runs.

## Replace only the contents

If we want to keep the container and refresh only its children, we can use `live-inner`:

```html
<div data-flux="live-inner">
	<strong>Waiting for the next refresh...</strong>
</div>
```

## Control the polling rate

Each live element can define its own interval in seconds:

```html
<time data-flux="live" data-flux-rate="5">12:00:00</time>
```

If we omit `data-flux-rate`, Flux uses one second.

## How polling behaves

Flux maintains a single polling scheduler even if there are several live targets on the page. It works out which targets are due, fetches the current document once, then applies updates only to those live targets.

That keeps the behaviour simple:

- one current page URL
- one background fetch per due poll
- multiple live targets refreshed from the same returned document

## Live targets survive page updates

If a larger Flux update replaces a container that contains a live region, Flux reinitialises the new live element and keeps polling.

## What about WebSockets, or Server-Sent Events?

The functionality of `data-flux="live"` is currently poll-only, by design.

The purpose of Flux is to introduce fluid user experience without changing server-side code.

When responses are zipped from the server (any modern web server will automatically zip responses), there is little benefit to streaming individual elements' HTML changes via WebSockets or Server-Sent Events, because for the few bytes that are saved, there has to be one individual socket connection left open per visitor, which requires more effort to scale well.

If there's a demand for any other type of live update, [please open an issue on GitHub](https://github.com/phpgt/Flux/issues) or cast your vote on an already open issue.

---

The remaining directives are smaller but still useful. Next we will cover `autosave`, `submit`, and attribute-only refreshes in [[autosave and background submits]].


By this point we have covered the main interaction patterns. This page fills in the remaining public directives that we use to fine-tune how requests are triggered and how targets are refreshed.

## `data-flux="submit"` on buttons

We have already used this directive in earlier examples, but it is worth stating the rule plainly: `submit` belongs on a `<button>` inside a form.

```html
<form method="post" data-flux="update-inner">
	<input name="title" />
	<button name="do" value="save" data-flux="submit">Save</button>
</form>
```

When clicked, Flux submits the containing form in the background and includes the clicked button's name and value in the `FormData`.

## `data-flux="autosave"` on buttons

Autosave also belongs on a `<button>`, but the behaviour is different:

```html
<form method="post" data-flux="update-inner">
	<label>
		<span>Title</span>
		<input name="title" />
	</label>
	<button name="do" value="save" data-flux="autosave">Save</button>
</form>
```

Flux hides the autosave button with its injected stylesheet, then listens for changes within the form. When a field changes, Flux submits the form automatically using that button's name and value.

This takes our plain HTML save button and converts it to an automatic autosave when JavaScript is running.

## Attribute-only refreshes

Sometimes the content of an element doesn't need changing, but the element's attributes do. For that, we can use `update-attributes`:

```html
<button	data-flux="update-attributes" disabled aria-busy="true">Save</button>
```

When Flux processes the returned document, it removes attributes that no longer exist and applies the fresh attribute set from the matching element.

This is useful for state such as:

- `disabled`
- `aria-*`
- `class`
- `data-*`

## Combining directives across the page

It's normal to combine several directives in one interface:

- a button with `submit`
- a wrapper with `update-inner`
- a status badge with `update-attributes`
- a live clock elsewhere on the page

Flux treats each registered target according to the response type it is handling.

---

Next up, add drag and drop ordering of lists with [[drag order]].

An HTML list of items could have an HTML form containing an `order` input to reorder the list. Flux can automatically convert this server-rendered form into a drag-and-drop list that works on touch or pointer devices.

The server remains responsible for storing and rendering the order. Flux only provides the browser interaction: it hides the manual order controls, adds a drag handle, moves the item in the DOM while dragging, and submits the existing form in the background when the item is dropped.

## Server-side contract

Each sortable item should contain:

- `data-flux="drag-order"` on the sortable item
- a form inside the sortable item
- an input named `order`
- a submit button

The `order` input uses a zero-based position. If the user drags an item to the first position, Flux submits `order=0`; if they drag it to the fourth position, Flux submits `order=3`.

```html
<ul data-flux="update">
	<li data-flux="drag-order">
		<form method="post">
			<input type="hidden" name="id" value="1" />

			<label>
				<span>Move to order</span>
				<input type="number" name="order" />
				<button name="do" value="move">Move</button>
			</label>
		</form>

		<span>one</span>
	</li>
</ul>
```

Without JavaScript, the user can type a zero-based number into the `order` input and press the button. With Flux running, those controls are hidden and replaced with a `.drag-handle` element inside the form, while the sortable host element is what actually moves in the DOM.

## PHP example

The server should treat the submitted order as the source of truth:

```php
$doAction = $_POST["do"] ?? null;
$id = filter_input(INPUT_POST, "id", FILTER_VALIDATE_INT);
$newOrder = filter_input(INPUT_POST, "order", FILTER_VALIDATE_INT);

if($doAction === "move" && isset($items[$id])) {
	$index = array_search($id, $order, true);

	unset($order[$index]);
	$order = array_values($order);

	$newOrder = max(0, min(count($items) - 1, $newOrder ?? 0));
	array_splice($order, $newOrder, 0, [$id]);

	$_SESSION["drag-order"] = $order;

	header("Location: $_SERVER[SCRIPT_NAME]");
	exit;
}
```

The full working version is in [example/06-drag-order.php](https://github.com/PhpGt/Flux/blob/master/example/06-drag-order.php).

## Page updates

Add an update target around the list:

```html
<ul class="drag-drop" data-flux="update">
	<!-- sortable items -->
</ul>
```

Flux moves the dragged item immediately for responsiveness, then submits the form. The returned HTML document refreshes the list from the server-rendered order.

## Touch support

`drag-order` works with mouse, pen, and touch input. Touch dragging uses Pointer Events and tracks movement on the document while a drag is active, so the drag keeps working even when the finger moves away from the handle.

---

To keep users from firing repeated requests too quickly, we can add throttling with [[rate limiting]].


Flux supports rate limiting for clicking buttons and links too frequently. The same attribute also sets the polling interval for live elements. This is useful when we want to prevent accidental double clicks, stop a frequently pressed control from sending requests too quickly, or slow a polling region down.

## Rate limit a submit button

```html
<button name="do" value="save" data-flux="submit" data-flux-rate="1">
	Save
</button>
```

Here we allow one request per second from that button.

## Rate limit a link

```html
<a href="/dashboard" data-flux="link" data-flux-rate="2">Dashboard</a>
```

This allows one navigation every two seconds from that link element.

## Slow down a live element

```html
<time data-flux="live" data-flux-rate="5">12:00:00</time>
```

Here the same attribute means the live region polls every five seconds.

## How it works

Flux stores the last trigger time per element and ignores interactions that arrive inside the defined time window. The key is based on the element's DOM path, so the limit follows the control itself rather than the URL.

## What rate limiting does not do

- it does not replace server-side validation or idempotency checks
- it does not queue requests for later
- it does not apply to plain forms or links unless a Flux button or Flux link is involved

---

In the final topic, we will learn how Flux can cooperate with our own JavaScript and how to inspect what it is doing. Continue to [[JavaScript hooks and debugging]].


Flux is deliberately small, but it still needs to cooperate with any JavaScript we add ourselves.

## Event listeners are reattached after swaps

Internally, Flux wraps `addEventListener` so it can keep a record of listeners attached to elements. When a Flux update replaces an element, Flux reattaches those listeners to the matching new element.

That means code like this continues to work after a refresh:

```js
const button = document.querySelector("button.tracker");
button.addEventListener("click", () => {
	console.log("tracked");
});
```

As long as the new document contains the corresponding replacement element, Flux carries the listener over.

## New Flux elements are initialised automatically

If an update inserts new elements containing `data-flux`, Flux scans and initialises them as part of the replacement process. This is particularly important for:

- nested submit buttons
- new Flux links
- live regions introduced by an update

## Enable debug logging

When we are working on Flux itself, or trying to understand a tricky page, we can enable debug mode:

```js
import { FluxDebug } from "@phpgt/flux";
import "@phpgt/flux";
```

With debug mode enabled, Flux logs extra detail about event registration, target storage, and focus restoration.

## Failure behaviour

If Flux cannot process a returned document properly, it logs an error and reloads the page. The most common reason would be a response that is not a complete HTML document.

> [!IMPORTANT]
> Flux is designed around full HTML responses. If we return a fragment with no `<head>`, Flux treats that as an error and falls back to a normal reload.

## Testing the behaviour

This repository includes two useful test layers:

- `vitest` unit tests for the JavaScript classes in `src/`
- `behat` browser tests for the runnable examples in `example/`

The browser suite is the best source of truth for end-to-end behaviour because it exercises the real DOM update flow.

---

The walkthrough is complete. See the [[list of flux attributes]] as the reference sheet, or browse the runnable [[examples]].


This page is the reference sheet for every public Flux directive and attribute. The rest of the guide introduces them gradually, but it's useful to have them listed here in one place.

## `data-flux`

### `data-flux` on a `<form>`

Shorthand for an automatic Flux container. Flux listens for the form's `submit` event and submits it in the background.

```html
<form method="post" data-flux>
	<button name="do" value="save">Save</button>
</form>
```

### `data-flux` on an `<a>`

Shorthand for `data-flux="link"`.

```html
<a href="/next-page" data-flux>Next page</a>
```

### `data-flux` on a `<button>`

Shorthand for `data-flux="submit"`.

```html
<button name="do" value="save" data-flux>Save</button>
```

### `data-flux="update"` and `data-flux="update-outer"`

Replace the whole element with the matching element from the returned HTML document.

### `data-flux="update-inner"`

Keep the element itself, but replace its contents with the matching element's contents from the returned document.

### `data-flux="update-link"`

Apply an outer replacement only for Flux link navigation.

### `data-flux="update-link-inner"`

Apply an inner replacement only for Flux link navigation.

### `data-flux="live"` and `data-flux="live-outer"`

Poll the current page URL and replace the whole element on each refresh.

### `data-flux="live-inner"`

Poll the current page URL and replace only the contents of the element.

### `data-flux="update-attributes"`

Refresh just the element attributes from the matching element in the returned document.

### `data-flux="submit"`

Attach background submission to the containing `<button>`'s form.

### `data-flux="link"`

Attach background navigation to an anchor element.

### `data-flux="autosave"`

Attach change-driven background submission to the containing form. This directive must be placed on a `<button>`, and Flux hides that button automatically.

```html
<form method="post">
	<input name="title" />
	<button name="do" value="save" data-flux="autosave">Save</button>
</form>
```

### `data-flux="drag-order"`

Enhance a server-rendered ordering form into a drag-and-drop control. This directive can be placed either on the sortable item or on the `<form>` inside it.

Flux expects the sortable host to contain a form with:

- an `input` named `order`
- a `button` named `do`

```html
<ul data-flux="update">
	<li data-id="1" data-flux="drag-order">
		<form method="post">
			<input type="hidden" name="id" value="1" />
			<label>
				<span>Move to order</span>
				<input type="number" name="order" />
				<button name="do" value="move">Move</button>
			</label>
		</form>
		<span>one</span>
	</li>
</ul>
```

Flux hides the `order` input, the `do` button, and any containing labels, then adds a `.drag-handle` element. When the item is dropped, Flux writes the zero-based position into `order` and submits the form in the background.

## Rate and timing attributes

### `data-flux-scroll`

Control how Flux restores scroll positions during link navigation and browser history navigation.

This attribute can be placed on the scrolling element that contains a Flux link:

```html
<section data-flux-scroll="smooth">
	<a href="/reports" data-flux>Reports</a>
</section>
```

Supported values are:

- `auto` - restore scroll positions immediately
- `smooth` - restore scroll positions with smooth browser scrolling

Flux uses the nearest `data-flux-scroll` ancestor of the clicked link. On ordinary elements, Flux stores and restores that element's own `scrollTop` and `scrollLeft`. On `<body>` or `<html>`, Flux stores and restores the window scroll position, which gives page-wide behaviour.

### `data-flux-rate`

Control how often a Flux interaction can happen. On buttons and links it throttles requests, and on live elements it sets the polling interval.

```html
<button data-flux="submit" data-flux-rate="1">Save</button>
<a href="/news" data-flux="link" data-flux-rate="2">Refresh</a>
<time data-flux="live" data-flux-rate="5">12:00:00</time>
```

The values are in seconds.

On live elements, omitting `data-flux-rate` leaves Flux using a one-second interval.

## Matching rule

If a Flux element has an `id` attribute, the matching `id` of subsequent responses will be used when replacing. However, flux **does not require you to add an `id` to elements** that need replacing. Instead, it records the current element's path through the DOM and looks up the element at that same path in the new document.

> [!IMPORTANT]
> When we return a fresh HTML document from the server, the structure around Flux targets should stay consistent enough for Flux to find the matching element in the same place.

---

If you want the walkthrough version of the docs rather than the reference sheet, go back to [[your first Flux form]] or continue on to [[examples]].


The examples directory is the practical companion to this guide. Each page exists to demonstrate a specific Flux behaviour in a real browser.

## Example list

- [example/01-counter.php](https://github.com/PhpGt/Flux/blob/master/example/01-counter.php): a minimal background form submission with preserved textarea state
- [example/02-list.php](https://github.com/PhpGt/Flux/blob/master/example/02-list.php): `update-inner` on a form containing a dynamic list
- [example/03-multiple-forms.php](https://github.com/PhpGt/Flux/blob/master/example/03-multiple-forms.php): several targets refreshed from the same response
- [example/04-links.php](https://github.com/PhpGt/Flux/blob/master/example/04-links.php): link navigation mixed with local card updates
- [example/04a-page1.php](https://github.com/PhpGt/Flux/blob/master/example/04a-page1.php): first linked page for the navigation demo
- [example/04b-page2.php](https://github.com/PhpGt/Flux/blob/master/example/04b-page2.php): second linked page for the navigation demo
- [example/05-live-clock.php](https://github.com/PhpGt/Flux/blob/master/example/05-live-clock.php): live polling with `data-flux-rate`
- [example/06-drag-order.php](https://github.com/PhpGt/Flux/blob/master/example/06-drag-order.php): server-rendered list ordering enhanced with `data-flux="drag-order"`

## Browser tests

The Behat features mirror those examples closely:

- [test/behat/01-counter.feature](https://github.com/PhpGt/Flux/blob/master/test/behat/01-counter.feature)
- [test/behat/02-list.feature](https://github.com/PhpGt/Flux/blob/master/test/behat/02-list.feature)
- [test/behat/03-multiple-forms.feature](https://github.com/PhpGt/Flux/blob/master/test/behat/03-multiple-forms.feature)
- [test/behat/04-links.feature](https://github.com/PhpGt/Flux/blob/master/test/behat/04-links.feature)
- [test/behat/05-live-clock.feature](https://github.com/PhpGt/Flux/blob/master/test/behat/05-live-clock.feature)
- [test/behat/06-drag-order.feature](https://github.com/PhpGt/Flux/blob/master/test/behat/06-drag-order.feature)

These tests are especially useful when we want to confirm the intended behaviour of a directive before changing the library.

## Running the suites

```bash
npm test
composer behat
```

The unit tests cover the JavaScript classes directly, while the Behat suite verifies that the examples behave correctly in a browser.

---

## Next up

If we want the full directive list in one place, finish with [[List of flux attributes]]. Otherwise, head back to [[Home]] and follow the guide again from the beginning.




---

# Documentation: GtCommand

`phpgt/gtcommand` provides the `gt` command used throughout PHP.GT projects to create applications, scaffold files, and run common development tasks from one place.

Most of the time we do not think about this package on its own. We use `gt create` to start a new WebEngine application, `gt add` to add files to it, and `gt run` while developing locally. This component is the layer that ties those workflows together.

> [!NOTE]
> In WebEngine projects, this package is the command-line entry point for several other PHP.GT components. Commands such as `gt serve`, `gt build`, `gt cron`, and `gt migrate` are provided by this repository, but they are powered by separately maintained packages.

## What this library covers

- Creating a new WebEngine application from a blueprint.
- Adding page, API, and cron files from built-in or project templates.
- Running PHP and JavaScript test suites from one command when the project exposes `test` scripts.
- Running the local development server on its own or alongside build and cron watchers.
- Exposing the Build, Cron, Database migration, and Server CLI commands through one entry point.
- Giving WebEngine projects a consistent `gt ...` workflow instead of several separate `vendor/bin/...` commands.

## A small example

Once the command is available on the shell, a typical beginner workflow looks like this:

```bash
gt create blog --namespace Blog
cd blog
gt add page about
gt run
```

That sequence creates a new WebEngine application, adds a page pair at `page/about.html` and `page/about.php`, then starts the local development processes needed to work on the project.

If `gt` is not on your `PATH`, the same commands can usually be run with `vendor/bin/gt`.

---

To get from zero to a running project, continue with the [[Quick start guide]].


In this guide we will create a small WebEngine application, add one page, and run it locally with the `gt` command.

> [!TIP]
> If you are using WebEngine already, this guide is really a tour of the command-line workflow that the framework expects. The same `gt` command is how WebEngine exposes serving, building, cron, and migration tasks.

## 1. Make the command available

Most often, `gt` comes from the project itself or from a PHP.GT setup tool that places it on your shell `PATH`.

If you are working in a Composer project and `gt` is not available globally, use:

```bash
vendor/bin/gt help
```

Throughout the rest of this guide we will write `gt ...`, but `vendor/bin/gt ...` works in the same way.

## 2. Create a new application

```bash
gt create blog --namespace Blog
```

This command creates a new directory called `blog`, asks Composer to install a WebEngine blueprint into it, and then updates the project's dependencies.

If you leave out `blog` or `--namespace Blog`, the command will ask for them interactively.

If you want the minimal scaffold explicitly, use `gt create blog --empty`. That option also fixes the namespace to the default `App` value.

## 3. Move into the project directory

```bash
cd blog
```

From this point on, `gt` works against the current project directory.

## 4. Add a page

```bash
gt add page about
```

That creates:

```text
page/
├── about.html
└── about.php
```

The starter files come from this package's built-in templates. The HTML file contains a heading and paragraph, and the PHP file contains an empty `go()` function ready for page logic.

## 5. Run the project

```bash
gt run
```

By default, this starts the local web server and, where relevant, also starts the build watcher and cron watcher. The default URL is:

```text
http://localhost:8080
```

Open that address in your browser and then visit `/about` to see the page you added.

## 6. Make another change

For example:

```bash
gt add api status
gt add cron cleanup
```

That gives you an API endpoint and a cron script scaffold using the same beginner-friendly workflow.

At that point you have the core shape of a PHP.GT command-line workflow: create a project, add files from templates, and run the local development processes through one command.

---

Next, move on to [[Adding files with gt add]] to see how templating and file generation work in more detail.


`gt add` is the scaffolding command. It creates starter files for common WebEngine project types so we do not have to remember the exact directory structure or write the initial boilerplate by hand.

## What it can create

The command currently supports three types:

- `page`
- `api`
- `cron`

Basic usage:

```bash
gt add type name [template]
```

Examples:

```bash
gt add page about
gt add api status
gt add cron cleanup
```

## What files get created

### Pages

```bash
gt add page about
```

Creates:

```text
page/about.html
page/about.php
```

The built-in page template contains a heading and paragraph in the HTML file, and an empty `go()` function in the PHP file.

### APIs

```bash
gt add api status
```

Creates:

```text
api/status.php
api/status.json
```

This gives us a PHP handler and a starter JSON Schema file describing request and response shapes.

### Cron scripts

```bash
gt add cron cleanup
```

Creates:

```text
cron/cleanup.php
```

That file contains a starter `go()` function that can be called from a `crontab` entry.

## How names are validated

The `name` part may contain:

- letters
- numbers
- hyphens
- underscores

If another character is used, the command stops with an error rather than creating awkward or invalid paths.

## Built-in templates

When no template name is supplied, `gt add` copies files from this package's own template directory:

- `src/Template/page/template.html`
- `src/Template/page/template.php`
- `src/Template/api/template.php`
- `src/Template/api/template.json`
- `src/Template/cron/template.php`

Any `{{name}}` placeholder inside those template files is replaced with the name passed on the command line.

## Project templates

If a template name is supplied, `gt add` looks in the current project instead of using the built-in files.

For example:

```bash
gt add page about marketing
```

This looks for files matching:

```text
page/_template/marketing.*
```

If `marketing.html` and `marketing.php` exist there, they will be copied to:

```text
page/about.html
page/about.php
```

The same pattern works for the other supported types:

- `api/_template/<template>.*`
- `cron/_template/<template>.*`

This is a useful way to keep team-specific starter files in the project itself.

## A few practical details

- The destination directory such as `page/`, `api/`, or `cron/` is created automatically if it does not already exist.
- Existing destination files are never overwritten.
- If a named project template does not exist, the command stops and explains which directory it checked.

> [!NOTE]
> In WebEngine, `gt add page ...` maps directly onto the framework's page conventions: HTML view in `page/`, matching PHP logic in `page/`, and a URI derived from the filename. That is why this command is such a common starting point in new projects.

---

Next, continue with [[Creating a new WebEngine application]] if you want to see how `gt create` bootstraps a whole project rather than just individual files.


`gt create` starts a complete WebEngine application from a blueprint. It is the fastest way to go from an empty directory to a runnable project.

## Basic usage

```bash
gt create [projectName] [--namespace|-n NAMESPACE] [--blueprint|-b BLUEPRINT] [--empty|-e]
```

Example:

```bash
gt create blog --namespace Blog --blueprint hello-world
```

If `projectName`, `--namespace`, or `--blueprint` are omitted, the command can ask for them interactively.

If you want the minimal project scaffold, `--empty` is a shortcut for `--blueprint empty` and forces the namespace to `App`.

Example:

```bash
gt create blog --empty
```

## Step by step

Internally, the command:

1. validates the project directory name
2. validates the PHP namespace
3. chooses a blueprint
4. runs `composer create-project` for that blueprint
5. runs `composer update` inside the new project directory
6. offers to run the new application immediately

That means the command is more than a file copier: it is a guided project bootstrap process.

## Available blueprints

At the time of writing, the built-in blueprint list is:

- `empty`
- `hello-world`
- `hello-you`
- `todo-list`
- More coming soon...

These are shown interactively with titles and descriptions if you do not pass `--blueprint`.

If you know you want the `empty` blueprint, `--empty` is a synonym for `--blueprint empty`.

## Choosing a project name

The project name becomes the directory name created in the current working directory.

Valid names may contain:

- letters
- numbers
- underscores
- hyphens

If a file or directory with that name already exists, the command stops before doing any work.

## Choosing a namespace

The namespace is the root PHP namespace for the generated application.

Example:

```bash
gt create blog --namespace Blog
```

That keeps the project's classes under `Blog\...` rather than a generic default.

If you omit the namespace interactively, the command suggests `App`.

If you pass `--empty`, the namespace is set to `App` even if `--namespace` is also provided.

## Running the new application straight away

After the blueprint has been installed successfully, `gt create` asks whether you would like to run the new application immediately.

If you answer yes, it changes into the new project directory and runs the same local development flow as `gt run`.

If you answer no, it leaves the new application on disk and prints the WebEngine getting-started link.

## When to use a blueprint

Blueprints are most useful when:

- you are learning WebEngine and want a working example to start from
- your team has settled on a common starting point for new applications
- you want a more guided introduction than a completely empty project gives

The `empty` blueprint is a good option when you want the framework structure without any extra demonstration code.

---

To see what happens after the project is created, move on to [[Running a project locally]].


`gt test` runs the test suites configured in your project metadata and gives you one result summary at the end.

## Basic usage

```bash
gt test
```

The command looks for common `test` scripts and runs each suite it finds.

At the moment that means:

- `composer.json` with a `scripts.test` entry, which runs as `composer test`
- `package.json` with a `scripts.test` entry, which runs as `npm run test`

Both suites are optional. If both are configured, `gt test` runs both of them even if the first one fails.

## Typical examples

If your `composer.json` contains:

```json
{
  "scripts": {
    "test": "vendor/bin/phpunit"
  }
}
```

then `gt test` will run:

```bash
composer test
```

If your `package.json` contains:

```json
{
  "scripts": {
    "test": "vitest run"
  }
}
```

then `gt test` will also run:

```bash
npm run test
```

## Exit behaviour

- returns success when every discovered test suite passes
- returns failure when any discovered test suite fails
- returns failure when no supported test suites are configured

That makes it suitable for local development and for CI steps that want one command to cover both PHP and JavaScript tests.

---

For the full command list, continue with [[Command reference]].


Once a project exists, the commands most people use day to day are `gt run` and `gt serve`.

`gt serve` starts only the local web server.  
`gt run` starts the server and, where appropriate, the other long-running development processes alongside it.

## `gt serve`

Basic usage:

```bash
gt serve [--port|-p PORT] [--bind|-b BIND] [--threads|-t THREADS] [--debug|-d]
```

Examples:

```bash
gt serve
gt serve --port 8081
gt serve --bind 127.0.0.1 --port 9000
gt serve --debug
```

This command is the simplest way to serve a WebEngine project locally.

Useful options:

- `--port` changes the port number
- `--bind` changes the host or interface to bind to
- `--threads` changes the worker count used by the underlying server command
- `--debug` enables debug output in the server layer

## `gt run`

Basic usage:

```bash
gt run [--port|-p PORT] [--bind|-b BIND] [--debug|-d] [--no-build] [--no-cron]
```

Examples:

```bash
gt run
gt run --port 8081
gt run --no-build
gt run --no-cron
```

`gt run` is intended as the normal local development command.

### `gt run` combines multiple commands

When running `gt run`, it also starts:

- `gt build --watch`, unless `--no-build` is supplied
- `gt cron --watch`, if a `crontab` file exists and `--no-cron` is not supplied

That gives us one foreground command for the usual WebEngine development setup.

### Default local URL

With the default settings, the command prints:

```text
http://localhost:8080
```

Even though the default bind value is `0.0.0.0`, the displayed browser URL is normalised to `localhost` for convenience.

### When to prefer `run` over `serve`

Use `gt run` when:

- you want asset builds to keep running while you work
- your project uses a `crontab` during development
- you would rather not think about several separate terminal windows

Use `gt serve` when:

- you only need the web server
- you are debugging one part of the stack at a time
- another tool is already handling asset builds

---

Next, see [[Build, cron, and migrate commands]] for the commands that `gt` exposes from the wider PHP.GT toolchain.


Several `gt` commands are thin wrappers around other PHP.GT packages. That is useful because it gives us one consistent command surface in WebEngine projects, even though the underlying work belongs to specialised components.

## `gt build`

Basic usage:

```bash
gt build [--watch|-w] [--config|-c CONFIG] [--default|-d DEFAULT] [--mode|-m MODE]
```

Examples:

```bash
gt build
gt build --watch
gt build --mode production
```

This command delegates to the PHP.GT Build package.

In a WebEngine project, `gt build` also supplies a default build configuration path of:

```text
vendor/phpgt/webengine/build.default.json
```

That means a project can often start using the build workflow without having to define every detail immediately.

For a full explanation of build configuration, modes, and watch behaviour, see the Build docs at https://www.php.gt/docs/build/.

## `gt cron`

Basic usage:

```bash
gt cron [file] [--watch|-w] [--validate] [--now]
```

Examples:

```bash
gt cron
gt cron --watch
gt cron --validate
```

This command delegates to the PHP.GT Cron package.

Typical uses:

- run any cron jobs that are due right now
- keep a watcher running during local development
- validate a `crontab` file without executing anything

If your project has a `crontab` file, `gt run` can start the watcher automatically.

For the full scheduling syntax and runtime behaviour, see the Cron docs at https://www.php.gt/docs/cron/.

## `gt migrate`

Basic usage:

```bash
gt migrate [--base-directory BASE-DIRECTORY] [--driver DRIVER] [--database DATABASE] [--host HOST] [--port PORT] [--username USERNAME] [--password PASSWORD] [--force|-f] [--reset|-r RESET]
```

Examples:

```bash
gt migrate
gt migrate --force
gt migrate --reset 3
```

This command delegates to the PHP.GT Database migration command.

In WebEngine projects, this is the normal way to apply schema changes. It uses the project's database configuration and migration files rather than requiring you to instantiate migration classes yourself.

Use it when you want to:

- apply the next pending migrations
- rebuild from the start with `--force`
- reset the integrity marker to a specific migration with `--reset`

For the migration model, directory structure, and integrity checks, see:

- https://www.php.gt/docs/database/database-migrations/
- https://www.php.gt/docs/webengine/database/

## `gt deploy`

`gt deploy` exists in the command list, but in this repository it is still a placeholder and does not perform deployment work yet.

It is worth documenting because users will see it in `gt help`, but for now it should be treated as not implemented.

---

If you want the whole command surface in one place, continue with [[Command reference]].


This page collects the current `gt` commands in one place.

Where a command is mainly a wrapper around another PHP.GT component, the command here is still documented from the point of view of someone using `gt` day to day in a WebEngine project.

## Available commands

### `gt add`

Description:

```text
Add a page, API endpoint or cron script from a template
```

Usage:

```text
gt add type name [template]
```

See [[Adding files with gt add]].

### `gt create`

Description:

```text
Create a new WebEngine application
```

Usage:

```text
gt create [projectName] [--namespace|-n NAMESPACE] [--blueprint|-b BLUEPRINT] [--empty|-e]
```

`--empty` is a shortcut for `--blueprint empty` and forces the namespace to `App`.

See [[Creating a new WebEngine application]].

### `gt test`

Description:

```text
Run configured PHP and JavaScript test suites
```

Usage:

```text
gt test
```

`gt test` looks for a `test` script in `composer.json` and `package.json`, then runs `composer test` and `npm run test` for the suites it finds.

See [[Testing a project]].

### `gt run`

Description:

```text
Run all background scripts at once (serve, build, cron)
```

Usage:

```text
gt run [--port|-p PORT] [--bind|-b BIND] [--debug|-d] [--no-build] [--no-cron]
```

See [[Running a project locally]].

### `gt serve`

Description:

```text
Start the inbuilt web server
```

Usage:

```text
gt serve [--port|-p PORT] [--bind|-b BIND] [--threads|-t THREADS] [--debug|-d]
```

See [[Running a project locally]].

### `gt build`

Description:

```text
Compile client-side assets
```

Usage:

```text
gt build [--watch|-w] [--config|-c CONFIG] [--default|-d DEFAULT] [--mode|-m MODE]
```

See [[Build, cron, and migrate commands]].

### `gt cron`

Description:

```text
Start a long-running process to execute each job when it is due
```

Usage:

```text
gt cron [file] [--watch|-w] [--validate] [--now]
```

See [[Build, cron, and migrate commands]].

### `gt migrate`

Description:

```text
Perform a database migration
```

Usage:

```text
gt migrate [--base-directory BASE-DIRECTORY] [--driver DRIVER] [--database DATABASE] [--host HOST] [--port PORT] [--username USERNAME] [--password PASSWORD] [--force|-f] [--reset|-r RESET]
```

See [[Build, cron, and migrate commands]].

### `gt deploy`

Description:

```text
Not yet implemented
```

Usage:

```text
gt deploy
```

At present this command is a placeholder only.




---

# Documentation: Http

# Encapsulated HTTP messages and helpers for PHP.

`phpgt/http` provides the low-level HTTP objects used throughout the PHP.GT ecosystem. It implements the core PSR-7 message interfaces, but it also adds a set of practical helpers around URIs, headers, form bodies, query strings, streams, and HTTP status handling.

If you are new to HTTP libraries in PHP, the important idea is simple: this package gives us PHP objects that represent the same pieces of web traffic the browser and the server already exchange all day long.

That means we can:

- build and inspect `Request` and `ServerRequest` objects
- create and modify `Response` objects
- work with `Uri` objects instead of string slicing
- manage headers in a case-insensitive, iterable way
- convert form and query-string data with browser-style helper objects
- wrap `$_SERVER` metadata in a predictable API
- represent common HTTP errors as dedicated exception classes

## Install the package

```bash
composer require phpgt/http
```

If you are working inside WebEngine, this package is already part of the normal request/response lifecycle.

> [!NOTE]
> If you are building with WebEngine, you will not usually construct every object here by hand. WebEngine uses `RequestFactory` to build the incoming request, passes `Request` and `Response` objects through the application lifecycle, exposes `ResponseHeaders` as a service, and relies on the HTTP status exception classes when generating error responses.

## A small example

```php
use GT\Http\RequestFactory;
use GT\Http\Response;

$request = (new RequestFactory())
	->createServerRequestFromGlobalState(
		$_SERVER,
		$_FILES,
		$_GET,
		$_POST
	);

$response = new Response();
$response = $response
	->withStatus(200)
	->withHeader("Content-Type", "text/plain");

$response->getBody()->write("Hello, " . $request->getMethod());
```

In practice, that means the incoming HTTP request is wrapped in an object you can pass around safely, and the outgoing response is built in the same way.

---

To see how the pieces fit together before diving into the individual classes, continue to the [[Overview]].


HTTP can feel abstract at first because there are a lot of moving parts: methods, URIs, headers, bodies, status codes, and server metadata. This package does not invent any of those ideas, it wraps them in PHP classes so we can work with them directly.

## The main object groups

### Messages

The centre of the package is the PSR-7 message layer:

- `GT\Http\Request`
- `GT\Http\ServerRequest`
- `GT\Http\Response`
- `GT\Http\Stream`
- `GT\Http\Uri`

These are the objects you will use most often.

### Supporting helpers

Around the PSR-7 types there are several supporting classes:

- `GT\Http\RequestFactory` builds a `ServerRequest` from PHP globals.
- `GT\Http\ResponseFactory` picks a response class from the request's `Accept` header.
- `GT\Http\ServerInfo` wraps raw `$_SERVER` data.
- `GT\Http\Header\Headers`, `HeaderLine`, and `Parser` help with header handling.
- `GT\Http\FormData` and `GT\Http\URLSearchParams` mirror familiar browser APIs.
- `GT\Http\Blob`, `File`, and `ArrayBuffer` provide binary and body-data helpers.
- `GT\Http\UriResolver` resolves relative references against a base URI.

### Status exceptions

The `ResponseStatusException` namespaces contain exception classes such as:

- `GT\Http\ResponseStatusException\ClientError\HttpNotFound`
- `GT\Http\ResponseStatusException\ClientError\HttpUnauthorized`
- `GT\Http\ResponseStatusException\ServerError\HttpInternalServerError`

These are useful when application flow should stop with a specific HTTP status.

## Typical usage

In a typical server-side request:

1. PHP gives us raw arrays such as `$_SERVER`, `$_GET`, `$_POST`, and `$_FILES`.
2. `RequestFactory` turns those into a `ServerRequest`.
3. Application code reads from the request, URI, headers, and body.
4. Application code creates or updates a `Response`.
5. The response headers and stream body are sent back to the browser.

```php
use GT\Http\RequestFactory;
use GT\Http\Response;

$request = new RequestFactory()
	->createServerRequestFromGlobalState(
		$_SERVER,
		$_FILES,
		$_GET,
		$_POST
	);

$response = new Response();
$response = $response->withHeader("Content-Type", "text/plain");
$response->getBody()->write("You requested " . $request->getUri()->getPath());
```

## Web-style helper objects

The aim of this library is to deliberately resemble browser APIs as closely as possible.

For example:

- `FormData` can represent form body data and can also be constructed from a DOM `<form>` element.
- `URLSearchParams` handles query-string style key/value pairs.
- `Blob` and `ArrayBuffer` mirror common web platform objects.

This makes the package especially comfortable to use alongside other PHP.GT components, because the mental model stays close to the web platform.

> [!TIP]
> [PHP.GT/Fetch](https://www.php.gt/fetch) uses the classes within this library to implement the Fetch HTTP client in PHP. For example: `$http->fetch("https://example.com", ["body" => new FormData()]);` 

## What to learn first

If you are starting from scratch, focus on these pages in this order:

1. [[Creating requests from global state]]
2. [[Request and ServerRequest objects]]
3. [[Response objects]]
4. [[URI objects]]
5. [[Working with headers]]

Once those are familiar, the rest of the helper classes will make much more sense.

---

Next, we will look at the most common entry point on the server: [[Creating requests from global state]].


On the server, we rarely start with a fully formed request object. We usually start with PHP globals such as `$_SERVER`, `$_FILES`, `$_GET`, and `$_POST`.

`GT\Http\RequestFactory` exists to bridge that gap.

## Why use a factory?

The factory keeps the messy parts of request construction in one place:

- request method validation
- URI construction
- header extraction from `$_SERVER`
- body stream creation
- uploaded file and form/query data wiring

That means the rest of the application can receive one `ServerRequest` object instead of several unrelated arrays.

## Build a `ServerRequest`

```php
use GT\Http\RequestFactory;

$request = new RequestFactory()
	->createServerRequestFromGlobalState(
		$_SERVER,
		$_FILES,
		$_GET,
		$_POST
	);
```

The returned object implements `Psr\Http\Message\ServerRequestInterface`.

## What the factory reads

`RequestFactory` uses the incoming arrays like this:

- `$_SERVER["REQUEST_METHOD"]` becomes the request method.
- `$_SERVER["REQUEST_URI"]`, `HTTP_HOST`, `SERVER_PORT`, `HTTPS`, and `QUERY_STRING` contribute to the URI.
- `$_SERVER["HTTP_*"]` entries become request headers.
- the input stream becomes the request body stream.
- `$_FILES`, `$_GET`, and `$_POST` are attached to the `ServerRequest`.

## A closer look

```php
use GT\Http\RequestFactory;

$factory = new RequestFactory();

$request = $factory->createServerRequestFromGlobalState(
	[
		"REQUEST_METHOD" => "POST",
		"REQUEST_URI" => "/profile/update",
		"HTTP_HOST" => "example.com",
		"SERVER_PORT" => "443",
		"HTTPS" => "on",
		"HTTP_ACCEPT" => "text/html",
		"SERVER_PROTOCOL" => "HTTP/1.1",
	],
	[],
	["tab" => "security"],
	["email" => "dev@example.com"]
);

echo $request->getMethod();           // POST
echo $request->getUri();              // https://example.com/profile/update?tab=security
echo $request->getHeaderLine("Accept"); // text/html
```

## Header names from `$_SERVER`

The factory converts `HTTP_*` entries into header names by removing the prefix and replacing underscores with hyphens.

For example:

- `HTTP_ACCEPT_LANGUAGE` becomes `ACCEPT-LANGUAGE`
- `HTTP_X_FORWARDED_FOR` becomes `X-FORWARDED-FOR`

Headers remain case-insensitive when you read them through the request object.

## Body stream input

By default the factory reads from `php://input`, which matches normal PHP request handling.

For tests or specialised scripts, you can override the body input path:

```php
$request = $factory->createServerRequestFromGlobalState(
	$_SERVER,
	$_FILES,
	$_GET,
	$_POST,
	"/tmp/request-body.txt"
);
```

## Validation

If the request method is missing or invalid, the factory throws `InvalidRequestMethodHttpException`.

That is a good thing. It means broken request state is rejected early, rather than silently spreading through the application.

> [!NOTE]
> In WebEngine, this factory is handled automatically during application start-up. Applications using WebEngine receive an already-built request object rather than calling `RequestFactory` directly.

---

Now that the request exists, the next step is to understand the objects you will read from most often: [[Request and ServerRequest objects]].


`Request` and `ServerRequest` both represent incoming HTTP requests, but they are used at slightly different levels.

- `GT\Http\Request` is the base PSR-7 request message.
- `GT\Http\ServerRequest` extends it with server-side concerns such as cookies, query params, uploaded files, parsed body data, attributes, and server parameters.

If you are writing normal server-side application code, `ServerRequest` is usually the object you will receive.

## `Request`

A `Request` contains three main things:

- the HTTP method
- the target URI
- the headers and body

```php
use GT\Http\Header\RequestHeaders;
use GT\Http\Request;
use GT\Http\Uri;

$request = new Request(
	"GET",
	new Uri("https://example.com/articles?page=2"),
	new RequestHeaders([
		"Accept" => "text/html",
	])
);
```

From there you can read the usual PSR-7 values:

```php
echo $request->getMethod();        // GET
echo $request->getUri()->getPath(); // /articles
echo $request->getRequestTarget();  // /articles?page=2
echo $request->getHeaderLine("Accept");
```

## Immutability

Like PSR-7 objects generally, request methods such as `withMethod()` and `withUri()` return a new object rather than editing the existing one in place.

```php
$secureRequest = $request->withUri(
	$request->getUri()->withScheme("https")
);
```

This pattern is important to get used to early. It keeps request objects predictable and easier to pass around.

## Setting the body

The request body usually holds a `Stream`, but this implementation also accepts `FormData`.

```php
use GT\Http\FormData;

$formData = new FormData();
$formData->append("name", "Cody");

$request = $request->withBody($formData);
```

When you pass `FormData`, the library serialises it and sets `Content-Type: application/x-www-form-urlencoded` if that header is not already present.

## `ServerRequest`

`ServerRequest` adds the data PHP applications usually need:

- `getServerParams()`
- `getCookieParams()`
- `getQueryParams()`
- `getUploadedFiles()`
- `getParsedBody()`
- `getAttributes()`

```php
echo $request->getQueryParams()["page"] ?? 1;
echo $request->getParsedBody()["email"] ?? "";
```

## Uploaded files

Uploaded files are returned as `UploadedFileInterface` objects.

```php
foreach($request->getUploadedFiles() as $name => $uploadedFile) {
	echo $name, ": ", $uploadedFile->getClientFilename();
}
```

This package uses `GT\Input\InputData\Datum\FileUpload` under the hood for those objects.

## Request attributes

Attributes are values attached to the request by application code rather than by the web client.

This is useful for routing, middleware, or any workflow that wants to enrich the request as it moves through the system.

```php
$request = $request->withAttribute("route-name", "article.show");
echo $request->getAttribute("route-name");
```

## Cookies and query params

`ServerRequest` keeps cookie and query helpers separate, which is helpful because they come from different places and should not be confused with each other.

```php
$cookies = $request->getCookieParams();
$query = $request->getQueryParams();
```

---

After the incoming request, the next step is the outgoing [[Response objects]].


`GT\Http\Response` represents the HTTP response your application will send back.

At the PSR-7 level, a response is mostly:

- a status code
- a set of headers
- a body stream

This implementation also adds a few convenience helpers such as `ok`, `status`, `statusText`, `type`, redirect helpers, and body conversion helpers.

## Create a response

```php
use GT\Http\Response;

$response = new Response();
```

You can also pass a status code and headers up front:

```php
use GT\Http\Header\ResponseHeaders;

$response = new Response(
	200,
	new ResponseHeaders([
		"Content-Type" => "text/plain; charset=UTF-8",
	])
);
```

## Status code and reason phrase

```php
$response = $response->withStatus(404);

echo $response->getStatusCode();  // 404
echo $response->getReasonPhrase(); // Not Found
```

The reason phrase is looked up from the built-in `StatusCode` mapping.

## Headers

Headers work through the shared message API:

```php
$response = $response
	->withHeader("Content-Type", "application/json")
	->withAddedHeader("Cache-Control", "no-store");
```

The response also exposes a typed `ResponseHeaders` object through `$response->headers` and `getResponseHeaders()`.

## Writing the body

The response body is a `Stream`, so the most direct pattern is:

```php
$response->getBody()->write("Hello, world");
```

## Convenience properties

The response exposes a few readable helper properties:

- `$response->ok`
- `$response->status`
- `$response->statusText`
- `$response->type`
- `$response->uri`
- `$response->url`

The `uri` and `url` helpers are mainly useful when the response came from `phpgt/fetch`, where they reflect the effective response URL in a browser-style way.

## Redirect helpers

`Response` includes `redirect()`, `reload()`, and `reloadWithoutQuery()`.

```php
$response->redirect("/login", 303);
```

Calling `redirect()` sets the `Location` header and updates the status code. A debug header is also added so the redirect source can be traced more easily during development.

## Reading the body as different data types

If the response body contains text that should be interpreted in a different format, helper methods are available:

- `text()` / `awaitText()`
- `json()` / `awaitJson()`
- `blob()` / `awaitBlob()`
- `arrayBuffer()` / `awaitArrayBuffer()`
- `formData()` / `awaitFormData()`

```php
$json = $response->awaitJson();
$text = $response->awaitText();
```

These helpers are most natural when `Response` objects come from `phpgt/fetch`, but they also work with already-populated response bodies.

> [!NOTE]
> In WebEngine, page logic will manipulate a `Response` object rather than returning or echoing plain strings. The framework then sends the response headers and stream body to the browser at the end of the request lifecycle.

---

[[URI objects]] provide a structured way to work with locations and resource identifiers in HTTP.


`GT\Http\Uri` is the package's PSR-7 URI implementation.

Working with URIs as objects is usually safer than repeatedly splitting strings by `:`, `/`, `?`, and `#`. The object keeps the parts separate and gives you a consistent way to inspect and replace them.

## Create a URI

```php
use GT\Http\Uri;

$uri = new Uri("https://user:pass@example.com:8080/path/123?q=abc#test");
```

Then read whichever part you need:

```php
echo $uri->getScheme();   // https
echo $uri->getAuthority(); // user:pass@example.com:8080
echo $uri->getUserInfo();  // user:pass
echo $uri->getHost();      // example.com
echo $uri->getPort();      // 8080
echo $uri->getPath();      // /path/123
echo $uri->getQuery();     // q=abc
echo $uri->getFragment();  // test
```

## Build a URI gradually

```php
$uri = new Uri()
	->withScheme("https")
	->withHost("example.com")
	->withPath("/articles")
	->withQuery("page=2");
```

As with other PSR-7 objects, each `with...()` method returns a new instance.

## Query helpers

This implementation adds a couple of convenience methods beyond the base PSR-7 interface:

- `getQueryValue()`
- `withQueryValue()`
- `withoutQueryValue()`

```php
$uri = new Uri("https://example.com/search?q=phpgt&page=2");

echo $uri->getQueryValue("q"); // phpgt

$nextPage = $uri->withQueryValue("page", "3");
$withoutPage = $uri->withoutQueryValue("page");
```

## Relative and reference-style URIs

The class supports more than fully qualified HTTP URLs. It also handles:

- relative references such as `./images/logo.svg`
- network-path references such as `//example.org`
- query-only references such as `?page=2`
- fragment-only references such as `#section`

That is useful when your application works with both absolute URLs and relative references in the same codebase.

## Default ports

`isDefaultPort()` tells you whether the port matches the default for the current scheme.

This matters because `https://example.com:443/` and `https://example.com/` usually mean the same endpoint.

## URI resolution

For relative-reference work, `GT\Http\UriResolver` can resolve one URI against another.

```php
use GT\Http\UriResolver;

$base = new Uri("https://example.com/docs/start/");
$relative = new Uri("../api");

$absolute = (new UriResolver())->resolve($base, $relative);
echo $absolute; // https://example.com/docs/api
```

## URI creation from parsed parts

If you already have a `parse_url()` style array, `UriFactory` can turn it back into a `Uri`.

```php
use GT\Http\UriFactory;

$parts = parse_url("https://example.com/a?b=c");
$uri = (new UriFactory())->createFromParts($parts);
```

## Validation

Invalid URIs throw `UriParseErrorException`, and invalid port numbers throw `PortOutOfBoundsException`.

That is helpful because URI mistakes are usually easier to fix at construction time than after they have spread through an application.

---

Requests and responses both rely on headers, so head to the next page covering [[Working with headers]].


Headers are the metadata around an HTTP message. They describe things such as:

- what content type is being sent
- which formats the client accepts
- how caching should behave
- whether cookies should be set

This package provides header helpers at two levels:

- `GT\Http\Header\HeaderLine` represents one named header line
- `GT\Http\Header\Headers` represents a whole collection of header lines

There are also the specialised subclasses:

- `RequestHeaders`
- `ResponseHeaders`

## Create a header collection

```php
use GT\Http\Header\Headers;

$headers = new Headers([
	"Content-Type" => "application/json",
	"Cache-Control" => "no-store",
]);
```

## Case-insensitive access

Header names are case-insensitive, so all of these work the same way:

```php
$headers->contains("content-type");
$headers->contains("Content-Type");
$headers->contains("CONTENT-TYPE");
```

## Add, replace, and remove

```php
$headers->add("Accept", "application/json");
$headers->add("Accept", "application/xml");

$headers->set("Content-Type", "text/plain");
$headers->remove("Cache-Control");
```

`add()` appends values, while `set()` replaces any existing values for that header name.

## Read values

```php
$line = $headers->get("Accept");
echo $line?->getValue();   // first value

$all = $headers->getAll("Accept");
```

`get()` returns a `HeaderLine` or `null`.

`getAll()` returns a flat array of values.

## Iteration

The collection is iterable, so you can inspect every header line:

```php
foreach($headers as $headerLine) {
	echo $headerLine->getName(), ": ", $headerLine, PHP_EOL;
}
```

## `Set-Cookie` is handled specially

Most headers can be combined with commas. `Set-Cookie` is different: each cookie line needs to stay separate.

This collection handles that for you. When multiple `Set-Cookie` values are present:

- `getAll("Set-Cookie")` returns every cookie value separately
- `asArray()` joins them with newlines rather than commas
- `asArray(true)` preserves them as an array

That detail matters because cookies are one of the places where a naive header implementation can lose information.

> [!TIP]
> In WebEngine applications, the [`GT\Cookie\Cookie`](https://www.php.gt/cookie) object is available to us for working with cookies, so there's no need to keep track of the cookie headers ourselves.

## Parsing raw headers

If you have one raw header block as a string, `GT\Http\Header\Parser` can extract:

- the protocol version
- the status code
- key/value pairs

```php
use GT\Http\Header\Parser;

$raw = implode("\n", [
	"HTTP/1.1 200 OK",
	"Content-Type: application/json",
	"Set-Cookie: a=1",
	"Set-Cookie: b=2",
]);

$parser = new Parser($raw);

echo $parser->getProtocolVersion(); // 1.1
echo $parser->getStatusCode();      // 200
print_r($parser->getKeyValues());
```

## Request and response integration

`Request`, `ServerRequest`, and `Response` all use the shared message API:

- `getHeaders()`
- `hasHeader()`
- `getHeader()`
- `getHeaderLine()`
- `withHeader()`
- `withAddedHeader()`
- `withoutHeader()`

That means once you understand headers here, the same reading and writing model applies everywhere in the package.

---

Learn more about the protocol-level background behind the first line and the header fields in [[Parts of the HTTP header]].


Every HTTP message starts with a line that tells us the broad meaning of the message, followed by zero or more header fields.

At a high level, it looks like this:

```text
A B C
X: Y
```

The first line means different things depending on whether the message is a request or a response.

## Request start line

For an HTTP request:

- `A` is the request method, such as `GET` or `POST`
- `B` is the request target, such as `/index.html` or `/api/user?id=5`
- `C` is the protocol version, such as `HTTP/1.1`

Example:

```text
GET /articles?page=2 HTTP/1.1
Host: example.com
Accept: text/html
```

## Response start line

For an HTTP response:

- `A` is the protocol version, such as `HTTP/1.1`
- `B` is the numeric status code, such as `200` or `404`
- `C` is the reason phrase, such as `OK` or `Not Found`

Example:

```text
HTTP/1.1 404 Not Found
Content-Type: text/plain
Content-Length: 9
```

## Header fields

After the start line come the header fields.

- `X` is the header name, such as `Content-Type`
- `Y` is the header value, such as `application/json`

Each header field is one name/value pair:

```text
Content-Type: application/json
Cache-Control: no-store
```

Some header values themselves contain multiple parts. For example:

```text
Accept: text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8
```

That is still one header field. The commas are part of the value syntax.

## A practical mapping to this library

In `phpgt/http`:

- the request start line becomes the request method, target URI, and protocol version on `Request`
- the response start line becomes the status code and protocol version on `Response`
- the header fields are stored in `Headers`, `RequestHeaders`, or `ResponseHeaders`

The `GT\Http\Header\Parser` class can parse a raw response-style header block into:

- protocol version
- status code
- header key/value pairs

## One important exception: `Set-Cookie`

Most repeated headers can be merged safely, but `Set-Cookie` should stay as separate lines.

This library preserves that distinction, which is why cookie headers are treated slightly differently from normal comma-combinable headers.

## Why this matters

Understanding the shape of an HTTP message makes the rest of the library much easier to follow. Once you can recognise the start line, the header fields, and the body as separate concerns, the purpose of `Request`, `Response`, `Headers`, and `Stream` becomes much clearer.

---

Learn about [[FormData and URLSearchParams]] to work with body data more comfortably.


`FormData` and `URLSearchParams` are based on the browser APIs of the same names.

They are both key/value stores, but they represent different kinds of data:

- `FormData` is for form submission style body data, including files and repeated fields
- `URLSearchParams` is for query-string style data

## `FormData`

### Build it manually

```php
use GT\Http\FormData;

$formData = new FormData();
$formData->append("name", "Cody");
$formData->append("interest", "Mathematics");
$formData->append("interest", "Cryptography");

echo (string)$formData;
// name=Cody&interest[]=Mathematics&interest[]=Cryptography
```

### Construct it from a DOM form

`FormData` can be created from a real DOM `<form>` element. When using [PHP.GT/Dom](https://www.php.gt/dom) this gives you a full modern HTMLDocument, just like in the browser:

```php
use GT\Dom\HTMLDocument;
use GT\Http\FormData;

$html = <<<HTML
<form class="example-form">
	<input name="name" value="Cody" />
	<textarea name="message">Hello</textarea>
	<button name="do" value="send">Send message</button>
</form>
HTML;

$document = new HTMLDocument($html);

$form = $document->querySelector(".example-form");
$formData = new FormData($form);
```

The constructor reads named HTMLInputElements from the form.

### Submit buttons

Just like when using FormData in JavaScript, buttons are not included automatically, because only the clicked submitter should contribute its value during a real form submission.

If you want that behaviour, pass the submitter element as the second argument:

```php
$formData = new FormData($form, $button);
```

If the submitter is not part of the form, the constructor throws `HttpException`.

### Files and blobs

`FormData` can hold:

- strings
- `Blob`
- `File`
- `SplFileObject`

If you pass an `SplFileObject`, the library wraps it in a `File` object for you.

### Reading values

```php
$formData->get("name");
$formData->getAll("interest");
$formData->getFile("avatar");
$formData->getBlob("attachment");
```

## `URLSearchParams`

### Construct from a query string

```php
use GT\Http\URLSearchParams;

$params = new URLSearchParams("?page=2&sort=name");

echo $params->get("page"); // 2
echo $params->size;        // 2
```

The leading `?` is optional and ignored.

### Construct from an array

```php
$params = new URLSearchParams([
	"page" => "2",
	"sort" => "name",
]);
```

### Construct from `FormData`

```php
$params = new URLSearchParams($formData);
```

This is useful when you want query-string style output from data you already gathered as form fields.

### Add and remove values

```php
$params->append("filter", "new");
$params->append("filter", "popular");
$params->set("page", "3");
$params->delete("sort");
```

Repeated keys are preserved and serialised with `[]`.

### Iteration helpers

`URLSearchParams` and `FormData` both inherit helpers from `KeyValuePairStore`, including:

- `entries()`
- `forEach()`
- `get()`
- `getAll()`
- `has()`
- `keys()`
- `values()`
- `delete()`
- `sort()`

That means once you learn one of these classes, the other feels familiar.

## Type-safe getters

Both classes also support the nullable type-safe getter helpers used elsewhere in PHP.GT.

For example:

```php
$age = $params->getInt("age");
$name = $formData->getString("name");
```

## When to use which

Use `FormData` when:

- you are representing a form submission
- repeated fields matter
- file values may be present

Use `URLSearchParams` when:

- you are building or reading a query string
- the data belongs in the URI
- you want a compact URL-encoded string

---

The next page covers the body helpers these classes often work alongside: [[Streams, blobs, and binary data]].


HTTP bodies are ultimately just streams of bytes. Sometimes we treat them as text, but underneath they still travel as raw data.

This package includes a few classes that help at different levels:

- `Stream` for PSR-7 body streams
- `Blob` for binary or textual body chunks
- `File` for file-like blob data with a filename
- `ArrayBuffer` for byte-oriented buffer data

## `Stream`

`GT\Http\Stream` is the PSR-7 stream implementation used by requests and responses.

```php
use GT\Http\Stream;

$stream = new Stream("php://memory");
$stream->write("Hello");
$stream->rewind();

echo $stream->getContents();
```

Common methods include:

- `write()`
- `read()`
- `getContents()`
- `rewind()`
- `seek()`
- `tell()`
- `eof()`
- `getSize()`

In everyday use, the most common place you will meet it is through:

```php
$request->getBody();
$response->getBody();
```

## `Blob`

`Blob` collects one or more string-like parts into a single object with:

- `size`
- `type`
- string casting through `__toString()`

```php
use GT\Http\Blob;

$blob = new Blob(
	["Hello", " ", "world"],
	["type" => "text/plain"]
);

echo $blob;       // Hello world
echo $blob->size; // 11
echo $blob->type; // text/plain
```

## `File`

`File` extends `Blob` and adds a `name`.

You can build it from an array of parts, or from an `SplFileObject`.

```php
use GT\Http\File;
use SplFileObject;

$file = new File(
	new SplFileObject("avatar.png"),
	"avatar.png"
);
```

This makes it useful for `FormData` values and file-style payload handling.

## `ArrayBuffer`

`ArrayBuffer` is a fixed-size buffer of bytes.

It is returned by `Response::arrayBuffer()` and `awaitArrayBuffer()`.

```php
$buffer = $response->awaitArrayBuffer();
echo $buffer->byteLength;
```

For most application code, `Blob` and plain text are easier to work with, but `ArrayBuffer` is useful when you need a byte-oriented representation.

## Response body conversions

`Response` provides several helpers that convert the body stream into other object types:

- `awaitText()`
- `awaitJson()`
- `awaitBlob()`
- `awaitArrayBuffer()`
- `awaitFormData()`

This means the same underlying response body can be consumed in the format that best fits the task.

---

The incoming request also carries server-level metadata around it, which is covered in [[ServerInfo and request metadata]].


`GT\Http\ServerInfo` wraps the raw `$_SERVER` array in a readable, predictable object.

This is useful when you need request metadata, but you do not want server variables spread across the whole codebase.

## Why not just read `$_SERVER` directly?

You can, but the drawbacks add up quickly:

- the keys are all-caps strings
- some values may be missing
- related URI and query work is left to you
- the code becomes tightly coupled to PHP superglobals

`ServerInfo` gives us one place to read these values through named methods instead.

> [!NOTE]
> In WebEngine, reading from `$_SERVER` directly is prohibited by [Protected Globals](https://www.php.gt/protectedglobal), but the `ServerInfo` object is constructed automatically, available in the [Service Container](https://www.php.gt/docs/WebEngine/Service-Container).

## Construct it

```php
use GT\Http\ServerInfo;

$serverInfo = new ServerInfo($_SERVER);
```

## Common reads

```php
echo $serverInfo->getRequestMethod();
echo $serverInfo->getServerProtocol();
echo $serverInfo->getRemoteAddress();
echo $serverInfo->getDocumentRoot();
```

## Headers from `$_SERVER`

`getHttpHeadersArray()` extracts the `HTTP_*` values and converts them into header-style names.

```php
$headers = $serverInfo->getHttpHeadersArray();
echo $headers["ACCEPT"] ?? "";
```

## Query-string helpers

```php
$queryString = $serverInfo->getQueryString();
$queryParams = $serverInfo->getQueryParams();

$updated = $serverInfo->withQueryParams([
	"page" => "2",
	"sort" => "name",
]);
```

Like the other immutable-style helpers in this package, `withQueryString()` and `withQueryParams()` return a clone.

## URI helpers

There are two URI-oriented methods:

- `getRequestUri()` for the request target URI
- `getFullUri()` for a fuller absolute URI view

```php
echo $serverInfo->getRequestUri();
echo $serverInfo->getFullUri();
```

These are especially handy when reconstructing absolute URLs from server state.

## HTTPS and ports

```php
if($serverInfo->isHttps()) {
	// secure request
}

$port = $serverInfo->getServerPort();
```

The class also accounts for cases where the host header does not explicitly include the port.

## Nullable values

Some server fields are optional in PHP, so methods such as these may return `null`:

- `getServerName()`
- `getServerSoftware()`
- `getAuthUser()`
- `getAuthPassword()`
- `getRemotePort()`
- `getRequestScheme()`

That makes it easier to handle incomplete server environments safely.

> [!NOTE]
> WebEngine uses HTTP `Request` objects for most day-to-day work, but `ServerInfo` still fits naturally anywhere you need a clear wrapper around raw server metadata, especially in tests or lower-level infrastructure code.

---

Another factory in this package helps choose response classes from the request's `Accept` header. That is covered in [[ResponseFactory and content negotiation]].


`GT\Http\ResponseFactory` creates a response object based on the request's `Accept` header.

This is useful when one application can return different response types depending on what the client asked for.

## The basic idea

Before the factory can build anything, you register which response class should handle which media type.

```php
use GT\Http\Response;
use GT\Http\ResponseFactory;

ResponseFactory::registerResponseClass(Response::class, "text/html");
```

Then call `create()` with a request:

```php
$response = ResponseFactory::create($request);
```

## Why registration is required

The factory does not guess which class to use. It only uses classes that you have explicitly mapped.

If you call `create()` before registering a matching response class, it throws `UnknownAcceptHeaderException`.

That behaviour is intentional. It avoids silently creating the wrong response type.

## Default accept type

If you register a response class without any media types, the factory uses its default accept type:

```php
ResponseFactory::registerResponseClass(MyHtmlResponse::class);
```

That default is `text/html`.

## Negotiation

Internally, the factory uses content negotiation to compare the incoming `Accept` header against a small set of priorities:

- `text/html; charset=UTF-8`
- `application/json`
- `application/xml;q=0.5`

The winning media type is then used to look up the registered response class.

## A simple example

```php
use GT\Http\Request;
use GT\Http\Response;
use GT\Http\ResponseFactory;

class HtmlResponse extends Response {}
class JsonResponse extends Response {}

ResponseFactory::registerResponseClass(HtmlResponse::class, "text/html");
ResponseFactory::registerResponseClass(JsonResponse::class, "application/json");

$response = ResponseFactory::create($request);
```

From there, your application can continue working with the returned response instance as normal.

## When this is useful

`ResponseFactory` is most helpful when:

- the same route can return more than one representation
- you want one response class per media type
- your application needs explicit content negotiation rather than ad hoc `if` statements everywhere

If your project only ever returns one response type, using `new Response()` directly is often simpler.

---

All standard [[HTTP status exceptions]] are covered in this package as helper classes.


This repository includes a set of exception classes representing HTTP status responses.

They live under the `GT\Http\ResponseStatusException` namespaces and are grouped by response category:

- `ClientError`
- `Redirection`
- `ServerError`

## Why use exception classes for HTTP statuses?

Sometimes the clearest way to stop request processing is to throw an exception that already carries the intended HTTP status.

For example:

```php
use GT\Http\ResponseStatusException\ClientError\HttpNotFound;

if(!$article) {
	throw new HttpNotFound("Article not found");
}
```

That expresses intent much more clearly than a plain generic exception.

## Common examples

Client errors:

- `HttpBadRequest`
- `HttpUnauthorized`
- `HttpForbidden`
- `HttpNotFound`
- `HttpMethodNotAllowed`
- `HttpNotAcceptable`
- `HttpTooManyRequests`
- `HttpUnprocessableEntity`

Redirections:

- `HttpMovedPermanently`
- `HttpFound`
- `HttpSeeOther`
- `HttpTemporaryRedirect`
- `HttpPermanentRedirect`

Server errors:

- `HttpInternalServerError`
- `HttpNotImplemented`
- `HttpBadGateway`
- `ServiceUnavailable`
- `HttpGatewayTimeout`

## Base classes

The status exceptions also have shared base types:

- `ResponseStatusException`
- `ClientErrorException`
- `RedirectionException`
- `ServerErrorException`

These are useful when you want to catch a whole category rather than one exact status.

```php
use GT\Http\ResponseStatusException\ClientError\ClientErrorException;

try {
	// ...
}
catch(ClientErrorException $error) {
	// Handle any 4xx style response exception.
}
```

## How the status code is exposed

Each class knows its own HTTP code through `getHttpCode()`.

That means higher-level framework code can catch the exception and turn it into the correct response automatically.

> [!NOTE]
> WebEngine makes direct use of these exception types. If page logic throws one of them, the framework can use the embedded HTTP code when generating the error response.

## When not to use them

These classes are best for application flow that really should become a specific HTTP response.

They are not a substitute for every ordinary domain or validation exception in your codebase. If an error is not really "HTTP 404, Not Found" or "HTTP 403, Forbidden", a normal exception class is usually the better fit.

---

Let's see some [[Examples]] of this library in action.


This page collects a few small examples that show the shape of the library in practice.

## Build a request from globals

```php
use GT\Http\RequestFactory;

$request =new RequestFactory()
	->createServerRequestFromGlobalState(
		$_SERVER,
		$_FILES,
		$_GET,
		$_POST
	);

echo $request->getMethod();
echo $request->getUri()->getPath();
```

## Create a text response

```php
use GT\Http\Response;

$response = new Response();
$response = $response
	->withStatus(200)
	->withHeader("Content-Type", "text/plain; charset=UTF-8");

$response->getBody()->write("Everything is working.");
```

## Redirect to another page

```php
use GT\Http\Response;

$response = new Response();
$response->redirect("/login", 303);
```

## Read and change URI parts

```php
use GT\Http\Uri;

$uri = new Uri("https://example.com/search?q=phpgt&page=1");

$nextPage = $uri->withQueryValue("page", "2");
$withoutQuery = $uri->withQuery("");
```

## Work with headers

```php
use GT\Http\Header\ResponseHeaders;

$headers = new ResponseHeaders();
$headers->add("Cache-Control", "no-store");
$headers->add("Set-Cookie", "theme=light; Path=/");
$headers->add("Set-Cookie", "session=abc123; HttpOnly; Path=/");

print_r($headers->getAll("Set-Cookie"));
```

## Use `FormData`

```php
use GT\Http\FormData;

$formData = new FormData();
$formData->append("name", "Cody");
$formData->append("interest", "Mathematics");
$formData->append("interest", "Cryptography");

echo (string)$formData;
```

## Use `URLSearchParams`

```php
use GT\Http\URLSearchParams;

$params = new URLSearchParams();
$params->append("page", "2");
$params->append("filter", "new");
$params->append("filter", "popular");

echo (string)$params;
```

## Wrap `$_SERVER` in `ServerInfo`

```php
use GT\Http\ServerInfo;

$serverInfo = new ServerInfo($_SERVER);

echo $serverInfo->getRequestMethod();
echo $serverInfo->getFullUri();
```

## Throw an HTTP status exception

```php
use GT\Http\ResponseStatusException\ClientError\HttpNotFound;

if(!$record) {
	throw new HttpNotFound("The requested record does not exist.");
}
```

## Choose a response class from `Accept`

```php
use GT\Http\Response;
use GT\Http\ResponseFactory;

class HtmlResponse extends Response {}
class JsonResponse extends Response {}

ResponseFactory::registerResponseClass(HtmlResponse::class, "text/html");
ResponseFactory::registerResponseClass(JsonResponse::class, "application/json");

$response = ResponseFactory::create($request);
```




---

# Documentation: Input

# Encapsulated and type-safe user input.

The default behaviour of PHP user input is handled globally via superglobals such as `$_GET`, `$_POST`, `$_FILES`, etc. While this approach provides a straightforward method for simple user input data handling, it often encounters limitations, particularly when managing HTTP requests involving multiple fields or files.

This library wraps request input in objects so we can pass around only the data we actually need. It gives us one place to read query string values, form fields, uploaded files, raw request bodies, and JSON payloads, with type-safe getters for the common cases.

> [!TIP]
> After integrating this library, it is recommended to prevent access to superglobals in PHP - see [PHP.GT/ProtectedGlobal](https://PHP.GT/ProtectedGlobal) for an automated solution.
>
> You may want to validate user input on the server - see [PHP.GT/DomValidation](https://PHP.GT/DomValidation) for an automated solution.
>
> This library and associated libraries are all part of [PHP.GT/WebEngine](https://PHP.GT/WebEngine).

## Quick example

```html
<form method="post" enctype="multipart/form-data">
	<label>
		<span>Name</span>
		<input name="name" required />
	</label>

	<label>
		<span>Age</span>
		<input type="number" name="age" />
	</label>

	<label>
		<span>Interests</span>
		<select name="interest[]" multiple>
			<option>Mathematics</option>
			<option>Cryptography</option>
			<option>Information Security</option>
			<option>Cyberwarfare</option>
		</select>
	</label>

	<label>
		<span>Photo</span>
		<input type="file" name="photo" />
	</label>

	<button name="do" value="save">Save profile</button>
</form>
```

```php
use GT\Input\Input;
use GT\Input\InputData\Datum\FailedFileUpload;

function do_save(Input $input, ProfileStore $profiles, int $profileId):void {
	$profiles->update(
		$profileId,
		$input->getString("name"),
		$input->getInt("age"),
	);

	foreach($input->getMultipleString("interest") as $interest) {
		$profiles->addInterest($profileId, $interest);
	}

	$photo = $input->getFile("photo");
	if($photo instanceof FailedFileUpload) {
		throw new RuntimeException($photo->getErrorMessage());
	}

	if($photo) {
		$photo->moveTo("data/upload/$profileId." . $photo->getOriginalExtension());
	}
}
```

---

For projects that don't use WebEngine, or just to familiarise yourself with the library, see [[constructing the Input class]]. 


`Input` is the main entry point to the library. It represents:

- query string data
- request body fields
- uploaded files
- the raw request body stream

In plain PHP, we usually construct it from the PHP superglobals:

```php
use GT\Input\Input;

$input = new Input(
	$_GET,
	$_POST,
	$_FILES,
	"php://input",
	$_SERVER["REQUEST_METHOD"] ?? "GET"
);
```

The fourth argument is the path to the request body stream, which defaults to `"php://input"`. The fifth argument is the HTTP method, which matters when we want to work with `PUT` upload streams.

## Working with a specific part of the request

The same `Input` object can read from different sections of the request. For example:

```php
$page = $input->get("page", Input::DATA_QUERYSTRING);
$search = $input->get("q", Input::DATA_BODY);
$avatar = $input->getFile("avatar");
```

If no method is provided, `Input` reads from the combined request data.

The available method constants are:

- `Input::DATA_QUERYSTRING`
- `Input::DATA_BODY`
- `Input::DATA_FILES`
- `Input::DATA_COMBINED`

## Working with all request data

Sometimes we need the whole input collection rather than a single value:

```php
$all = $input->getAll();
$queryOnly = $input->getAll(Input::DATA_QUERYSTRING);
$bodyOnly = $input->getAll(Input::DATA_BODY);
$filesOnly = $input->getAll(Input::DATA_FILES);
```

These calls return `InputData` objects, which are iterable, countable, array-accessible, and can also use the same type-safe getters as `Input`.

## Usage within WebEngine

In WebEngine applications we do not usually construct `Input` ourselves. The framework puts it in the service container and injects it into `go()` and `do_*()` functions for us:

```php
use GT\Input\Input;

function do_save(Input $input, ProfileStore $profiles):void {
	$profiles->saveName($input->getString("name"));
}
```

That means the same API works whether we are writing a standalone PHP script or a WebEngine application.

---

Next: [[Type-safe getters]]


All request data arrives over HTTP as text, but application code usually expects something more specific. `Input` and `InputData` both provide type-safe getters so we can read values in the type our code expects.

## Available getters

### Single values

- `getString(string $key): ?string`
- `getInt(string $key): ?int`
- `getFloat(string $key): ?float`
- `getBool(string $key): ?bool`
- `getDateTime(string $key, ?string $format = null): ?DateTimeInterface`
- `getFile(string $key): ?FileUpload`

### Multiple values

- `getMultipleString(string $key): array`
- `getMultipleInt(string $key): array`
- `getMultipleFloat(string $key): array`
- `getMultipleBool(string $key): array`
- `getMultipleDateTime(string $key): array`
- `getMultipleFile(string $key): array`

## Nulls and empty values

Single-value getters return `null` when the key does not exist.

For numeric, boolean, and date getters, an empty string is also treated as `null`. That is useful for optional form fields where an empty control should not become `0`, `false`, or an invalid date by accident.

## Strings, integers, floats, and booleans

```php
$name = $input->getString("name");
$age = $input->getInt("age");
$height = $input->getFloat("height");
$termsAccepted = $input->getBool("accept-terms");
```

`getBool()` uses normal PHP boolean casting rules. For example, a non-empty string becomes `true`. If we need stricter semantics such as accepting only `"true"` and `"false"`, read the value as a string and validate it explicitly in application code.

For multiple-value controls, use the matching `getMultiple*` getter:

```html
<label><input type="checkbox" name="topping[]" value="mozzarella" /> Mozzarella</label>
<label><input type="checkbox" name="topping[]" value="basil" /> Basil</label>
<label><input type="checkbox" name="topping[]" value="olive" /> Olive</label>
```

```php
foreach($input->getMultipleString("topping") as $topping) {
	$pizza->addTopping($topping);
}
```

PHP requires the square brackets in the field name for repeated values. Without `[]`, PHP will not treat the submitted values as a list.

## Dates and times

`getDateTime()` constructs a `DateTimeInterface` from the input value:

```php
$published = $input->getDateTime("published-at");
```

If the incoming value has a fixed format, we can supply it explicitly:

```php
$date = $input->getDateTime("start-date", "Y-m-d");
```

If a date string exists but cannot be parsed into the requested format, the library throws `DataNotCompatibleFormatException`. That makes invalid date input visible to application code rather than silently producing the wrong value.

## Files

`getFile()` returns a `FileUpload` object, or `null` if that file field was not submitted.

```php
$avatar = $input->getFile("avatar");
if($avatar) {
	echo $avatar->getOriginalName();
}
```

If the form field exists in the body but was sent as plain text rather than as a file upload, `getFile()` throws `DataNotFileUploadException`. That usually means the form is missing `enctype="multipart/form-data"`.

## Choosing the right getter

- Use `getString()` when the value is free-form text or when you want to validate the format yourself.
- Use `getInt()` and `getFloat()` for numeric fields that should already have been constrained by the form or by server-side validation.
- Use `getBool()` when the input represents a true/false choice and you want PHP truthiness semantics.
- Use `getDateTime()` when the value should become a real date object immediately.
- Use `getMultiple*()` for checkbox groups, multi-selects, and repeated file inputs.

---

Next: [[Reading request data and streams]]


`Input` can do more than read HTML form fields. It also gives us access to the raw request body, JSON payloads, and request sections individually.

## Reading a single value

Use `get()` when we want the raw submitted value without converting it:

```php
$search = $input->get("q");
```

By default this reads from the combined request input. If we want to be explicit, we can choose a section of the request:

```php
$page = $input->get("page", Input::DATA_QUERYSTRING);
$token = $input->get("token", Input::DATA_BODY);
```

## Checking whether a key exists

Use `contains()` when the difference between "missing" and "present but empty" matters:

```php
if($input->contains("draft")) {
	// The key exists somewhere in the request.
}
```

There are also section-specific checks:

- `containsQueryStringParameter()`
- `containsBodyParameter()`
- `containsFile()`

## Reading all values at once

`getAll()` returns an `InputData` object:

```php
$all = $input->getAll();
$query = $input->getAll(Input::DATA_QUERYSTRING);
$body = $input->getAll(Input::DATA_BODY);
$files = $input->getAll(Input::DATA_FILES);
```

`InputData` is useful when we want to pass a subset of user input to another class or callback without handing over the whole request object.

## Reading JSON request bodies

If the request body contains JSON, use `getBodyJson()`:

```php
$json = $input->getBodyJson();

if($json) {
	$email = $json->getString("email");
}
```

If the body is not valid JSON, `getBodyJson()` returns `null`.

That makes it a good fit when the request might be JSON but we still want to detect invalid payloads in our own application flow.

## Reading the raw body stream

To work with the raw request body directly, use `getStream()`:

```php
$stream = $input->getStream();

while(!feof($stream)) {
	$chunk = fread($stream, 1024);
	processBodyChunk($chunk);
}
```

This is useful for non-form requests, custom formats, large payloads, or situations where another component expects a PSR-7 stream.

## Reading `PUT` upload streams

For `PUT` requests carrying file data in the body rather than through `multipart/form-data`, use `getPutFileStream()`:

```php
$stream = $input->getPutFileStream();
$fh = fopen("data/upload.bin", "w");
// memory efficient copy from incoming stream to file, for example purposes only (not really that useful in real world situations)
stream_copy_to_stream($stream, $fh);
```

This method is only available when the request method is `PUT`. Calling it for another HTTP method throws `StreamNotAvailableException`.

---

Next: [[triggers and callbacks]]


One common pattern in PHP applications is to branch behaviour based on submitted input. A button press might trigger one action, while the presence of a certain field might trigger another.

`Trigger` lets us express that flow directly from the `Input` object.

## `do()` for action buttons

The `do()` helper is shorthand for matching a submitted `do` parameter:

```html
<button name="do" value="save">Save</button>
<button name="do" value="archive">Archive</button>
```

```php
$input->do("save")->call(function() {
	// Save the current record.
});

$input->do("archive")->call(function() {
	// Archive the current record.
});
```

> [!NOTE]
> This pattern is already hooked up in WebEngine, so `do_*()` functions are the expected trigger for "do buttons".

## `when()` for matching keys or key/value pairs

Use `when()` when the trigger is based on the presence of one or more keys:

```php
$input->when("confirm")->call(function() {
	// Runs when the "confirm" key is present.
});
```

We can also match exact values:

```php
$input->when(["status" => "published"])->call(function() {
	// Runs only when status=published.
});
```

Multiple conditions can be combined:

```php
$input->when(
	["status" => "published"],
	"notify"
)->call(function() {
	// Runs only when both conditions are met.
});
```

## Passing only the input a callback needs

Callbacks receive an `InputData` object as their first argument. By default that object contains all request data.

Often that is more than the callback should know about, so `select()` lets us narrow the input down, enforcing good encapsulation throughout the project:

```php
$input->when(["do" => "save"])
	->select("title", "summary")
	->call(function(InputData $data) {
		// $data contains only title and summary.
	});
```

To exclude keys instead, use `selectAllExcept()`:

```php
$input->when("register")
	->selectAllExcept("csrf", "password-confirm")
	->call(function($data) {
		// All input except the excluded keys.
	});
```

If we want to pass the whole request explicitly, use `selectAll()`:

```php
$input->when("register")
	->selectAll()
	->call(function($data) {
		// All request input.
	});
```

## Matching keys by prefix

`selectPrefix()` is useful when a family of keys follows a naming convention:

```php
$input->selectPrefix("io_")->call(function($data) {
	// Runs when at least one input key begins with "io_".
});
```

This method creates a trigger based on key presence. If no matching key exists, it returns a trigger that never fires.

For backwards compatibility the older names still exist:

- `with()` is an alias of `select()`
- `without()` is an alias of `selectAllExcept()`
- `withAll()` is an alias of `selectAll()`

The `select*` names are clearer and should be preferred in new code.

## Fallback callbacks

After `call()`, we can add an `orCall()` fallback:

```php
$input->do("delete")
	->call(function() {
		// Deletion path.
	})
	->orCall(function() {
		// Runs only when the trigger did not fire.
	});
```

`orCall()` must come after `call()`. If it is called first, the library throws `CallOrOutOfSequenceException`.

## Passing extra arguments

Additional string arguments supplied to `call()` are passed on after the `InputData` object:

```php
$input->do("save")->call(
	function($data, string $mode, string $actor) {
		// ...
	},
	"draft",
	$currentUsername
);
```

Use this when the callback needs a small amount of extra context alongside the selected input.

---

Next: [[Working with InputData]]


`InputData` is the value object used throughout the library to represent a set of request parameters.

We get `InputData` from:

- `Input::getAll()`
- trigger callbacks
- selected subsets created through `select()` and `selectAllExcept()`

## What `InputData` can do

`InputData` implements:

- `ArrayAccess`
- `Iterator`
- `Countable`

So we can use it in familiar PHP ways:

```php
foreach($input->getAll() as $key => $value) {
	echo $key, ": ", $value, PHP_EOL;
}
```

```php
$data = $input->getAll();

if(isset($data["email"])) {
	echo $data["email"];
}

echo count($data);
```

## Type-safe getters also work here

Because `InputData` uses the same getter trait as `Input`, we can call the same typed methods on a selected subset:

```php
$input->when(["do" => "checkout"])
	->select("email", "postcode")
	->call(function($data) {
		$email = $data->getString("email");
		$postcode = $data->getString("postcode");
	});
```

## Checking presence and values

`InputData` provides:

- `contains($key)` to check whether the key exists
- `hasValue($key)` to check whether the key contains a non-empty value

```php
if($data->contains("referrer") && $data->hasValue("referrer")) {
	// Referrer exists and is not empty.
}
```

## Converting to a plain PHP array

Use `asArray()` when another part of the application expects a plain array:

```php
$payload = $input->getAll()->asArray();
```

Single values become strings, while multiple values become arrays of strings.

## Mutating `InputData`

There's support for adding and removing keys:

```php
$data = $input->getAll();
$data->remove("csrf");
```

That is mainly useful when we are preparing a sanitised or narrowed set of input for another layer of code. In most request-handling code, we should prefer selecting the right keys up front.

---

Next: [[Handling file uploads]]


The library wraps uploaded files in `FileUpload` objects so we can work with them consistently, regardless of how PHP shaped `$_FILES`.

## Reading one uploaded file

```php
$photo = $input->getFile("photo");
```

The result can be:

- `null` if the field was not submitted
- `FileUpload` if the upload succeeded
- `FailedFileUpload` if PHP received the field but the upload failed

That means it is worth checking the concrete type before moving the file:

```php
use GT\Input\InputData\Datum\FailedFileUpload;

$photo = $input->getFile("photo");

if($photo instanceof FailedFileUpload) {
	throw new RuntimeException($photo->getErrorMessage());
}

if($photo) {
	$photo->moveTo("data/photos/" . $photo->getOriginalName());
}
```

## Reading multiple uploaded files

For a field such as `<input type="file" name="gallery[]" multiple />`, use `getMultipleFile()`:

```php
foreach($input->getMultipleFile("gallery") as $name => $file) {
	$file->moveTo("data/gallery/$name");
}
```

The returned array is keyed by the original client filename.

## Inspecting upload metadata

`FileUpload` provides:

- `getOriginalName()`
- `getOriginalExtension()`
- `getMimeType()`
- `getSize()`
- `getRealPath()`
- `getFileInfo()`
- `getStream()`
- `getError()`
- `getClientFilename()`
- `getClientMediaType()`

Example:

```php
$document = $input->getFile("document");

if($document && !$document instanceof FailedFileUpload) {
	printf(
		"%s (%s, %d bytes)",
		$document->getOriginalName(),
		$document->getMimeType(),
		$document->getSize()
	);
}
```

## Moving an uploaded file

Use `moveTo()` to move the temporary upload into permanent storage:

```php
$photo->moveTo("data/avatar/user-42.jpg");
```

The method creates the target directory if it does not already exist.

Internally it still uses PHP's upload checks, so it will reject paths that do not refer to a real uploaded file and it will throw an exception if the move fails.

## Handling upload failures

`FailedFileUpload` carries the PHP upload error code and a readable message:

```php
if($file instanceof FailedFileUpload) {
	error_log($file->getErrorMessage());
}
```

This is useful when the field existed but PHP could not complete the upload because of size limits, missing temporary directories, interrupted uploads, or similar server-side problems.

## A note on security

Treat client-provided filenames and MIME types as descriptive, not authoritative.

- Generate your own storage filenames when possible.
- Validate file contents if the application depends on a trusted format.
- Store uploads outside the public document root unless they are intended to be served directly.

---

If you want the low-level background for why this wrapper exists, see [[how PHP handles files]].


PHP's `$_FILES` structure changes shape depending on how the form is written. Single file inputs, repeated file inputs, and `multiple` file inputs all arrive slightly differently.

This page explains the problem that PHP.GT/Input normalises.

## The form requirements

For file uploads to work, the form must include:

- `method="post"`
- `enctype="multipart/form-data"`

Without that encoding type, the browser will not send uploaded file data in a way PHP treats as a file upload.

## A single file input

```html
<form method="post" enctype="multipart/form-data">
	<input type="file" name="exampleFile" />
	<button>Submit</button>
</form>
```

PHP produces a structure like this:

```php
$_FILES = [
	"exampleFile" => [
		"name" => "Clouds.jpg",
		"type" => "image/jpeg",
		"tmp_name" => "/tmp/phpgt/input/example.tmp",
		"error" => 0,
		"size" => 1234,
	]
];
```

## Several distinct file inputs

```html
<form method="post" enctype="multipart/form-data">
	<input type="file" name="passport" />
	<input type="file" name="drivingLicence" />
	<input type="file" name="utilityBill" />
	<button>Submit</button>
</form>
```

Each field gets its own top-level entry in `$_FILES`.

## One file input with `multiple`

```html
<form method="post" enctype="multipart/form-data">
	<input type="file" name="gallery[]" multiple />
	<button>Submit</button>
</form>
```

Now the shape changes:

```php
$_FILES = [
	"gallery" => [
		"name" => ["Clouds.jpg", "Mountains.jpg"],
		"type" => ["image/jpeg", "image/jpeg"],
		"tmp_name" => ["/tmp/phpA.tmp", "/tmp/phpB.tmp"],
		"error" => [0, 0],
		"size" => [1481681, 263091],
	]
];
```

Instead of each uploaded file being represented as one unit, the arrays are grouped by property. That means application code needs one branch for single uploads and a different branch for multiple uploads.

## What PHP.GT/Input changes

PHP.GT/Input normalises this into a predictable interface.

- `getFile("passport")` always returns one `FileUpload`, `FailedFileUpload`, or `null`.
- `getMultipleFile("gallery")` always returns an array of `FileUpload` objects.
- We do not need to care whether the incoming `$_FILES` entry used scalar values or arrays internally.

In other words, the library absorbs the awkward part of `$_FILES` so the rest of the application can work with proper objects.

---

For practical examples, read the [[handling file uploads]] page.




---

# Documentation: Installer

One of the main goals of PHP.GT is to remove barriers that get in the way of quickly building a prototype. This repository supports that goal by providing an installer that sets up a single `gt` command for working with new and existing WebEngine projects.

This installer is completely optional. You can continue to set up WebEngine projects manually without losing any functionality.

The `gt` command itself is maintained separately at [PHP.GT/GtCommand](https://www.php.gt/gtcommand).

***

This repository maintains the `install.sh` script responsible for setting up the `gt` command on Linux and macOS shells using either native PHP with Composer or Docker. The script is hosted publicly at:

- `https://php.gt/install`

Quick install:

- `curl https://php.gt/install | sh`

Verbose output:

- `curl https://php.gt/install | sh -s -- --verbose`

Force shell profile selection:

- `curl https://php.gt/install | sh -s -- --shell bash`




---

# Documentation: Json

This library provides a consistent way to read, inspect and construct JSON data in PHP without falling back to loosely typed arrays and `stdClass` objects.

It builds on [PHP.GT/DataObject](https://www.php.gt/dataobject) by adding JSON-specific functionality, so the JSON objects we work with are immutable and expose type-safe getters such as `getString()` and `getInt()`.

## What this library provides

- `JSONObjectBuilder`, which turns JSON strings, decoded JSON values and files into `JSONObject` instances
- `JSONKvpObject` for JSON objects with named properties
- `JSONPrimitive` subtypes for root JSON values such as strings, numbers, booleans, `null` and arrays
- `JSONDocument`, which helps build JSON responses and nested keys
- `Validator`, `ValidationSuccess` and `ValidationError` for JSON Schema validation

## Where this library fits in

This package can be used on its own in any PHP project.

If you are using WebEngine, the integration point to know about is `JSONDocument`. WebEngine uses it as the view model for JSON responses, so page logic can call methods like `set()` and `error()` and let the framework output the final document.

## A minimal example

```php
use GT\Json\JSONObjectBuilder;
use GT\Json\JSONKvpObject;
use GT\Json\JSONPrimitive\JSONPrimitive;

$builder = new JSONObjectBuilder();
$json = $builder->fromJsonString('{"id": 105, "tags": ["php", "json"]}');

if($json instanceof JSONKvpObject) {
	echo $json->getInt("id"), PHP_EOL;
	echo implode(", ", $json->getArray("tags", "string")), PHP_EOL;
}
elseif($json instanceof JSONPrimitive) {
	var_dump($json->getPrimitiveValue());
}
```

`JSONObjectBuilder` decides which JSON type has been decoded and returns the matching object. We can then read the data through getters rather than manually checking each value ourselves.

---

Start with [[Getting started]] to install the package and decode a few different kinds of JSON.


## Installation

Install the package with Composer:

```bash
composer require phpgt/json
```

> [!NOTE]
> If you are using WebEngine, this package is already installed as part of the framework.

## Your first JSON object

`JSONObjectBuilder` is the main entry point. It reads JSON and returns the right subtype of `JSONObject`.

```php
use GT\Json\JSONObjectBuilder;

$builder = new JSONObjectBuilder();
$json = $builder->fromJsonString('{"name":"Cody", "active":true}');

echo $json->getString("name"), PHP_EOL;
var_dump($json->getBool("active"));
```

## Other builder methods

### `fromJsonDecoded()`

Use this when `json_decode()` has already been called somewhere else.

```php
$decoded = json_decode('{"name":"Cody"}');
$json = $builder->fromJsonDecoded($decoded);
```

This method accepts:

- decoded objects
- associative arrays
- indexed arrays
- strings
- integers
- floats
- booleans
- `null`

### `fromFile()`

Use this to read JSON from disk.

```php
$json = $builder->fromFile(__DIR__ . "/example.json");
```

If the file does not exist, a `FileNotFoundException` is thrown.

### `fromAssociativeArray()`

Use this when the starting point is already a PHP associative array and you want a `JSONObject`.

```php
$json = $builder->fromAssociativeArray([
	"name" => "Ada",
	"roles" => ["developer", "reviewer"],
]);
```

## Builder options

The constructor accepts two optional arguments:

```php
$builder = new JSONObjectBuilder(
	depth: 512,
	flags: JSON_BIGINT_AS_STRING,
);
```

`depth` is passed to `json_decode()`.

`flags` are combined with `JSON_THROW_ON_ERROR`, so JSON decoding errors are always surfaced as exceptions.

One useful flag is `JSON_BIGINT_AS_STRING`, which avoids very large integers being converted to floats.

> [!NOTE]
> Depending on your computer's processor type, the maximum number possible to be stored inside an integer is stored in the [`PHP_INT_MAX`](https://www.php.net/manual/en/reserved.constants.php#constant.php-int-max) constant. On 64 bit computers, this is 9,223,372,036,854,775,807 (2^63 − 1).

## Decode failures

Malformed JSON throws `JSONDecodeException`.

```php
try {
	$builder->fromJsonString('{ "broken": ');
}
catch(\GT\Json\JSONDecodeException $exception) {
	echo $exception->getMessage();
}
```

---

Next, read [[Types and getters]] to see what kind of object the builder returns and how to read values from it.


`JSONObjectBuilder` always returns a `JSONObject`, but the concrete type depends on the JSON value at the root.

## `JSONKvpObject`

If the root value is a JSON object, the result is a `JSONKvpObject`.

```php
$json = $builder->fromJsonString('{"id": 42, "name": "Ada"}');

echo $json->getInt("id"), PHP_EOL;
echo $json->getString("name"), PHP_EOL;
```

`JSONKvpObject` extends the underlying `DataObject`, so it also supports:

- `get()`
- `getString()`
- `getInt()`
- `getFloat()`
- `getBool()`
- `getDateTime()`
- `getArray()`
- `getInstance()`
- `contains()`
- `typeof()`
- `asArray()`
- `asObject()`

Because the object is immutable, methods such as `with()` return a cloned object rather than modifying the current one.

## `JSONPrimitive`

If the root value is not a JSON object, the builder returns one of the primitive subtypes:

- `JSONStringPrimitive`
- `JSONIntPrimitive`
- `JSONFloatPrimitive`
- `JSONBoolPrimitive`
- `JSONNullPrimitive`
- `JSONArrayPrimitive`

Each of these exposes `getPrimitiveValue()`.

```php
$json = $builder->fromJsonString('"hello"');
echo $json->getPrimitiveValue();
```

## Arrays

Arrays appear in two slightly different ways:

- if the root JSON value is an indexed array, the result is `JSONArrayPrimitive`
- if an array sits inside a `JSONKvpObject`, read it with `getArray()`

```php
$json = $builder->fromJsonString('{"tags":["php","json"]}');
print_r($json->getArray("tags", "string"));
```

Passing the optional second argument to `getArray()` lets us enforce a type for every item in the array.

```php
$json = $builder->fromJsonString('{"ids":[10521,21042,999991]}');
$ids = $json->getArray("ids", "int");
```

If an item does not match the requested type, PHP throws a `TypeError`.

## Iterating objects

`JSONKvpObject` implements `Iterator`, so we can loop over its keys and values.

```php
foreach($json as $key => $value) {
	echo $key, ": ", json_encode($value), PHP_EOL;
}
```

## Converting back to JSON

Every `JSONObject` can be:

- cast to a string, which returns JSON text
- passed to `json_encode()`
- converted to arrays with `asArray()`
- converted to `stdClass` style objects with `asObject()`

```php
echo (string)$json;
echo json_encode($json);
```

If you want more background on immutability and the shared getter API, the fuller explanation lives in the [PHP.GT/DataObject documentation](https://www.php.gt/dataobject).

---

Next, read [[JSONDocument]] to see how this package can be used to build JSON output as well as read it.


`JSONDocument` is a small helper for building JSON output one property at a time.

It is particularly useful when the response shape is assembled gradually, or when error responses need a consistent structure.

## Building a document

```php
use GT\Json\Schema\JSONDocument;

$document = new JSONDocument();
$document->set("name", "Ada");
$document->set("role", "Developer");

echo $document;
```

Output:

```json
{"name":"Ada","role":"Developer"}
```

## Nested keys

Dot notation creates nested objects for us.

```php
$document = new JSONDocument();
$document->set("department.name", "Computer Science");
$document->set("department.building", "Babbage");
```

Output:

```json
{"department":{"name":"Computer Science","building":"Babbage"}}
```

`get()` also understands dot notation:

```php
echo $document->get("department.name");
```

If we ask for a simple key whose value is itself an object, `get()` returns another `JSONDocument`, so nested access can continue naturally.

## Starting from an existing `JSONObject`

`JSONDocument` can also wrap a `JSONObject`.

```php
use GT\Json\JSONObjectBuilder;
use GT\Json\Schema\JSONDocument;

$builder = new JSONObjectBuilder();
$json = $builder->fromAssociativeArray([
	"name" => "Ada",
	"skills" => ["PHP", "SQL"],
]);

$document = new JSONDocument($json);
echo $document;
```

## Error responses

`error()` clears any existing properties and replaces them with an error payload.

```php
$document = new JSONDocument();
$document->error("Something went wrong");

echo $document;
```

Output:

```json
{"error":"Something went wrong"}
```

An optional context array can be included:

```php
$document->error(
	"Validation failed",
	context: ["field" => "email"]
);
```

Output:

```json
{"error":"Validation failed","errorContext":{"field":"email"}}
```

You can rename both property names if required:

```php
$document->error(
	"Validation failed",
	context: ["field" => "email"],
	property: "message",
	contextProperty: "details"
);
```

After `error()` has been called, later calls to `set()` throw `JSONErrorStateException`.

## Error callbacks

If you need to log or react to errors as they are set, attach a callback:

```php
$document->setErrorCallback(function(string $message, ?array $context):void {
	error_log($message);
});
```

The callback runs each time `error()` is called.

## Using `JSONDocument` in WebEngine

When a WebEngine route uses the JSON view, the framework creates a `JSONDocument` as the view model. That means page logic can work directly with methods such as:

- `set()`
- `get()`
- `error()`
- `setErrorCallback()`

The JSON output is then handled by WebEngine's response pipeline.

Outside WebEngine, `JSONDocument` is still just a normal PHP object and can be used anywhere a stringable JSON payload is useful.

---

Next, read [[JSON Schema]] if you need to validate JSON against a predefined schema before using it.


JSON Schema is useful when JSON needs to match a known shape before the rest of the application uses it.

In this library, the `Validator` class compares a `JSONObject` against a schema and returns either `ValidationSuccess` or `ValidationError`.

> [!NOTE]
> WebEngine applications inherently support automatic JSON schema validations. This documentation is only necessary for setups where WebEngine is not used.

## Creating a validator

```php
use GT\Json\JSONObjectBuilder;
use GT\Json\Schema\ValidationError;
use GT\Json\Schema\Validator;

$builder = new JSONObjectBuilder();

$schema = $builder->fromFile("schema.json");
$json = $builder->fromFile("example.json");

$validator = new Validator($schema);
$result = $validator->validate($json);

if($result instanceof ValidationError) {
	foreach($result->getErrorList() as $pointer => $message) {
		echo $pointer, ": ", $message, PHP_EOL;
	}
}
```

The keys in `getErrorList()` are JSON Pointer style paths such as `/name` or `/food/2`.

## Validation results

`ValidationSuccess` means the JSON matched the schema.

`ValidationError` means at least one schema rule failed. It provides:

- `getErrorList()`, which returns the validation messages keyed by path
- `jsonSerialize()`, which returns a JSON-friendly object with `error`, `errorList` and `schema`

## A complete example

```php
$builder = new JSONObjectBuilder();

$jsonString = <<<JSON
{
	"name": "Cody",
	"colr": "orange",
	"food": [
		"Biscuits",
		"Mushrooms",
		12345
	]
}
JSON;

$schemaString = <<<JSON
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Simple object schema",
	"type": "object",
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1
		},
		"colour": {
			"type": "string"
		},
		"food": {
			"type": "array",
			"items": {
				"type": "string"
			}
		}
	},
	"required": [
		"name",
		"colour",
		"food"
	],
	"additionalProperties": false
}
JSON;

$schema = $builder->fromJsonString($schemaString);
$json = $builder->fromJsonString($jsonString);

$validator = new Validator($schema);
$result = $validator->validate($json);
```

In that example, validation fails because:

- `colr` is not part of the schema
- `colour` is missing
- the last item in `food` is an integer, not a string

If you are already inside a WebEngine JSON endpoint, schema validation is still an explicit step. WebEngine creates the `JSONDocument` response model, but it does not automatically validate incoming or outgoing JSON for you.




---

# Documentation: Logger

`phpgt/logger` is a small logging library for PHP applications.

Start logging with zero configuration. By default, the logger writes to standard output, so `Log::error("You can't do that");` is enough to get started. When we need to, we can configure the logger to write to files, stderr, or any other stream path PHP can open.

The aim of this library is minimalism. There are no large configuration objects, channels, processors, or transport layers to learn first. We get a set of familiar log levels, a tiny handler system, and a straightforward way to route messages where they need to go.

> [!NOTE]
> In a WebEngine project, this library is already part of the request lifecycle. WebEngine uses it for request, redirect, timing, and error logging, and configures stdout/stderr handling from the application's `logger.*` config values. In WebEngine application code, use the `Log` class statically without needing any configuration.

## A small example

```php
use GT\Logger\Log;
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\FileHandler;
use GT\Logger\LogHandler\StdErrHandler;
use GT\Logger\LogLevel;

LogConfig::addHandler(new FileHandler("var/app.log"), LogLevel::DEBUG);
LogConfig::addHandler(new StdErrHandler(), LogLevel::ERROR, LogLevel::EMERGENCY);

Log::info("Application started");
Log::warning("Using fallback configuration");
Log::error("Unable to write cache file", [
	"path" => "var/cache",
]);
```

This is the core shape of the library: call a static logging method, optionally attach context, and configure handlers once near the start of the application.

***

To get the first log line on screen and then route it somewhere more useful, read the [[Quick start guide]].


In this guide we will install the package, write the first log line, and then add one or two handlers so the output goes where we expect.

## 1. Install the package

```bash
composer require phpgt/logger
```

## 2. Write the first log line

```php
use GT\Logger\Log;

Log::info("Application started");
```

With no other setup, the library creates a default stdout handler the first time a log message is written.

That makes it very easy to start, especially for command-line scripts and small applications.

## 3. Use the log level constants

The static methods on `Log` map directly to the constants on `LogLevel`:

```php
use GT\Logger\Log;
use GT\Logger\LogLevel;

Log::debug("Debug details");
Log::error("Something went wrong");

echo LogLevel::ERROR;
```

The constants are most useful when configuring handlers, because they help us avoid spelling mistakes.

## 4. Add a file handler

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\FileHandler;
use GT\Logger\LogLevel;

LogConfig::addHandler(
	new FileHandler("var/app.log"),
	LogLevel::DEBUG
);
```

From this point on, every log at `DEBUG` and above will be appended to `var/app.log`.

## 5. Split stdout and stderr

Many applications want general output on stdout but errors on stderr.

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\StdErrHandler;
use GT\Logger\LogLevel;

LogConfig::setDefaultHandlerLevel(LogLevel::DEBUG);
LogConfig::addHandler(
	LogConfig::getDefaultHandler(),
	LogLevel::DEBUG,
	LogLevel::WARNING
);
LogConfig::addHandler(
	new StdErrHandler(),
	LogLevel::ERROR,
	LogLevel::EMERGENCY
);
```

This keeps lower-severity logs on stdout while routing `ERROR`, `CRITICAL`, `ALERT`, and `EMERGENCY` to stderr.

## 6. Attach context data

```php
use GT\Logger\Log;

Log::error("Unable to save profile", [
	"userId" => 42,
	"section" => "preferences",
]);
```

The context is appended to the log line in a readable key/value format.

---

Next: [[Log levels]]


The library uses the eight standard PSR-3 level names. They are stored as uppercase constants in `GT\Logger\LogLevel`, and each one has a matching static method on `GT\Logger\Log`.

## The available levels

- `DEBUG`: detailed debugging information
- `INFO`: interesting events during normal operation
- `NOTICE`: normal but significant events
- `WARNING`: unexpected situations that are not outright failures
- `ERROR`: runtime errors that should usually be recorded and investigated
- `CRITICAL`: critical conditions
- `ALERT`: action must be taken immediately
- `EMERGENCY`: the system is unusable

The ordering is important because handler filtering is based on severity. A handler configured with a minimum level of `WARNING` logs:

- `WARNING`
- `ERROR`
- `CRITICAL`
- `ALERT`
- `EMERGENCY`

but does not log:

- `DEBUG`
- `INFO`
- `NOTICE`

## Calling the matching methods

```php
use GT\Logger\Log;

Log::debug("SQL query started");
Log::info("User signed in");
Log::notice("Cache warmup took longer than usual");
Log::warning("Profile picture missing");
Log::error("Could not write session data");
Log::critical("Primary storage unavailable");
Log::alert("Manual intervention required");
Log::emergency("Application cannot continue");
```

## Choosing a minimum level

The minimum level is applied per handler:

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\FileHandler;
use GT\Logger\LogLevel;

LogConfig::addHandler(
	new FileHandler("var/error.log"),
	LogLevel::ERROR
);
```

In this example, the handler ignores `DEBUG`, `INFO`, `NOTICE`, and `WARNING`.

> [!NOTE]
> In WebEngine applications, the configuration of the logger is done by adding settings to the `config.ini`.

## Choosing a range

`addHandler()` also accepts an optional maximum level:

```php
LogConfig::addHandler(
	new FileHandler("var/normal.log"),
	LogLevel::DEBUG,
	LogLevel::WARNING
);
```

This handler receives only the lower-severity messages from `DEBUG` up to `WARNING`.

That is useful when we want one output for routine logs and another for errors.

## A practical guideline

If we are not sure which level to use, a simple rule of thumb is:

- `DEBUG` while inspecting internals during development
- `INFO` for ordinary application events we may want to trace later
- `WARNING` for something unusual that the application recovered from
- `ERROR` when the requested operation failed

Once we are consistent about that, handler configuration becomes much easier.

---

Next: [[Configuring handlers]]


`LogConfig` is the small static registry that controls where log messages go.

The logger itself only decides _what_ level was written. The handlers decide _where_ to write it.

## The default handler

If we do nothing else, the first log call creates a default `StdOutHandler`.

That means this works immediately:

```php
use GT\Logger\Log;

Log::info("Hello from stdout");
```

If we want to configure the minimum level for that default stdout handler before anything is logged, call:

```php
use GT\Logger\LogConfig;
use GT\Logger\LogLevel;

LogConfig::setDefaultHandlerLevel(LogLevel::NOTICE);
```

## Adding handlers

The main configuration method is `LogConfig::addHandler()`:

```php
LogConfig::addHandler($handler, $minimumLevel, $maximumLevel);
```

- The first argument is any `LogHandler`.
- The second argument is the minimum level.
- The third argument is optional and sets the maximum level.

Handlers are appended, not replaced. If two handlers both match the same message, both will receive it.

## Writing to a file

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\FileHandler;
use GT\Logger\LogLevel;

LogConfig::addHandler(
	new FileHandler("var/app.log"),
	LogLevel::DEBUG
);
```

`FileHandler` opens the file in append mode, so new messages are added to the end.

## Writing to stderr

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\StdErrHandler;
use GT\Logger\LogLevel;

LogConfig::addHandler(
	new StdErrHandler(),
	LogLevel::ERROR,
	LogLevel::EMERGENCY
);
```

This is especially useful for CLI tools, containers, and process supervisors that expect problems on stderr.

## Using streams and sockets

`StreamHandler` currently extends `FileHandler` without adding extra behaviour. It exists to make stream-based intent clearer in application code.

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\StreamHandler;
use GT\Logger\LogLevel;

LogConfig::addHandler(
	new StreamHandler("php://stdout"),
	LogLevel::DEBUG
);
```

If PHP can open the path for appending, the handler can write to it.

## A common stdout/stderr split

```php
use GT\Logger\LogConfig;
use GT\Logger\LogHandler\StdErrHandler;
use GT\Logger\LogLevel;

LogConfig::setDefaultHandlerLevel(LogLevel::DEBUG);
LogConfig::addHandler(
	LogConfig::getDefaultHandler(),
	LogLevel::DEBUG,
	LogLevel::WARNING
);
LogConfig::addHandler(
	new StdErrHandler(),
	LogLevel::ERROR,
	LogLevel::EMERGENCY
);
```

Here the default stdout handler is kept only for the lower levels, while the stderr handler receives the more severe range.

## Configure once, early

Because the configuration is static, we usually set handlers once near the application's bootstrap code and then leave them alone.

If we keep calling `addHandler()` throughout the request, we keep adding more destinations.

---

Next: [[Context data]]


Every logging method accepts a second argument: an array of context data.

```php
use GT\Logger\Log;

Log::warning("Unable to send welcome email", [
	"userId" => 42,
	"email" => "new.user@example.com",
]);
```

By default, that context is appended to the line in a bracketed key/value format:

```text
2026-05-08 12:34:56    WARNING    Unable to send welcome email    [userId = 42] [email = new.user@example.com]
```

## Nested arrays

Nested arrays are unwrapped recursively:

```php
Log::error("Form validation failed", [
	"user" => [
		"id" => 42,
		"role" => "admin",
	],
]);
```

Output:

```text
[user = {[id = 42] [role = admin]}]
```

## Non-scalar values

Scalars and `null` are written directly.

If a context value is an object or another non-scalar type, the logger writes its type name rather than trying to serialise the whole thing.

That keeps the default output safe and predictable.

## A useful habit

Context is most helpful when the message stays short and the changing details move into the array:

```php
Log::error("Unable to save order", [
	"orderId" => $orderId,
	"userId" => $userId,
	"retry" => $retryCount,
]);
```

This tends to age better than building one large string with every value interpolated into it.

## What context does not do

This library does not implement PSR-3 placeholder interpolation such as:

```php
Log::info("User {id} signed in", ["id" => 42]);
```

In this library, that message remains exactly as written and the context is appended separately.

If we want the ID in the message itself, we should add it explicitly:

```php
Log::info("User 42 signed in", ["id" => 42]);
```

---

Next: [[Custom log handlers]]


The built-in handlers cover the common destinations:

- stdout
- stderr
- files
- generic stream paths

When that is not enough, we can create a custom handler by extending `GT\Logger\LogHandler\LogHandler` or one of its subclasses.

## The smallest useful customisation

Quite often we do not need a completely new destination. We just want a different way of formatting context.

In that case, extending `FileHandler` is usually the simplest path:

```php
use GT\Logger\LogHandler\FileHandler;

class JsonContextFileHandler extends FileHandler {
	protected function unwrapContext(array $context):string {
		return json_encode($context, JSON_UNESCAPED_SLASHES) ?: "";
	}
}
```

```php
use GT\Logger\LogConfig;
use GT\Logger\LogLevel;

LogConfig::addHandler(
	new JsonContextFileHandler("var/json.log"),
	LogLevel::INFO
);
```

This keeps all of `FileHandler`'s file-opening and line-writing behaviour, while changing how the context part is rendered.

## Writing a handler from scratch

When the destination itself is different, extend the abstract base class:

```php
use GT\Logger\LogHandler\LogHandler;

class PhpErrorLogHandler extends LogHandler {
	public function handle(
		string $level,
		string $message,
		array $context = []
	):void {
		error_log($this->getLogLine($level, $message, $context));
	}

	protected function unwrapContext(array $context):string {
		$parts = [];

		foreach($context as $key => $value) {
			$parts[] = "$key=" . (is_scalar($value) || $value === null
				? (string)$value
				: get_debug_type($value));
		}

		return implode(" ", $parts);
	}
}
```

`LogHandler` gives us:

- the log line token constants
- the default format parts
- the `getLogLine()` helper that assembles the final string

We only need to decide how to write the line and how to render the context.

## When to extend `StreamHandler`

At the moment, `StreamHandler` does not add behaviour on top of `FileHandler`.

It is still a reasonable class to extend if the destination is stream-like and we want the name to reflect that intention in our codebase.

---

Next: [[WebEngine integration]]


`phpgt/logger` is used directly inside WebEngine's bootstrap and application lifecycle.

That means we can use this package in WebEngine even if we never configure it manually.

## What WebEngine uses it for

WebEngine logs several kinds of events through this library, including:

- request and response status lines
- redirects
- slow request timing notices
- some error conditions
- optional static-file request logging

> [!NOTE]
> This is one of the reasons the logger stays intentionally small. It is used very early in the lifecycle, before the rest of the application is fully up and running.

## The relevant config values

WebEngine reads these logger settings from its application config:

- `logger.level`
- `logger.stderr_level`
- `logger.log_all_requests`
- `logger.log_static_requests`
- `logger.log_redirects`
- `logger.log_404_to_error_log`

For the stream split specifically:

- `logger.level` defaults to `debug`
- `logger.stderr_level` defaults to `ERROR`

## How stdout and stderr are split

During application startup, WebEngine configures:

- the default stdout handler for messages from `logger.level` up to the level below `logger.stderr_level`
- a `StdErrHandler` for messages from `logger.stderr_level` up to `EMERGENCY`

So with the default settings:

- `DEBUG`, `INFO`, `NOTICE`, and `WARNING` go to stdout
- `ERROR`, `CRITICAL`, `ALERT`, and `EMERGENCY` go to stderr

That makes the default behaviour much more convenient for web servers, containers, and process tools that already treat stdout and stderr differently.

## Using the logger in our own WebEngine code

Application code can still call the logger directly:

```php
use GT\Logger\Log;

function do_save():void {
	Log::info("Saving profile");
}
```

That message goes through the same configured handlers as the framework's own logging.

## One practical implication

`LogConfig` is static. If we add our own handlers in WebEngine, they are added alongside the framework's handlers rather than replacing them automatically.

That is usually what we want, but it is worth remembering when a message appears in more than one place.




---

# Documentation: Orm

The ORM feature of PHP.GT is currently work-in-progress. Each step of its development is being heavily considered, and the first version will be documented here when it's ready.

For now, check out the [SQL database capabilities of PHP.GT](https://www.php.gt/Database).



---

# Documentation: Promise

In computer science, a _Promise_ is a construct that bridges the gap between procedural code and asynchronous execution. In procedural languages like PHP, functions influence program flow by either returning a value or throwing an exception, but when dealing with asynchronous operations, we can't return a value (because it isn't ready yet), and we can't throw an exception (because there's no clear place to catch it).

This is where Promises come in. Instead of returning a value or throwing an exception, an asynchronous function returns a `Promise`: an object that will eventually be _settled_ by _fulfilling_ with a value or _rejecting_ with an error — but not immediately.

In this library, that background work is encapsulated by the `Deferred` class, which allows execution to be deferred while still exposing a `Promise` object that can be resolved or rejected later.

This implementation follows the [Web API's Promise specification][mdn-promise] in terms of syntax and expected behaviour — using `then`, `catch`, and `finally` — but is tailored to work natively in PHP.

> [!NOTE]
> While the API is compatible with Promises/A+, this library differs in one important way: instead of returning a new Promise with each `then`, `catch`, or `finally` call, it maintains and returns the _same instance_ throughout the chain. This design keeps memory usage lower, avoids deep call stacks, and results in simpler, more predictable code — especially helpful in procedural environments like PHP.

## Overview

- Exposes `PromiseInterface` with `then()`, `catch()`, `finally()`, and `getState()`.
- Exposes `DeferredInterface` for managing asynchronous work and resolving the related promise.
- Supports chaining by returning scalar values, `null`, or another `PromiseInterface` from callbacks.
- Uses PHP parameter types to decide which chained callback should run.
- Leaves scheduling to your own loop, or to a separate package such as [PHP.GT/Async][gt-async].

> [!NOTE]
> This package is fully usable on its own for implementing Promise-driven libraries. The examples in this guide are standalone PHP examples. Framework-specific usage in PHP.GT/WebEngine is documented separately in the WebEngine docs.

## A tiny example

```php
use GT\Promise\Deferred;

$deferred = new Deferred();
$promise = $deferred->getPromise();

$promise->then(function(string $message) {
	echo $message, PHP_EOL;
});

$deferred->resolve("Task complete");
```

This example resolves immediately, so it does not need a loop yet. Real asynchronous work is usually spread across repeated process callbacks, which we will look at next.

---

Start with [[Getting started]] to install the package and build a minimal deferred task.

[gt-async]: https://www.php.gt/async


Before we can use this package, we need to install it with Composer and create a `Deferred` that exposes a `Promise`.

## Install with Composer

```bash
composer require phpgt/promise
```

## A first standalone example

The smallest useful setup is:

```php
use GT\Promise\Deferred;

$deferred = new Deferred(function() use (&$deferred) {
	$deferred->resolve("Finished");
});

$promise = $deferred->getPromise();
$promise->then(function(string $message) {
	echo $message, PHP_EOL;
});

foreach($deferred->getProcessList() as $process) {
	$process();
}
```

Here is what happens:

1. We construct a `Deferred`.
2. The `Deferred` creates and keeps a matching `Promise`.
3. We attach a `then()` callback to the promise.
4. We run the deferred process callback.
5. The process resolves the promise, so the `then()` callback runs.

- `Deferred` and `Promise` are separate objects with separate jobs.
- The package does not run process callbacks for us.
- `then()`, `catch()`, and `finally()` can be attached before or after resolution.
- A promise stays pending until something calls `resolve()` or `reject()`.

If you are coming from JavaScript, the syntax will look familiar, but the scheduling is more explicit because PHP does not provide an event loop by default.

---

Next, learn the difference between [[Deferred and Promise objects]].


This package keeps asynchronous work and asynchronous results separate:

- `Deferred` manages the work.
- `Promise` represents the eventual outcome.

That separation is the main idea to keep in mind while reading the rest of the API.

## `Deferred`

A `Deferred` is the object we control directly. It has three main responsibilities:

- Store one or more process callbacks.
- Expose a `Promise` through `getPromise()`.
- Settle that promise later with `resolve()` or `reject()`.

The process list is available through `getProcessList()`, and `isActive()` tells us whether the deferred task still has work left to do.

```php
use GT\Promise\Deferred;

$deferred = new Deferred();
$deferred->addProcess(function() use ($deferred) {
	$deferred->resolve("Done");
});
```

Concrete `Deferred` objects also provide `onComplete()`, which can be useful when you want to run local cleanup code after the deferred finishes. That helper is available on the class itself rather than on `DeferredInterface`.

## `Promise`

A `Promise` is what we return to the caller. It exposes:

- `then()` for resolved values
- `catch()` for rejections
- `finally()` for code that should run in either case
- `getState()` to inspect whether the promise is `PENDING`, `RESOLVED`, or `REJECTED`

The promise does not know how to do the work itself. It only reacts when the paired deferred settles it.

## Returning promises from your own classes

This is the usual pattern when building on top of this package:

```php
use GT\Promise\Deferred;
use GT\Promise\PromiseInterface;

class ExampleJob {
	private Deferred $deferred;
	private array $items;

	public function __construct(array $items) {
		$this->items = $items;
	}

	public function start():PromiseInterface {
		$this->deferred = new Deferred(fn() => $this->tick());
		return $this->deferred->getPromise();
	}

	private function tick():void {
		if($this->items) {
			array_shift($this->items);
			return;
		}

		$this->deferred->resolve("All items processed");
	}
}
```

The calling code only needs the promise:

```php
$job = new ExampleJob(["a", "b", "c"]);
$job->start()->then(function(string $message) {
	echo $message, PHP_EOL;
});
```

The event loop, runner, or timer that calls `tick()` can stay elsewhere in the application.

---

Next: [[Chained promises]].


Once a promise exists, we usually build a chain of callbacks around it.

## The chain methods

- `then()` runs when the promise resolves.
- `catch()` runs when the promise rejects.
- `finally()` runs in either case.

This implementation keeps returning the same promise instance throughout the chain. This is slightly different to how Promises within the browser context are handled - the chaining behaviour still works, but it is implemented by mutating the promise's internal chain rather than allocating a new promise object on every call.

## Forwarding values

If a `then()` callback returns a scalar or object, that value becomes the input to the next compatible `then()` callback.

```php
$promise
	->then(function(string $value) {
		return strtoupper($value);
	})
	->then(function(string $value) {
		echo $value, PHP_EOL;
	});
```

If a callback returns `null`, the current chain stops there.

## Returning another promise

If a `then()`, `catch()`, or `finally()` callback returns another `PromiseInterface`, the chain waits for that promise to settle and continues with its resolved value or rejection.

```php
$promise
	->then(function(int $userId) use ($api) {
		return $api->loadUser($userId);
	})
	->then(function(User $user) {
		echo $user->name, PHP_EOL;
	});
```

This is the correct way to combine asynchronous steps. We should not resolve a promise directly with another promise. If `resolve()` receives a `PromiseInterface`, the package rejects with `PromiseResolvedWithAnotherPromiseException`.

## Typed callbacks

This package uses PHP parameter types when deciding which callback should run next.

```php
$promise
	->then(function(string $value) {
		return 42;
	})
	->then(function(float $number) {
		echo "This will be skipped, because a float is never returned", PHP_EOL;
	})
	->then(function(int $number) {
		echo $number, PHP_EOL;
	});
```

The `float` handler is skipped because the resolved value is an `int`. The `int` handler then receives the value.

The same idea applies to `catch()` callbacks, which means we can target specific exception types:

```php
$promise
	->catch(function(ValueError $error) {
		echo "Value error: ", $error->getMessage(), PHP_EOL;
	})
	->catch(function(ArithmeticError $error) {
		echo "Arithmetic error: ", $error->getMessage(), PHP_EOL;
	});
```

If no matching `catch()` handles a rejection, the exception bubbles out to the main thread.

If a matching `catch()` returns a value, the chain becomes resolved again and later `then()` callbacks can continue:

```php
$promise
	->catch(function(RuntimeException $error) {
		return "Fallback value";
	})
	->then(function(string $value) {
		echo $value, PHP_EOL;
	});
```

## `finally()` behaviour

`finally()` receives the resolved value or rejected reason, and always runs after the promise settles.

- If it returns a scalar, the original resolution or rejection still continues.
- If it returns another promise, the chain waits for that promise.
- If it throws, the thrown exception leaves the chain.

Use `finally()` for cleanup, logging, or state updates that should happen regardless of success or failure.

---

To make all of this work, we need an [[Async event loop]].


This package does not provide an event loop. That part is left to the calling application.

Without something repeatedly calling each deferred process callback, a pending promise will stay pending forever.

## A minimal loop

If we only need a small proof of concept, we can loop over active deferred tasks ourselves:

```php
/** @var GT\Promise\Deferred[] $deferredList */
while($deferredList) {
	foreach($deferredList as $index => $deferred) {
		foreach($deferred->getProcessList() as $process) {
			$process();
		}

		if(!$deferred->isActive()) {
			unset($deferredList[$index]);
		}
	}
}
```

The important part is simple:

- read each deferred's process list
- call each process callback
- stop tracking the deferred when `isActive()` becomes `false`

## Using PHP.GT/Async

For real applications, you will usually want a dedicated loop implementation. Within PHP.GT, that role is handled by [PHP.GT/Async][gt-async].

```php
use Gt\Async\Loop;
use Gt\Async\PeriodicTimer;

$timer = new PeriodicTimer(0.1, true);
$loop = new Loop();
$loop->addTimer($timer);

/** @var GT\Promise\Deferred $deferred */
$loop->addDeferredToTimer($deferred);
$loop->run();
```

This keeps Promise focused on representing work and results, while Async focuses on scheduling.

## Inside WebEngine

When Promise is used inside a wider PHP.GT application, it is usually through a higher-level package that already knows how to schedule its own deferred work. This repository still remains a standalone package, so the examples in this guide stay at that lower level.

[gt-async]: https://www.php.gt/async




---

# Documentation: PropFunc

`phpgt/propfunc` is a very small library with one job: let a PHP class expose methods as if they were normal object properties.

That means we can keep the logic for reading or writing a value in methods such as `__propGetName()` and `__propSetName()`, but use the class from the outside like this:

```php
$user->name = "Cody";
echo $user->name;
```

This is especially useful when a value should be:

- read-only
- calculated on demand
- validated before it is stored
- backed by a private property rather than a public one

The library does this through the `GT\PropFunc\MagicProp` trait, which implements PHP's `__get()`, `__set()`, `__isset()`, and `__unset()` magic methods.

> [!NOTE]
> If you are building with WebEngine, you may not install this package directly very often. It sits underneath other PHP.GT packages, especially `phpgt/dom`, which WebEngine relies on heavily. In practice, this trait helps those libraries expose DOM-style read-only and computed properties with a familiar API.

## A small example

```php
use GT\PropFunc\MagicProp;
use DateTimeImmutable;
use DateTimeInterface;

class Day {
	use MagicProp;

	public function __construct(
		private DateTimeInterface $dateTime,
	) {}

	private function __propGetFuture():bool {
		return new DateTimeImmutable() < $this->dateTime;
	}

	private function __propGetDaysApart():int {
		$diff = (new DateTimeImmutable())->diff($this->dateTime);
		return $diff->days;
	}
}

$day = new Day(new DateTimeImmutable("+3 days"));

echo $day->future ? "Future" : "Past";
echo PHP_EOL;
echo $day->daysApart;
```

The class does not contain public properties called `future` or `daysApart`, but the object can still be used as if those properties exist.

> [!NOTE]
> Since PHP 8.4, [object property hooks](https://www.php.net/manual/en/language.oop5.property-hooks.php) were introduced, which will eventually render this library obsolete once dependent libraries drop support for older PHP versions.

---

To build the smallest useful class with the trait, continue with [[Getting started]].


## 1. Install the package

```bash
composer require phpgt/propfunc
```

## 2. Import the trait

```php
use GT\PropFunc\MagicProp;
```

## 3. Create a class that uses the trait

```php
class User {
	use MagicProp;
}
```

At this point nothing is exposed yet. The trait is ready to respond to unknown or inaccessible properties, but we still need to define what those properties should do.

## 4. Add a getter method

```php
class User {
	use MagicProp;

	private string $name = "Cody";

	private function __propGetName():string {
		return $this->name;
	}
}
```

The method name matters:

- property name: `name`
- getter method: `__propGetName`

The property part is converted with `ucfirst()`, so `fullName` becomes `__propGetFullName`.

## 5. Use the class like a normal property API

```php
$user = new User();
echo $user->name;
```

Even though `name` is private, the trait notices the property access, finds `__propGetName()`, calls it, and returns the result.

## 6. Add a setter when the property should be writable

```php
class User {
	use MagicProp;

	private string $name = "Cody";

	private function __propGetName():string {
		return $this->name;
	}

	private function __propSetName(string $name):void {
		$this->name = trim($name);
	}
}
```

Now this works:

```php
$user = new User();
$user->name = "  Ada  ";
echo $user->name; // Ada
```

## 7. Know what happens when a method is missing

- If a getter exists but no setter exists, the property is read-only.
- If no getter or setter exists for that property, a `PropertyDoesNotExistException` is thrown.

---

Next, move on to [[Exceptions and edge cases]] for handling errors.


## `PropertyDoesNotExistException`

This exception is thrown when a property is read or written and the trait cannot find a matching getter or setter.

```php
$example->unknown;
$example->unknown = "value";
```

Both cases throw `GT\PropFunc\PropertyDoesNotExistException` if no matching magic property methods exist.

## `PropertyReadOnlyException`

This exception is thrown when:

- a getter exists but a setter does not, and we try to write the property
- `unset()` is called on a property with no setter

```php
$example->id = 123;
unset($example->id);
```

If `id` only has `__propGetId()`, both operations are treated as attempts to modify a read-only property.

## `PropertyReadOnlySetMoreThanOnceException`

This class exists in the library, but the trait does not throw it directly.

It is there for application code or higher-level libraries that want a more specific exception type for write-once rules.

In other words, if you need "can be written once, then becomes read-only", that policy belongs in your setter method.

## `property_exists()` is not the same as magic property support

`property_exists($object, "name")` only answers whether the class declares a real property called `name`.

It does **not** tell us whether `MagicProp` can respond to `$object->name`.

For example:

- a public or private declared property may make `property_exists()` return `true`
- a fully magic property backed only by `__propGetName()` may make `property_exists()` return `false`

So `property_exists()` is about declared class structure, not the full property-like API exposed by the trait.

## `isset()` tells us whether the property is readable

This is worth repeating because it can surprise people.

If a getter exists, `isset($object->property)` returns `true` even when:

- the getter would return `null`
- the backing value has not really been initialised yet

That makes `isset()` more like "is this property available?" than "does this property currently contain a value?".

## `unset()` is rarely the best public API

`unset()` only makes sense when the property maps cleanly to real mutable state.

For most `MagicProp` code, a clearer alternative is to:

- expose a setter that accepts `null`
- provide a dedicated method such as `clearNickname()`

That usually makes the class easier to understand, especially for newer developers.

---

Finally, check some [[Examples]] for full reference classes.


This page groups together a few small patterns that tend to come up when using `MagicProp`.

## Example 1: expose a private property as read-only

```php
use GT\PropFunc\MagicProp;

class User {
	use MagicProp;

	public function __construct(
		private int $id,
	) {}

	private function __propGetId():int {
		return $this->id;
	}
}

$user = new User(42);
echo $user->id;
```

This is a good fit for IDs, timestamps, and values initialised in the constructor.

## Example 2: validate a writable property

```php
use GT\PropFunc\MagicProp;
use InvalidArgumentException;

class User {
	use MagicProp;

	private string $email = "";

	private function __propGetEmail():string {
		return $this->email;
	}

	private function __propSetEmail(string $email):void {
		$email = trim($email);

		if(!filter_var($email, FILTER_VALIDATE_EMAIL)) {
			throw new InvalidArgumentException("Invalid email address");
		}

		$this->email = $email;
	}
}
```

The caller gets a clean property API, while the class keeps control over validation.

## Example 3: expose a calculated property

```php
use GT\PropFunc\MagicProp;

class Name {
	use MagicProp;

	public function __construct(
		private string $first,
		private string $last,
	) {}

	private function __propGetFull():string {
		return "$this->first $this->last";
	}
}

$name = new Name("Ada", "Lovelace");
echo $name->full;
```

This avoids adding boilerplate methods such as `getFull()` to the public API when we really want the consumer to think of the value as a property.

## Example 4: map one property API to different internal state

```php
use GT\PropFunc\MagicProp;

class Stopwatch {
	use MagicProp;

	private int $startedAt;

	public function __construct() {
		$this->startedAt = time();
	}

	private function __propGetElapsed():int {
		return time() - $this->startedAt;
	}

	private function __propSetElapsed(int $seconds):void {
		$this->startedAt = time() - $seconds;
	}
}
```

This is the same shape used in the test suite for the `age` property.

## Example 5: optional internal storage

```php
use GT\PropFunc\MagicProp;

class Profile {
	use MagicProp;

	private function __propGetNickname():?string {
		return $this->__prop["nickname"] ?? null;
	}

	private function __propSetNickname(string $nickname):void {
		$this->__prop["nickname"] = $nickname;
	}
}
```

This can be helpful for optional values that do not need a dedicated declared property.

## Example 6: write-once semantics

```php
use GT\PropFunc\MagicProp;
use GT\PropFunc\PropertyReadOnlySetMoreThanOnceException;

class ApiToken {
	use MagicProp;

	private ?string $token = null;

	private function __propGetToken():?string {
		return $this->token;
	}

	private function __propSetToken(string $token):void {
		if($this->token !== null) {
			throw new PropertyReadOnlySetMoreThanOnceException("token");
		}

		$this->token = $token;
	}
}
```

This exception type is optional, but it can make the intent clearer than a generic runtime exception.




---

# Documentation: ProtectedGlobal

`phpgt/protectedglobal` helps us stop accidental use of PHP superglobals in the parts of an application where we want stronger encapsulation.

In plain PHP, arrays such as `$_GET`, `$_POST`, `$_COOKIE`, and `$_SERVER` are available everywhere. That can be convenient in very small scripts, but in larger systems it makes data flow hard to follow. Any part of the codebase can read from, write to, or unset global request data without making that dependency obvious.

This library replaces selected superglobals with `GT\ProtectedGlobal\ProtectedGlobal` objects. Those objects allow access only to explicitly whitelisted offsets. Any other array access throws a `ProtectedGlobalException`, making accidental global usage obvious during development.

> [!TIP]
> This library pairs naturally with [PHP.GT/Input](https://www.php.gt/input). Input gives us an object-oriented way to read request data, while ProtectedGlobal helps catch code that still reaches for the raw superglobals.

> [!NOTE]
> WebEngine uses this library during application start-up to protect the common request-related superglobals before page logic runs. That helps keep page logic focused on injected services such as `Input` and `Request` rather than hidden global state.

## What this library does

- Wraps selected superglobal arrays in protective objects.
- Allows a whitelist of offsets to remain accessible where needed.
- Throws a dedicated exception when blocked global access is attempted.
- Leaves clear debug output behind when a protected global is dumped accidentally.

## A small example

```php
use GT\ProtectedGlobal\Protection;

$protection = new Protection();

$whitelist = $protection->removeGlobals(
	[
		"_GET" => $_GET,
		"_POST" => $_POST,
		"_COOKIE" => $_COOKIE,
	],
	[
		"_COOKIE" => ["XDEBUG_SESSION"],
	]
);

$protection->overrideInternals($whitelist);

// Allowed because it was whitelisted.
$xdebugSession = $_COOKIE["XDEBUG_SESSION"];

// Throws GT\ProtectedGlobal\ProtectedGlobalException.
$page = $_GET["page"];
```

In practice, that means we can move request handling into explicit objects and services, while still leaving a narrow escape hatch for the few offsets that genuinely need to stay available.

---

Start with the [[Quick start guide]] to see the normal setup sequence.


In this guide we will protect the common request-related superglobals in a small PHP script.

The normal flow has two steps:

1. collect the values we want to preserve
2. replace the original globals with `ProtectedGlobal` objects

## 1. Install the package

```bash
composer require phpgt/protectedglobal
```

## 2. Create a `Protection` object

```php
use GT\ProtectedGlobal\Protection;

$protection = new Protection();
```

`Protection` is the public entry point for the library.

## 3. Collect the globals we want to protect

```php
$globals = [
	"_ENV" => $_ENV,
	"_SERVER" => $_SERVER,
	"_GET" => $_GET,
	"_POST" => $_POST,
	"_FILES" => $_FILES,
	"_COOKIE" => $_COOKIE,
	"_SESSION" => $_SESSION ?? [],
];
```

The keys should match the superglobal names that will later be overridden.

## 4. Optionally define a whitelist

If some offsets need to remain accessible, we can whitelist them before protection happens:

```php
$whiteList = [
	"_COOKIE" => ["XDEBUG_SESSION"],
	"_ENV" => ["APP_ENV"],
];
```

We will look at this in more detail on [[Whitelisting superglobals]].

## 5. Remove the allowed values from the originals

```php
$allowed = $protection->removeGlobals($globals, $whiteList);
```

`removeGlobals()` returns a new array containing only the values that should remain readable after protection is enabled.

## 6. Override the real superglobals

```php
$protection->overrideInternals($allowed);
```

After this point, accesses such as `$_GET["page"]` or `$_POST["name"]` will throw an exception unless those offsets were whitelisted.

## 7. Use explicit request objects instead of globals

Once the protection is in place, the rest of the application should prefer explicit abstractions.

For example, with PHP.GT/Input:

```php
use GT\Input\Input;

$input = new Input(
	$globals["_GET"],
	$globals["_POST"],
	$globals["_FILES"]
);
```

Or in a framework such as WebEngine, use the injected request-related services instead of reading from the global arrays directly.

> [!NOTE]
> ProtectedGlobal is designed to catch accidental global usage. It is not a validation library and it is not a replacement for request parsing by itself.

---

Next: [[Whitelisting superglobals]]


Whitelisting lets us keep a small number of known-safe offsets available while still blocking everything else.

This is useful when a tool expects one specific cookie, environment variable, or server key to remain readable, but we still want the rest of the superglobal to be protected.

## The whitelist shape

The second argument to `removeGlobals()` is an associative array.

- The keys are superglobal names such as `"_COOKIE"` or `"_SERVER"`.
- The values are lists of offsets that should remain available within that superglobal.

Example:

```php
$whiteList = [
	"_COOKIE" => ["XDEBUG_SESSION"],
	"_SERVER" => ["REQUEST_TIME_FLOAT"],
];
```

## Passing the whitelist to `removeGlobals()`

```php
$allowed = $protection->removeGlobals(
	[
		"_COOKIE" => $_COOKIE,
		"_SERVER" => $_SERVER,
	],
	[
		"_COOKIE" => ["XDEBUG_SESSION"],
		"_SERVER" => ["REQUEST_TIME_FLOAT"],
	]
);
```

The returned `$allowed` array contains only the whitelisted values, ready to be passed into `overrideInternals()`.

## What happens when a whitelisted key is missing?

If a whitelisted offset does not exist in the original array, the library still creates the offset with a value of `null`.

That means this is allowed:

```php
$allowed = $protection->removeGlobals(
	[
		"_ENV" => $_ENV,
	],
	[
		"_ENV" => ["APP_ENV"],
	]
);

$protection->overrideInternals($allowed);

$_ENV["APP_ENV"] = "development";
```

The key did not have to exist before protection started, as long as it was explicitly whitelisted.

## What is still blocked?

Only the named offsets remain available. Everything else still throws `ProtectedGlobalException`.

```php
echo $_SERVER["REQUEST_TIME_FLOAT"]; // Allowed if whitelisted.
echo $_SERVER["HTTP_HOST"];          // Throws if not whitelisted.
```

## Keep the whitelist small

The whitelist is most useful when it stays narrow and deliberate.

- Prefer keeping whole superglobals protected.
- Whitelist only the exact offsets a tool genuinely requires.
- Favour passing data through objects, function arguments, or services instead of relying on globals.

That way the codebase still gains the main benefit of the library: making hidden global dependencies visible.

---

Next: [[Understanding the ProtectedGlobal object]]


`ProtectedGlobal` is the object that replaces the original superglobal arrays after protection has been enabled.

Its job is deliberately simple: allow access to a small internal whitelist, and throw an exception for everything else.

## Array-style access

The class implements `ArrayAccess`, so it can be used with normal array syntax:

```php
$value = $_COOKIE["XDEBUG_SESSION"];
isset($_ENV["APP_ENV"]);
$_ENV["APP_ENV"] = "development";
unset($_ENV["APP_ENV"]);
```

Those operations are only allowed for offsets that were whitelisted earlier.

## Blocked access throws an exception

If code tries to read, write, check, or unset a non-whitelisted offset, the object throws `GT\ProtectedGlobal\ProtectedGlobalException`.

```php
$page = $_GET["page"]; // Throws when "page" was not whitelisted.
```

This is the core behaviour of the library. It does not silently return `null`, and it does not log a warning while continuing. It fails loudly so the accidental dependency can be fixed.

## Allowed offsets remain mutable

When an offset is whitelisted, the value can still be updated or unset through the `ProtectedGlobal` object:

```php
$_ENV["APP_ENV"] = "production";
unset($_ENV["APP_ENV"]);
```

That behaviour is useful for compatibility, but in new code it is still usually better to avoid mutating global state where possible.

## Debug output

If a protected global is converted to a string or dumped in a debugger, the object exposes a warning message instead of pretending to be a normal array.

That makes mistakes more obvious during development:

```php
echo $_GET;
var_dump($_GET);
```

The object includes the warning text and any whitelisted values in its debug information.

---

Next: [[API reference]]


## `GT\ProtectedGlobal\Protection`

`Protection` is the orchestration class. In normal usage we create one instance, call `removeGlobals()`, then pass the result to `overrideInternals()`.

### `removeGlobals(array $globalsToDeregister, array $whiteList = []): array`

Takes an associative array of superglobal data and returns a new array containing only the whitelisted offsets.

Example:

```php
$allowed = $protection->removeGlobals(
	[
		"_GET" => $_GET,
		"_POST" => $_POST,
	],
	[
		"_POST" => ["token"],
	]
);
```

Important points:

- The array keys should match the superglobal names we want to protect, such as `"_GET"` and `"_POST"`.
- The whitelist keys use the same naming.
- Missing whitelisted offsets are created with the value `null`.
- The return value is intended to be passed directly to `overrideInternals()`.

### `overrideInternals(array $whitelistedGlobals): void`

Replaces the internal PHP superglobals with `ProtectedGlobal` objects.

The class protects the following superglobals:

- `$_ENV`
- `$_SERVER`
- `$_GET`
- `$_POST`
- `$_FILES`
- `$_COOKIE`
- `$_SESSION`

Each protected global receives the corresponding whitelisted data from the array passed in.

## `GT\ProtectedGlobal\ProtectedGlobal`

This class implements `ArrayAccess` and acts as the protective wrapper around each superglobal.

### `__construct(array $whiteListData = [])`

Creates a new wrapper around the provided whitelist data.

### Array access methods

The following operations are supported through array syntax:

- `isset($global["key"])`
- `$global["key"]`
- `$global["key"] = $value`
- `unset($global["key"])`

For non-whitelisted offsets, each of those operations throws `ProtectedGlobalException`.

### `WARNING_MESSAGE`

The class exposes a `WARNING_MESSAGE` constant used in string conversion and debug output:

```text
Global variables are protected - see https://php.gt/globals
```

## `GT\ProtectedGlobal\ProtectedGlobalException`

This is the dedicated exception thrown when blocked global access is attempted.

It extends PHP's base `Exception` class and does not add extra methods. Its purpose is semantic clarity: the exception tells us exactly why the access failed.




---

# Documentation: Routing

Routing is the part of an application that decides which code should handle an incoming HTTP request.

## What this library provides

- `BaseRouter`, which finds matching callback methods on your provided router class
- Route attributes such as `#[Get]`, `#[Post]` and `#[Any]`
- Content negotiation using the request's `Accept` header
- `Assembly` objects for ordered logic and view file lists
- Path-matching helpers for static files, magic files and dynamic paths
- `DynamicPath`, which exposes placeholder values from matched routes
- `Redirects`, which reads redirect rules from a CSV file
- `LogicStreamWrapper`, which makes path-mapped plain PHP files safe to load together

## Where this library fits in

For WebEngine projects, most of the wiring is already done. WebEngine creates the request, router, path matcher, dispatcher and response pipeline, then uses this repository as its routing layer.

When using this package directly, we can still build our own router class, pass in a PSR-7 request and decide what to do with the resulting assemblies.

## A minimal example

```php
use GT\Routing\BaseRouter;
use GT\Routing\Method\Get;
use GT\Routing\Method\Post;
use GT\Http\Request;
use GT\Http\Uri;

class AppRouter extends BaseRouter {
	#[Get(path: "/")]
	public function home():void {
		$this->addToViewAssembly("page/index.html");
	}

	#[Post(path: "/contact", accept: "text/html")]
	public function submitContactForm():void {
		$this->addToLogicAssembly("page/contact.php");
		$this->addToViewAssembly("page/contact.html");
	}
}

$router = new AppRouter();
$request = new Request("GET", new Uri("/"));
$router->route($request);

foreach($router->getViewAssembly() as $path) {
	echo $path, PHP_EOL;
}
```

The router callback decides what belongs to the request. Another part of the application can then load the files in the order we assembled.

---

Start with the [[quick start guide]] to build a minimal router, then continue with [[understanding routing]] to see how the pieces fit together.


In this guide we will install `phpgt/routing`, build a router class, pass in a PSR-7 request, and inspect the resulting assemblies.

> [!NOTE]
> When building WebEngine applications, much of this setup is already done for us. WebEngine creates the request, configures the routing layer, and uses the path-matching tools in this repository as part of its request lifecycle. This guide is still useful because it shows the moving parts in isolation.

## 1. Install the package

```bash
composer require phpgt/routing
```

To follow the examples on this page as written, we also need a PSR-7 request implementation. The PHP.GT HTTP package fits naturally here:

```bash
composer require phpgt/http
```

## 2. Create a router class

The router extends `GT\Routing\BaseRouter` and uses attributes to mark routable methods.

```php
use GT\Routing\BaseRouter;
use GT\Routing\Method\Get;
use GT\Routing\Method\Post;

class AppRouter extends BaseRouter {
	#[Get(path: "/")]
	public function home():void {
		$this->addToViewAssembly("page/index.html");
	}

	#[Post(path: "/contact", accept: "text/html")]
	public function submitContactForm():void {
		$this->addToLogicAssembly("page/contact.php");
		$this->addToViewAssembly("page/contact.html");
	}
}
```

At this point we have defined what should happen when the request is for `/`, and what should happen when it is a `POST` request to `/contact`.

## 3. Create a request

This library expects a PSR-7 request. Here we will use `GT\Http\Request` and `GT\Http\Uri`.

```php
use GT\Http\Request;
use GT\Http\Uri;

$request = new Request("GET", new Uri("/"));
```

## 4. Route the request

Now we can instantiate the router and ask it to match the request:

```php
$router = new AppRouter();
$router->route($request);
```

If a callback matches, it will be invoked and the assemblies will be filled.

## 5. Read the assemblies

The router has separate assemblies for logic and view paths, which are iterable containers of one type of file - for instance, the view assembly can contain all the HTML files that build up the current page view, and the logic assemble can contain all PHP files that need executing in order to produce the page logic:

```php
foreach($router->getViewAssembly() as $path) {
	echo "View: $path", PHP_EOL;
}

foreach($router->getLogicAssembly() as $path) {
	echo "Logic: $path", PHP_EOL;
}
```

For the `GET /` request above, the output would include:

```text
View: page/index.html
```

## 6. Add content negotiation

If we want more than one representation of the same URI, we can add `accept` values:

```php
use GT\Routing\Method\Any;

class AppRouter extends BaseRouter {
	#[Any(path: "/report", accept: "text/html")]
	public function htmlReport():void {
		$this->addToViewAssembly("page/report.html");
	}

	#[Any(path: "/report", accept: "application/json")]
	public function jsonReport():void {
		$this->addToLogicAssembly("api/report.php");
	}
}
```

The router will compare those values against the request's `Accept` header and choose the best match.

## 7. Move on to file-based routing

The callback example above is enough to show the core routing flow, but the library also includes the path-matching tools used by WebEngine:

- `PathMatcher`
- `BasicFileMatch`
- `MagicFileMatch`
- `DynamicPath`
- `LogicStreamWrapper`

Those tools are covered in the rest of the guide, starting with [[understanding routing]] and then [[path matching]].

---

Next, continue with [[understanding routing]] for the wider picture of how callback matching and assemblies fit together.


Routing takes an incoming request and decides which part of the application should handle it.

That sounds straightforward, but in practice there are usually two levels of decision to make:

1. Which callback should receive the request
2. Which files make up the response for that request

This library supports both.

## Callback routing

At the first level, `BaseRouter` reflects over the methods on your router class and looks for route attributes.

Each attributed method can match on:

- HTTP method
- request path
- accepted content type

When `route()` is called, every attributed method is checked. The matching callback is then invoked through the service container injector, so the method can receive services such as the current request, a `PathMatcher`, or any application service that has been registered.

## Assembly-based routing

After a callback has matched, the callback usually adds files to one or both assemblies:

- A logic assembly for PHP files to execute
- A view assembly for templates or page fragments to render

The router itself does not execute those files. It only decides what belongs to the request. This keeps routing separate from dispatching and rendering, which can remain the responsibility of the framework.

## Request matching order

The matching process is:

1. Filter by HTTP method
2. Filter by exact path match
3. Filter by `Accept` header compatibility
4. If more than one callback still matches, choose the best candidate by content negotiation

If nothing matches, `BaseRouter::route()` throws `HttpNotAcceptable`.

## Redirect handling

Redirects are separate from callback routing. If we have a redirects CSV file, we can load it through `Redirects` and call `handleRedirects()` before normal routing begins.

The redirect response code comes from `RouterConfig`:

- `300` for `HttpMultipleChoices`
- `301` for `HttpMovedPermanently`
- `302` for `HttpFound`
- `303` for `HttpSeeOther`
- `304` for `HttpNotModified`
- `307` for `HttpTemporaryRedirect`
- Any other configured value falls back to `308` `HttpPermanentRedirect`

## What this library does not do

This repository does not:

- create the PSR-7 request
- emit the final response
- render HTML
- execute assemblies for you

Those jobs belong to the wider application or framework.

---

Continue to [[attribute configuration]] to see how callbacks are declared.


Router callbacks are ordinary methods on a class that extends `BaseRouter`. A method becomes routable when we add one of the route attributes.

## Available attributes

The library provides an attribute for each HTTP method:

- `#[Get]`
- `#[Head]`
- `#[Post]`
- `#[Put]`
- `#[Patch]`
- `#[Delete]`
- `#[Connect]`
- `#[Options]`
- `#[Trace]`
- `#[Any]`

Underneath, these all extend `HttpRouteMethod`, which extends `HttpRoute`.

## Supported attribute arguments

Each method attribute accepts the same optional arguments:

- `path`
- `function`
- `name`
- `accept`

Example:

```php
use GT\Routing\BaseRouter;
use GT\Routing\Method\Get;

class AppRouter extends BaseRouter {
	#[Get(
		path: "/article",
		name: "article-list",
		accept: "text/html,application/xhtml+xml"
	)]
	public function articleList():void {
		$this->addToViewAssembly("page/article/index.html");
	}
}
```

## What each argument means

### `path`

`path` is matched against the request URI path.

At present, callback path matching is exact:

```php
#[Get(path: "/about")]
```

If we need more involved filesystem-style matching, that is usually handled through `PathMatcher` and `DynamicPath` inside the callback rather than in the attribute itself.

### `accept`

`accept` declares which media types the callback is prepared to serve.

```php
#[Get(path: "/feed", accept: "application/json,application/xml")]
```

If several callbacks match the same request path, the best match is chosen from the request's `Accept` header. This is covered in more detail in [[content negotiation]].

### `name`

`name` gives the route a human-readable identifier. This library does not currently use it for reverse routing, but it can still be useful when keeping a large router organised.

### `function`

`function` is accepted by the attribute constructors for compatibility with the wider WebEngine routing model, where the same route metadata may be used alongside logic methods or function-based handlers.

In this repository's callback execution flow, the reflected router method itself is what gets called.

## Dependency injection in callbacks

Router callbacks are invoked through `GT\ServiceContainer\Injector`, so parameters can be resolved from the container.

```php
use GT\Routing\Method\Any;
use GT\Routing\Path\PathMatcher;
use GT\Http\Request;

#[Any]
public function page(Request $request, PathMatcher $pathMatcher):void {
	// ...
}
```

That means the callback can stay focused on routing decisions rather than container lookups.

## Matching examples

### Match any request

```php
#[Any]
public function fallback():void {
}
```

### Match one method and one path

```php
#[Post(path: "/login")]
public function login():void {
}
```

### Match by content type

```php
#[Get(path: "/report", accept: "text/html")]
public function htmlReport():void {
}

#[Get(path: "/report", accept: "application/json")]
public function jsonReport():void {
}
```

---

Once a callback matches, it will usually add files to the logic or view list. Read [[assemblies]] next.


An `Assembly` is an ordered list of file paths.

Routing uses two assemblies:

- the logic assembly
- the view assembly

The router builds them up; another part of the application can then execute or render them in order.

## Why assemblies exist

Many routed responses are made of more than one file. In WebEngine, for example, a request may include:

- a shared `_header.html`
- a page-specific `index.html`
- a shared `_footer.html`
- one or more logic files such as `_common.php` and a page-specific PHP file

The assembly gives us a single object that represents that ordered list.

## Working with an assembly

`Assembly` implements `Iterator` and `Countable`, so we can append files and then loop over them later.

```php
use GT\Routing\Assembly;

$assembly = new Assembly();
$assembly->add("page/_header.html");
$assembly->add("page/index.html");
$assembly->add("page/_footer.html");

foreach($assembly as $path) {
	echo $path, PHP_EOL;
}
```

The class also supports:

- `replace($oldPath, $newPath)`
- `remove($path)`
- `count()`

## Distinct files and magic files

`Assembly::containsDistinctFile()` answers a specific question: does the assembly contain anything more specific than the framework's magic wrapper files?

The magic filenames recognised here are:

- `_common`
- `_header`
- `_footer`

If an assembly contains only those wrapper files, `containsDistinctFile()` returns `false`. This is useful when deciding whether a route has a page-specific match or only inherited shared files.

## Adding files from a router callback

`BaseRouter` exposes protected helpers for adding to the current router's assemblies:

```php
use GT\Routing\BaseRouter;
use GT\Routing\Method\Get;

class AppRouter extends BaseRouter {
	#[Get(path: "/")]
	public function home():void {
		$this->addToLogicAssembly("page/index.php");
		$this->addToViewAssembly("page/index.html");
	}
}
```

## View class support

`BaseRouter` also allows a view class name to be set separately with `setViewClass()` and read with `getViewClass()`. That gives the wider application one more hook when it decides how to dispatch the matched route.

## Access timing

`getLogicAssembly()` is only available after `route()` has completed. If we try to read it before routing, `NotYetRoutedException` is thrown.

`getViewAssembly()` can be read directly because view selection may begin while the router is still building up the route.

---

Assemblies often contain files found through content-aware matching. The next part of the routing decision is covered in [[content negotiation]].


Content negotiation is how the router chooses the best callback when more than one route matches the same request.

This is especially useful when the same URI can serve different representations, such as HTML for a browser and JSON for an API client.

## Accept header

Browsers often send broad `Accept` headers. A normal page request may include values such as:

```http
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
```

Without content negotiation, a callback that merely mentions `application/xml` could accidentally win over a page route. The router avoids that by comparing the quality values and selecting the best match.

Each callback can declare one or more accepted media types:

```php
#[Any(path: "/report", accept: "text/html,application/xhtml+xml")]
public function html():void {}

#[Any(path: "/report", accept: "application/json,application/xml")]
public function data():void {}
```

When `route()` runs:

1. callbacks that do not match the request method are ignored
2. callbacks that do not match the request path are ignored
3. callbacks whose `accept` value is incompatible with the request are ignored
4. the remaining callbacks are ranked using the negotiated quality value

The callback with the highest quality wins.

## `*/*` behaviour

If the request sends `Accept: */*`, the first matching compatible callback wins.

That keeps the result deterministic even when the client has not expressed any preference.

## Media type declaration format

The `accept` argument is a comma-separated string, for example:

```php
accept: "application/json,application/xml"
```

or:

```php
accept: "text/html,application/xhtml+xml,application/xml;q=0.9"
```

## When to use content negotiation

Use it when the same URI can return more than one representation:

- HTML and JSON from the same route name
- HTML and XML feeds
- Human-facing pages and machine-facing endpoints that share a common path

If the URI already separates those concerns clearly, content negotiation may not be necessary.

---

The callback usually hands off to filesystem matching after it has been selected. That is covered in [[path matching]].


The callback router decides _which_ route has matched. `PathMatcher` helps us decide _which files_ belong to that route.

This is the layer that WebEngine uses to map request paths to page logic and page view files on disk, but applies to any application's usage.

## `PathMatcher`

`PathMatcher` scans a directory tree and returns file paths that match a request URI.

On its own, it only walks the filesystem and filters by extension. The actual matching rules come from filter callbacks that we add with `addFilter()`.

```php
use GT\Routing\Path\PathMatcher;

$matcher = new PathMatcher("page");
$matcher->addFilter(function(
	string $filePath,
	string $uriPath,
	string $baseDir
):bool {
	// return true when this file belongs to the request
});
```

`findForUriPath()` then returns the matching files:

```php
$matches = $matcher->findForUriPath("/shop/phones", "page", "php", "html");
```

## File matching helpers

The repository provides three important helper types for building those filters.

### `BasicFileMatch`

`BasicFileMatch` handles direct path-to-file matching.

Examples:

- `/about` matches `page/about.html`
- `/blog` matches `page/blog/index.html`
- `/shop/cakes/chocolate` matches `page/shop/@category/@item.html`

It also takes sibling files into account so that dynamic placeholders do not swallow real files. For example, if both `page/request/@request-id.html` and `page/request/secrets.html` exist, the URI `/request/secrets` matches the concrete file rather than the dynamic placeholder.

### `MagicFileMatch`

`MagicFileMatch` recognises shared wrapper files that apply to a request because of where they sit in the directory tree.

The recognised magic names are:

- `_common`
- `_header`
- `_footer`

So a request for `/shop/item` can legitimately include:

- `page/_header.html`
- `page/shop/_common.php`
- `page/shop/item.html`
- `page/_footer.html`

### `DirectoryExpander`

`DirectoryExpander` is the low-level iterator used by `PathMatcher` to walk a directory tree recursively.

Most applications will not use it directly, but it can be swapped in for testing or custom directory behaviour.

## Typical filter setup

The repository's example project uses both basic and magic matching:

```php
$pathMatcher->addFilter(function(string $filePath, string $uriPath, string $baseDir):bool {
	$basicFileMatch = new BasicFileMatch($filePath, $baseDir);
	if($basicFileMatch->matches($uriPath)) {
		return true;
	}

	$magicFileMatch = new MagicFileMatch($filePath, $baseDir);
	return $magicFileMatch->matches($uriPath);
});
```

## Ordering

`PathMatcher` returns matching paths in directory-depth order. Applications often perform an additional sort before dispatching so that wrappers such as headers and footers are rendered in the correct place.

---

When dynamic placeholders are involved, we usually want to read the actual URI values back out. That is what [[dynamic path mapping]] covers.


Dynamic path mapping is how we move from a placeholder on disk to the real values from the request URI.

This repository uses `@` in filenames and directory names to mark dynamic path parts.

## Named placeholders

A named placeholder uses a single `@` prefix:

```text
page/shop/@category/@itemName.html
```

If the request URI is:

```text
/shop/phones/nexus-5
```

we can read the values through `DynamicPath`:

```php
use GT\Routing\Path\DynamicPath;

$dynamicPath = new DynamicPath("/shop/phones/nexus-5", $viewAssembly, $logicAssembly);

echo $dynamicPath->get("category"); // phones
echo $dynamicPath->get("itemName"); // nexus-5
```

## The deepest dynamic value

If we call `get()` with no argument, the deepest matching dynamic part is returned.

```php
echo $dynamicPath->get();
```

For `/shop/phones/nexus-5`, that returns `nexus-5`.

## Deeper paths with `@@`

Sometimes the route needs to match the start of a path and then leave the rest untouched. That is what the double-`@` form is for:

```text
page/shop/@category/@@itemName.php
```

For a URI such as:

```text
/shop/phones/nexus-5/128gb/refurbished
```

we get:

- `get("category")` => `phones`
- `get("itemName")` => `nexus-5`
- `getExtra()` => `128gb/refurbished`

`getExtra()` returns an `Extra` object, which can also expose individual path segments:

```php
$extra = $dynamicPath->getExtra();
echo $extra;             // 128gb/refurbished
echo $extra->getIndex(0); // 128gb
```

## Building a URL from a matched assembly

`DynamicPath::getUrl()` works in the other direction. It inspects the view assembly and returns the matched route pattern relative to a base path:

```php
echo $dynamicPath->getUrl("page/");
// /shop/@category/@itemName
```

This is useful when we want the route shape rather than the literal request URL.

`DynamicPath` reads the file paths that were actually added to the assemblies. That means it does not invent placeholder values itself; it only reflects the route that was already matched by the path-matching stage.

---

In many projects, it's useful to store redirected paths in the project - read [[redirects]] next.


`Redirects` provides an iterator over redirect rules stored in CSV format.

It is designed so we can keep straightforward URL migrations in a file rather than hard-coding them into router callbacks.

## CSV format

Each row contains:

1. the old URI
2. the new URI

Example:

```csv
/about-us,/about
/product/1234,/product/widget-1234
/dir/nested/old-link,/other-dir/new-link,303
```

## Loading redirects

We can construct the object with either a pathname or an `SplFileObject`:

```php
use GT\Routing\Redirects;

$redirects = new Redirects("redirects.csv");
```

## Applying redirects

`BaseRouter::handleRedirects()` checks the current request path against the redirect list and throws the appropriate HTTP redirect exception when it finds a match.

```php
$router->handleRedirects($redirects, $request);
```

In practice we would usually do this before calling `route()`.

The comparison is against the request path, so these rules should be written as path-to-path redirects rather than full URI strings with query components.

## Redirect response code

The redirect status comes from `RouterConfig::$redirectResponseCode`.

Supported mappings are:

- `300` => `HttpMultipleChoices`
- `301` => `HttpMovedPermanently`
- `302` => `HttpFound`
- `303` => `HttpSeeOther`
- `304` => `HttpNotModified`
- `307` => `HttpTemporaryRedirect`
- any other configured value => `HttpPermanentRedirect` (`308`)

## Iterating manually

`Redirects` implements `Iterator`, so we can inspect or transform the data before applying it:

```php
foreach($redirects as $from => $to) {
	echo "$from -> $to", PHP_EOL;
}
```

---

To increase simplicity of application routes, logic can be stored in path-mapped files rather than namespaced classes. Read about this in the [[logic stream wrapper]] section.


`LogicStreamWrapper` exists for one specific problem: path-mapped logic files often declare the same function names, such as `go()`.

If we load several of those files in one PHP process, the function names would normally collide. The stream wrapper prevents that by injecting a namespace when the file does not already declare one.

## Why this is needed

A typical WebEngine request may load several logic files:

- `page/_common.php`
- `page/shop/_common.php`
- `page/shop/@category/index.php`

All of them may define a function called `go()`. Without namespacing, PHP would reject the second declaration.

## What the wrapper does

When a file is required through the stream wrapper:

1. the file must begin with `<?php`
2. if it already declares a namespace, that namespace is left in place
3. otherwise a namespace is injected based on the file path
4. unqualified internal PHP class names are prefixed so built-in types such as `DateTime` still resolve correctly inside the injected namespace

The generated namespace prefix is:

```text
GT\AppLogic
```

with the file path appended and normalised.

## Registering the wrapper

```php
use GT\Routing\LogicStream\LogicStreamWrapper;

stream_wrapper_register("gt-logic-stream", LogicStreamWrapper::class);
require "gt-logic-stream://page/shop/_common.php";
```

## Namespace generation

The namespace path is handled by `LogicStreamNamespace`, which converts path separators and unsupported characters into namespace-safe names.

For example, a path such as:

```text
/tmp/page/shop/@category/index.php
```

becomes a generated namespace rooted under `GT\AppLogic`.

## File requirements

For the wrapper to work correctly:

- the file must be a PHP file
- it must begin with an opening PHP tag
- it should contain only PHP code, and have no side effects (including it should only declare symbols, not echo content)

If the opening tag is missing, the wrapper throws an exception explaining which file failed.

## When we need this page

If we are only using class-based router callbacks, we may never need the stream wrapper.

If we are building a filesystem-mapped application runtime, or trying to understand how WebEngine can load many `go()` functions in one request, this is the missing piece.

---

To see how the callback router, path matcher, dynamic paths and stream wrapper are used together, read [[example project]].


The repository includes a project under `example/project/simple-site/` that shows how the pieces fit together.

It is not a full framework. Its value is that we can see the routing flow directly, without any extra abstraction.

## Project structure

The example contains:

- `app-router.php` for the router class
- `config.ini` for router and application configuration
- `page/` for page view and page logic files
- `api/v1/` for API logic files
- `class/` for ordinary application classes

## The flow

The entry script in `example/01-test.php` does the following:

1. loads configuration
2. creates a PSR-7 request
3. creates a service container
4. configures a `PathMatcher`
5. loads the application router class
6. handles redirects if a CSV file exists
7. calls `route()`
8. reads the resulting logic and view assemblies
9. registers the logic stream wrapper
10. loads each logic file and calls its `go()` function

That is essentially the routing part of a framework laid out in one file.

## Router callbacks in the example

The router has three callbacks:

### `api()`

```php
#[Any(name: "api-route", accept: "application/json,application/xml")]
```

This callback adds matching logic files from `api/v1/` to the logic assembly.

### `page()`

```php
#[Get(name: "page-route", accept: "text/html,application/xhtml+xml")]
```

This callback adds matching PHP logic files from `page/` and matching HTML view files from `page/`.

### `dynamicText()`

```php
#[Post(path: "/greet/@name", function: "greet", accept: "text/plain")]
```

This callback is part of the example project's layout, but it is worth noting that callback `path` matching in `BaseRouter` is currently exact. Dynamic placeholder matching in this repository is handled by the path-matching layer described in [[Path matching]] and [[Dynamic path mapping]].

## Path matching in the example

The example's `PathMatcher` filter uses:

- `BasicFileMatch` for direct file matches
- `MagicFileMatch` for `_common`, `_header` and `_footer` style files

That combination is enough to build a request assembly for both nested pages and dynamic routes.

## Dynamic path access

The example's page logic reads values from `DynamicPath`, for example:

```php
function go(DynamicPath $path) {
	echo "SHOP ITEM: " . $path->get("itemName"), PHP_EOL;
}
```

This shows how placeholder values from the route can be injected into ordinary PHP logic.

## Why this matters

This example is the clearest place to see the repository's boundary:

- the router decides what belongs to the request
- the assemblies record the result
- another layer then loads the files and produces the response

That same separation is what allows WebEngine to use this library as a component.




---

# Documentation: Server

This webserver is for use with WebEngine projects. Starting the server executes the PHP inbuilt server and uses the WebEngine `go.php` entry point as the router script.

When requiring this project directly using Composer, run the server by calling vendor/bin/serve. If you're using the [PHPGT Installer](https://www.php.gt/installer) you can start the server on its own with the `gt serve` command, or with the other background processes with the `gt run` command.

// TODO: More documentation



---

# Documentation: ServiceContainer

PHP.GT/ServiceContainer is a small dependency injection library centred around two classes: `Container` stores services, and `Injector` invokes functions or methods with those services supplied automatically.

It is intentionally small: There's no compiled container, no configuration format, and no separate definition step. Object instances are registered directly, or lazy loaders can be registered that know how to build them later.

> [!NOTE]
> If you are building with WebEngine, this library is usually already in place for you. The framework uses it to provide typed objects to page logic such as `go()` and `do()` functions.

## What this library does

- Stores object instances by class name.
- Resolves interfaces and parent classes to registered concrete objects.
- Supports lazy service construction through callbacks.
- Can discover loader methods from a plain PHP object by reading return types.
- Invokes functions and methods by matching parameter types to registered services.
- Implements `Psr\Container\ContainerInterface`.

## A tiny example

```php
use GT\ServiceContainer\Container;
use GT\ServiceContainer\Injector;

// The example class we'll pass to the container:
class HelloWorld {
	public function greet():string {
		return "Hello, world!";
	}
}

// This function will be called with the HelloWorld object already instantiated:
function example(HelloWorld $helloWorld):string {
	return "<p>" . $helloWorld->greet() . "</p>";
}

// Start a Container and insert an instance of HelloWorld. 
$container = new Container();
$container->set(new HelloWorld());

// Give an Injector a reference to the container:
$injector = new Injector($container);

// Finally, call the example function above - the function's parameters are
// handled automatically.
$html = $injector->invoke(null, example(...));
```

In a nutshell: your application code asks for typed objects in function parameters, and the service container supplies them from one central place.

---

To get set up from scratch, read [[Getting started]].


In this section we will build the smallest useful setup from scratch.

The public API is deliberately small. Most applications only need one `Container` to store services and one `Injector` to call functions with those services.

## 1. Install the library

```bash
composer require phpgt/servicecontainer
```

## 2. Create a service class

```php
class Greeter {
	public function greet(string $name = "you"):string {
		return "Hello, $name!";
	}
}
```

This is just a normal PHP class. The service container does not require your classes to extend or implement anything special.

## 3. Register an object in the container

```php
use GT\ServiceContainer\Container;

$container = new Container();
$container->set(new Greeter());
```

The `set()` method stores object instances by class name. The same call also makes the object available through any interfaces or parent classes it implements.

## 4. Read the object back

```php
$greeter = $container->get(Greeter::class);
echo $greeter->greet("Cody");
```

Lookups are case-insensitive, but it is still best to use `::class` wherever possible.

## 5. Invoke a function with automatic injection

The injector reflects the callable's parameter list and asks the container for the matching service type.

```php
use GT\ServiceContainer\Injector;

$injector = new Injector($container);

$output = $injector->invoke(null, function(Greeter $greeter):string {
	return $greeter->greet("Cody");
});

echo $output;
```

The injector is the main feature of this library. It allows a function to have any parameters in any order, and as long as the correctly typed objects exist in the container, the function will be invoked automatically, with all the correct paramters.

## 6. Invoke an object method

```php
class PageActions {
	public function home(Greeter $greeter):string {
		return $greeter->greet();
	}
}

$page = new PageActions();
echo $injector->invoke($page, "home");
```

Pass the object instance as the first argument and the method name as the second.

## 7. Supply non-service values explicitly

Services are matched by type. If a callable also needs another typed value that should not come from the container, pass it in the third argument:

```php
$date = new DateTime("2026-04-17");

$output = $injector->invoke(null, function(
	Greeter $greeter,
	DateTime $today,
):string {
	return $greeter->greet($today->format("l"));
}, [
	DateTime::class => $date,
]);
```

The key must match the parameter type name.

---

The basics are now in place. Next, move on to [[Container class]] to see exactly how services are stored and resolved.


The `Container` class is the registry of services used by your application. It stores object instances, resolves them by type, and can defer creation until first use.

It implements `Psr\Container\ContainerInterface`, so it can also be passed to code that expects a PSR-11 compatible container.

## Constructing a container

```php
use GT\ServiceContainer\Container;

$container = new Container();
```

In normal application code, the constructor does not need any arguments.

An optional `Injector` can be supplied, which is mainly useful when composing advanced setups or tests:

```php
use GT\ServiceContainer\Container;
use GT\ServiceContainer\Injector;

$baseContainer = new Container();
$injector = new Injector($baseContainer);
$container = new Container($injector);
```

Without any arguments, a default Injector is used. In practice, most projects should just use the no-argument form.

## Setting services

Use `set()` to store one or more object instances:

```php
$container->set(
	new Greeter(),
	new DateTimeImmutable(),
);
```

Only objects may be registered this way. Scalars, arrays, and `null` are rejected with a `ServiceContainerException`.

## Getting services

Use `get()` with a class name:

```php
$greeter = $container->get(Greeter::class);
```

If the service has not been registered and there is no loader for it, a `ServiceNotFoundException` is thrown.

## Checking if a service exists

Use `has()` when you need to test availability first:

```php
if($container->has(Greeter::class)) {
	$greeter = $container->get(Greeter::class);
}
```

`has()` and `get()` are both case-insensitive.

## Interface and parent class resolution

When an object is registered, the container also exposes it through its interfaces and parent classes.

```php
interface GreetingInterface {
	public function greet():string;
}

class Greeter implements GreetingInterface {
	public function greet():string {
		return "Hello!";
	}
}

$container->set(new Greeter());
$greeting = $container->get(GreetingInterface::class);
```

This makes the library useful in applications that depend on abstractions instead of concrete classes.

## One service per type

The container keeps a single value for each class or interface name. Registering another object of the same type replaces the previous one for that key.

This library does not try to manage multiple named services of the same type. If you need that, create a higher-level application object that exposes the variation you need.

---

When service construction should be deferred until first use, use [[Lazy loaders]].


Lazy loaders allow the container to construct a service only when it is first requested.

This is useful when a service is expensive to create, depends on other services, or should only exist in some requests.

## Register a loader callback

Use `setLoader()` to associate a class name with a callback:

```php
$container->setLoader(Greeter::class, function():Greeter {
	return new Greeter();
});
```

On the first `get(Greeter::class)`, the callback is invoked and the returned object is stored in the container.

Subsequent calls return the same instance, not a fresh object each time.

This means that in applicaiton code, if an object isn't used, it isn't constructed - and if it's used more than once, it's only ever constructed once.

## Nullable loaders

Loaders may return `null` if the return type allows it:

```php
$container->setLoader(Greeter::class, function():?Greeter {
	return null;
});
```

After the first lookup, `null` is cached for that type. This can be useful when a service is genuinely optional. For example, a `User` object could be nullable in application code if an area of the application allows non-authenticated use. Requesting `?User` can be used as an indicator to whether the user has authenticated yet.

## Loader callbacks can use injected dependencies

Loader callbacks are invoked through the library's `Injector`, so the callback itself can declare service dependencies:

```php
$container->setLoader(UriGreeter::class, function(GreetingInterface $greeter):UriGreeter {
	return new UriGreeter($greeter);
});
```

As long as `GreetingInterface` can be resolved by the container, the loader can depend on it.

This means loaders can be chained together naturally.

## Register loader methods from an object

If you prefer not to register each loader manually, use `addLoaderClass()`:

```php
$container->addLoaderClass(new class {
	public function loadGreeter():GreetingInterface {
		return new Greeter();
	}

	public function loadUriGreeter(GreetingInterface $greeter):UriGreeter {
		return new UriGreeter($greeter);
	}
});
```

The container scans every public method on the object. Any method with a declared return type becomes a loader for that type.

Methods without a return type are ignored.

## Return types define the service key

With `addLoaderClass()`, the method name does not matter. The return type is what determines which service the method loads.

Because of that, this is valid:

```php
$container->addLoaderClass(new class {
	public function doTheGreetThing():GreetingInterface {
		return new Greeter();
	}
});
```

The service is still resolved via `GreetingInterface::class`.

## Base classes and interfaces from loaders

When a loader is added for a concrete class, its parent classes and implemented interfaces are also mapped to that same loader.

That means a loader for `Greeter` can also satisfy `GreetingInterface` if `Greeter` implements it.

---

To see how services are passed into functions and methods, continue to the [[Injector class]] section.


The `Injector` class is responsible for invoking callables and filling their parameters from the container.

It uses reflection to inspect the callable signature, then requests each typed dependency from the `Container`.

## Constructing an injector

```php
use GT\ServiceContainer\Container;
use GT\ServiceContainer\Injector;

$container = new Container();
$injector = new Injector($container);
```

Most applications create one injector for one container.

## Invoking a standalone function or closure

Pass `null` as the first argument and the callable as the second:

```php
$result = $injector->invoke(null, function(Greeter $greeter):string {
	return $greeter->greet();
});
```

The injector reflects the closure's parameters and resolves `Greeter` from the container.

## Invoking an object method

To call a method on an existing object, pass the object instance and the method name:

```php
class ExamplePage {
	public function go(Greeter $greeter):string {
		return $greeter->greet();
	}
}

$page = new ExamplePage();
$result = $injector->invoke($page, "go");
```

This is the pattern commonly used in framework code where the object instance already exists.

## Supplying explicit argument values

The optional third argument lets you provide values that should not come from the container:

```php
$result = $injector->invoke($page, "showBirthday", [
	DateTime::class => new DateTime("1988-04-05 17:24"),
]);
```

These values are matched by parameter type name and take precedence over container lookups.

This is especially useful for request-specific values or test doubles.

## Nullable parameters

If a parameter type allows `null` and the container cannot resolve it, the injector supplies `null` instead of throwing an exception:

```php
class ExamplePage {
	public function go(?Greeter $greeter):void {
		if($greeter) {
			echo $greeter->greet();
		}
	}
}
```

If the parameter is not nullable, unresolved services still raise `ServiceNotFoundException`.

## Important limitation

This injector expects typed parameters so it knows what to request from the container. Untyped parameters are not part of the library's public contract.

In practical terms, treat typed parameters as required when using `Injector`.

---

For the error types exposed by the library, continue to [[Exception handling]].


This library exposes two exception types.

Both are runtime exceptions, and both follow the PSR container exception interfaces.

## `ServiceContainerException`

`ServiceContainerException` is the general-purpose container exception type. It implements `Psr\Container\ContainerExceptionInterface`.

You will most commonly see it when invalid values are passed to `Container::set()`:

```php
$container->set("not an object");
```

Only objects may be registered directly. If a string, array, integer, or `null` is supplied, this exception is thrown with a message explaining the invalid type.

## `ServiceNotFoundException`

`ServiceNotFoundException` extends `ServiceContainerException` and implements `Psr\Container\NotFoundExceptionInterface`.

It is thrown when the container cannot resolve a requested type:

```php
$container->get(Greeter::class);
```

The same exception may be raised indirectly by `Injector` when invoking a callable that requires a non-nullable service the container does not have.

## When exceptions are not thrown

There are two cases where missing services do not raise an exception:

- `Container::has()` returns `false` instead of throwing.
- `Injector` injects `null` for a missing service when the parameter type is nullable.

These two behaviours make it possible to model genuinely optional services without special container configuration.




---

# Documentation: Session

`phpgt/session` gives us an object-oriented way to work with PHP session data without reading and writing the `$_SESSION` superglobal directly.

Sessions are useful whenever a web application needs to remember short-lived information about one visitor between HTTP requests. Common examples include whether someone is logged in, which step of a form they are on, or which message should be shown after a redirect.

PHP already has session support, but the native API stores everything in global state. This library wraps the session in objects, so we can pass only the session area a piece of code needs.

> [!NOTE]
> In WebEngine applications, the session is created during request initialisation and placed into the service container. Page logic can ask for `GT\Session\Session` directly, without constructing it manually.

## What this library covers

- A `Session` object that starts PHP's session mechanism and reads persisted data.
- Dot-notation keys for grouping session data into named areas.
- `SessionStore` objects that can be passed to one part of an application without giving access to the whole session.
- Type-safe getters through `phpgt/typesafegetter`.
- File-backed session storage through `FileHandler`.
- Redis-compatible shared session storage through `RedisHandler`.
- Flash messages for one-request notifications.

## A small example

```php
use GT\Session\Session;

function showAccount(Session $session):void {
	if($session->contains("auth.userId")) {
		echo "Signed in as user ", $session->getInt("auth.userId");
		return;
	}

	echo "Please sign in.";
}
```

Here the `auth.userId` key means: read the `userId` value from the `auth` area of the session. That same `auth` area can be passed to another class as its own `SessionStore`, so that class cannot accidentally read or write unrelated session data.

---

To see a complete setup from scratch, continue with the [[Quick start guide]].


PHP sessions let a server recognise the same visitor across multiple HTTP requests.

HTTP itself is stateless. When someone loads one page, then clicks to another page, the second request does not automatically know anything about the first one. PHP solves this by sending a session cookie to the browser. The cookie contains a session ID, and PHP uses that ID to find the matching data on the server.

The important part is that the cookie only identifies the session. The actual session data should stay on the server.

## Why wrap PHP sessions in objects?

Native PHP exposes session values through `$_SESSION`. That works, but it means any line of PHP can read or change any session value.

This library gives us a smaller, safer shape:

- `Session` represents the whole session.
- `SessionStore` represents one named area inside the session.
- Dot-notation keys let us write simple code while keeping data grouped.
- Type-safe getters make common reads clearer.

## The basic pattern

```php
use GT\Session\Session;

function do_login(Session $session, User $user):void {
	$session->set("auth.userId", $user->id);
	$session->set("auth.email", $user->email);
}

function go(Session $session):void {
	$email = $session->getString("auth.email");

	if($email) {
		echo "Welcome back, $email";
	}
}
```

The full key is written as a string, but the library stores the data in nested `SessionStore` objects. The `auth` store contains `userId` and `email`.

## Encapsulation

The most useful part of this library is that we can pass a smaller store to another object:

```php
use GT\Session\Session;
use GT\Session\SessionStoreInterface;

class LoginTracker {
	public function __construct(
		private SessionStoreInterface $session
	) {}

	public function markAttempt():void {
		$count = $this->session->getInt("attempts") ?? 0;
		$this->session->set("attempts", $count + 1);
	}
}

function example(Session $session):void {
	$tracker = new LoginTracker(
		$session->getStore("auth", true)
	);

	$tracker->markAttempt();
}
```

`LoginTracker` can read and write inside `auth`, but it has no direct access to other top-level stores.

> [!NOTE]
> WebEngine's protected global behaviour is designed around this idea. Application code should ask for the objects it needs instead of reaching into PHP superglobals.

---

Next, build the smallest standalone example in the [[Quick start guide]].


In this guide we will build the smallest useful standalone session setup.

In WebEngine applications, this setup is already done for us. The guide is still useful because it shows the shape of the objects that WebEngine provides.

## 1. Install the package

```bash
composer require phpgt/session
```

## 2. Create a session handler

The handler controls where the session data is stored.

```php
use GT\Session\FileHandler;

$handler = new FileHandler();
```

`FileHandler` stores session data as files under the configured save path. If shared storage across multiple application servers is needed, use [[Redis session storage]] instead.

## 3. Create the session

```php
use GT\Session\Session;

$session = new Session($handler, [
	"name" => "GT",
	"save_path" => "phpgt/session",
]);
```

When the save path is not an absolute path, the library places it under the system temporary directory. On many systems, the example above becomes something like `/tmp/phpgt/session/GT`.

## 4. Write values

```php
$session->set("auth.userId", 105);
$session->set("auth.email", "cody@example.com");
```

Calling `set()` writes the value into the in-memory `SessionStore`, then immediately asks the handler to persist the session data.

## 5. Read values

```php
if($session->contains("auth.userId")) {
	echo $session->getInt("auth.userId");
	echo $session->getString("auth.email");
}
```

The typed getters return `null` when the value does not exist. If a value does exist, it is converted to the requested type where possible.

## 6. Remove values

```php
$session->remove("auth.email");
```

`remove()` can remove a single value, or a whole nested store when the key points to a store name.

## 7. Pass a smaller store to another object

```php
use GT\Session\SessionStoreInterface;

class Basket {
	public function __construct(
		private SessionStoreInterface $session
	) {}

	public function addItem(string $sku):void {
		$items = $this->session->get("items") ?? [];
		$items []= $sku;
		$this->session->set("items", $items);
	}
}

$basket = new Basket($session->getStore("basket", true));
$basket->addItem("TEA-001");
```

The `Basket` class only receives the `basket` store. It does not need to know about `auth`, flash messages, or any other session data.

> [!NOTE]
> In WebEngine, `GT\Session\Session` is injected into page logic from the service container. We usually start from `function go(Session $session):void` or `function do_save(Session $session):void`, rather than constructing it ourselves.

---

Next, see the constructor and setup options in [[Constructing a Session]].


`Session` is the main entry point to the library.

The constructor accepts:

1. a PHP `SessionHandlerInterface`
2. an optional configuration array
3. an optional session ID

```php
use GT\Session\FileHandler;
use GT\Session\Session;

$session = new Session(
	new FileHandler(),
	[
		"name" => "GT",
		"save_path" => "phpgt/session",
	]
);
```

## Using `SessionSetup`

`SessionSetup` is a small helper for creating and attaching a handler class by name.

```php
use GT\Session\FileHandler;
use GT\Session\Session;
use GT\Session\SessionSetup;

$setup = new SessionSetup();
$handler = $setup->attachHandler(FileHandler::class);

$session = new Session($handler, [
	"name" => "GT",
	"save_path" => "phpgt/session",
]);
```

If the handler class is not PHP's built-in `SessionHandler`, `SessionSetup` calls `session_set_save_handler()` before the session starts.

## Configuration keys

The constructor passes session options through to `session_start()`.

Common keys are:

- `name`
- `save_path`
- `use_only_cookies`
- `use_cookies`
- `use_trans_sid`
- `cookie_lifetime`
- `cookie_path`
- `cookie_domain`
- `cookie_secure`
- `cookie_httponly`
- `cookie_samesite`
- `use_strict_mode`

The library also forces PHP's session serialiser to `php_serialize`, because the stored data is a serialised `SessionStore` object.

## Defaults

When a config value is not supplied, `Session` uses these defaults:

- session name: `PHPSESSID`
- save path: `/tmp`
- cookie lifetime: `0`
- cookie path: `/`
- cookie domain: empty string
- secure cookie: `true`
- HTTP-only cookie: `true`
- SameSite policy: `Lax`
- strict mode: `true`
- cookies only: `true`
- trans SID: `false`

`cookie_lifetime` of `0` means the browser treats the cookie as a session cookie, normally clearing it when the browser session ends.

## Save paths

The `save_path` can be a filesystem path or a DSN.

Filesystem paths are normalised to the operating system's directory separator. Relative paths are placed under `sys_get_temp_dir()`.

```php
use GT\Session\FileHandler;

$session = new Session(new FileHandler(), [
	"save_path" => "phpgt/session",
]);
```

DSN-style save paths are left unchanged, so they can be passed to handlers such as `RedisHandler`.

```php
use GT\Session\RedisHandler;

$session = new Session(new RedisHandler(), [
	"save_path" => "rediss://default:secret@example.internal:25061/0",
]);
```

## Supplying a session ID

The third constructor argument can be used when the caller already knows the session ID.

```php
$session = new Session($handler, $config, $sessionIdFromCookie);
```

If no ID is supplied, the library asks PHP for the current `session_id()`. If PHP has not created one yet, it calls `session_create_id()`.

> [!NOTE]
> WebEngine reads the configured session name, handler and path from `config.ini`, finds the current cookie value, attaches the handler, and then constructs `Session` for the request.

---

Next, learn how to organise data in [[Session stores and namespaces]].


`SessionStore` is the object that actually holds session values.

The root `Session` object delegates reads and writes to a root store. Nested stores can then represent separate areas of the session, such as `auth`, `basket`, `ui`, or `csrf`.

## Dot notation

Keys can contain dots. Everything before the final dot is treated as a store path, and the final part is the value name.

```php
$session->set("user.name", "Cody");
$session->set("user.colour", "orange");
```

That creates a `user` store with two values:

- `name`
- `colour`

We can read those values with the same dot notation:

```php
echo $session->getString("user.name");
```

## Creating a store

`getStore()` returns a `SessionStoreInterface` when the store exists.

```php
$authStore = $session->getStore("auth");
```

If the store might not exist yet, pass `true` as the second argument:

```php
$authStore = $session->getStore("auth", true);
```

That pattern is common when constructing a class that owns one area of session data.

## Passing a store to another class

```php
use GT\Session\SessionStoreInterface;

class AuthSession {
	public function __construct(
		private SessionStoreInterface $session
	) {}

	public function signIn(int $userId):void {
		$this->session->set("userId", $userId);
	}

	public function getUserId():?int {
		return $this->session->getInt("userId");
	}
}

$auth = new AuthSession($session->getStore("auth", true));
```

Inside `AuthSession`, the key is just `userId`. The class does not need to know that the value is stored at `auth.userId` in the full session.

This is the core encapsulation benefit: each part of the application receives only the session area it owns.

## Nested stores

Stores can be nested more than one level deep.

```php
$session->set("checkout.payment.lastMethod", "card");

$paymentStore = $session->getStore("checkout.payment");
echo $paymentStore->getString("lastMethod");
```

Nested stores are useful when one larger area of the application has smaller sub-areas.

## Removing data

Remove a single value:

```php
$session->remove("auth.userId");
```

Remove a nested store:

```php
$session->remove("checkout.payment");
```

Calling `remove()` on a `SessionStore` without an argument removes that store from its parent.

```php
$basket = $session->getStore("basket");
$basket?->remove();
```

## Writing behaviour

`set()` and `remove()` both call `write()` after changing the store. `write()` serialises the root store and asks the configured handler to persist it.

If we store an object in the session, PHP must be able to autoload that object's class before the session data is read back.

---

Next, see how to read values predictably with [[Type-safe getters]].


`Session` and `SessionStore` both implement `Gt\TypeSafeGetter\TypeSafeGetter`.

That gives us a consistent way to read common types without manually casting every value. The same getter style is used across several PHP.GT libraries.

## Available getters

- `get(string $name):mixed`
- `getString(string $name):?string`
- `getInt(string $name):?int`
- `getFloat(string $name):?float`
- `getBool(string $name):?bool`
- `getDateTime(string $name):?DateTimeInterface`
- `getInstance(string $name, string $className)`

## Reading scalar values

```php
$session->set("auth.userId", "42");
$session->set("basket.total", "12.50");
$session->set("ui.compact", "1");

$userId = $session->getInt("auth.userId");
$total = $session->getFloat("basket.total");
$compact = $session->getBool("ui.compact");
```

If the value is missing, the typed getter returns `null`.

If the value exists, scalar getters cast to the requested PHP type.

## Reading date and time values

`getDateTime()` accepts values that can be turned into a `DateTimeImmutable`.

```php
$session->set("auth.lastSeen", "2026-04-23 10:15:00");

$lastSeen = $session->getDateTime("auth.lastSeen");
echo $lastSeen?->format("j F Y");
```

Numeric values are treated as Unix timestamps.

## Reading objects

`getInstance()` checks that a stored object is an instance of the class or interface we ask for.

```php
$basket = $session->getInstance("checkout.basket", Basket::class);
```

If the stored value is the wrong object type, a `TypeError` is thrown. This is intentional: it catches session-shape mistakes close to where they are read.

## Use typed getters at boundaries

It is usually best to use typed getters as soon as session data enters application logic:

```php
function do_save(Session $session, ProfileRepository $profiles):void {
	$userId = $session->getInt("auth.userId");

	if(!$userId) {
		throw new RuntimeException("You must be signed in to save a profile.");
	}

	$profiles->saveForUser($userId);
}
```

That keeps the rest of the function working with known types.

---

Next, look at the browser cookie and PHP options in [[Session cookies and configuration]].


A PHP session normally uses a cookie to connect the browser to server-side data.

The browser stores the session cookie. The server stores the session data. On each request, the browser sends the cookie back, and PHP uses the cookie value as the session ID.

## Session cookie name

The cookie name is controlled by the `name` config value.

```php
$session = new Session($handler, [
	"name" => "GT",
]);
```

If no name is supplied, the library uses PHP's familiar `PHPSESSID` default.

> [!NOTE]
> WebEngine's default session name is `GT`. In a WebEngine project this is configured in the `[session]` section of `config.ini`.

## Cookie lifetime

`cookie_lifetime` controls how long the browser should keep the session cookie.

```php
$session = new Session($handler, [
	"cookie_lifetime" => 3600,
]);
```

The library default is `0`, which means a browser-session cookie. Browsers normally clear session cookies when the browser session ends.

This does not make session data permanent. Session data should still be treated as temporary. If we need to remember something important, store it in a database or another durable system.

## Secure and HTTP-only cookies

The defaults are:

- `cookie_secure`: `true`
- `cookie_httponly`: `true`

`cookie_secure` tells the browser to send the cookie only over HTTPS.

`cookie_httponly` prevents JavaScript from reading the cookie through `document.cookie`.

For a production site, these are good defaults. During local development over plain HTTP, we may need to set `cookie_secure` to `false`.

## SameSite

The default SameSite policy is `Lax`.

```php
$session = new Session($handler, [
	"cookie_samesite" => "Lax",
]);
```

`Lax` is a practical default because it protects against many cross-site request patterns while still allowing normal navigation from another site to ours.

## Cookie-only sessions

The defaults are:

- `use_only_cookies`: `true`
- `use_cookies`: `true`
- `use_trans_sid`: `false`

That means the session ID should be carried in a cookie, not added to URLs.

If `use_trans_sid` is enabled and cookies are disabled, the library can read the session ID from the request query data using the configured session name. This mode is rarely needed for modern applications.

## Strict mode

`use_strict_mode` defaults to `true`.

Strict mode tells PHP not to accept uninitialised session IDs supplied by a client. This helps avoid session fixation problems.

## Ending a session

`Session::kill()` asks the handler to destroy the current session data and sends an expired cookie for the current session name.

```php
$session->kill();
```

This is useful during logout. Application code should also remove any user-specific state it stores outside the session.

---

Next, choose where session data is stored in [[Storage handlers]].


PHP separates session behaviour from session storage through `SessionHandlerInterface`.

This library can work with any object that implements that interface. It also provides two handlers:

- `GT\Session\FileHandler`
- `GT\Session\RedisHandler`

## FileHandler

`FileHandler` stores each session as a file.

```php
use GT\Session\FileHandler;
use GT\Session\Session;

$session = new Session(new FileHandler(), [
	"name" => "GT",
	"save_path" => "phpgt/session",
]);
```

The handler stores files under:

```text
<save-path>/<session-name>/<session-id>
```

When the save path is relative, `Session` places it under `sys_get_temp_dir()` before the handler receives it.

## Garbage collection

`FileHandler::gc()` deletes session files whose modification time is older than the maximum lifetime passed by PHP.

The method returns the number of deleted files, or `false` if a file could not be deleted.

## Empty sessions

`FileHandler` does not write PHP's empty serialised array value, `a:0:{}`. That avoids creating files for sessions that have no useful data.

## Custom handlers

Any custom handler can be used as long as it implements `SessionHandlerInterface`.

```php
use GT\Session\Session;

$handler = new MySessionHandler();
$session = new Session($handler, [
	"name" => "GT",
	"save_path" => "custom/path",
]);
```

If the handler should be registered with PHP's session system, use `SessionSetup`.

```php
use GT\Session\SessionSetup;

$setup = new SessionSetup();
$handler = $setup->attachHandler(MySessionHandler::class);
```

## Choosing a handler

Use file storage when the application runs on one server, or when the filesystem is shared safely between all application nodes.

Use Redis-compatible storage when application nodes are disposable, load-balanced, or do not share a filesystem.

> [!NOTE]
> WebEngine reads the handler class from `[session] handler` in `config.ini`. Older projects may still show `Gt\Session\FileHandler`; Composer keeps that prefix working, but new configuration can use `GT\Session\FileHandler`.

---

Next, configure shared storage in [[Redis session storage]].


`RedisHandler` stores session data in Redis-compatible storage.

This is useful when an application runs on more than one server, or when the server filesystem is temporary. Redis and Valkey are common choices for this kind of shared session storage.

> [!IMPORTANT]
> `RedisHandler` requires the `phpredis` extension. The package suggests `ext-redis`, but Composer cannot install PHP extensions for us.

## Basic configuration

```php
use GT\Session\RedisHandler;
use GT\Session\Session;

$session = new Session(new RedisHandler(), [
	"name" => "GT",
	"save_path" => "redis://localhost:6379/0",
]);
```

The save path is a DSN. `Session` recognises DSN-style save paths and leaves them unchanged.

## DSN examples

```text
redis://localhost:6379
redis://:secret@localhost:6379/0
redis://default:secret@redis.internal:6379/2
rediss://default:secret@redis.internal:25061/0
```

The path part selects the Redis database. If no database is supplied, database `0` is used.

## Authentication

If the DSN contains both a username and password, the handler passes both to `Redis::auth()`.

```text
redis://default:secret@redis.internal:6379/0
```

If the DSN contains only a password, the handler authenticates with just the password.

```text
redis://:secret@redis.internal:6379/0
```

## Query parameters

Supported query parameters are:

- `prefix`
- `ttl`
- `timeout`
- `read_timeout`
- `persistent`
- `persistent_id`
- `verify_peer`
- `verify_peer_name`

Example:

```text
rediss://default:secret@example-redis.internal:25061/0?prefix=GT:&ttl=1440&timeout=1.5&read_timeout=2.5&persistent=1
```

## Key prefix

By default, Redis keys are prefixed with the session name followed by a colon.

For a session named `GT`, the key for session ID `abc123` is:

```text
GT:abc123
```

Set the `prefix` query parameter to choose a different prefix:

```text
redis://localhost:6379/0?prefix=app-session:
```

## TTL

The `ttl` query parameter controls the Redis expiry time in seconds.

```text
redis://localhost:6379/0?ttl=3600
```

If no TTL is supplied, the handler uses PHP's `session.gc_maxlifetime` value.

When TTL is greater than zero, writes use `setEx()`. Otherwise, writes use `set()`.

## TLS

Use `rediss://` or `tls://` for TLS connections.

```text
rediss://default:secret@redis.internal:25061/0
```

For local testing against a TLS endpoint with self-signed certificates, verification can be disabled:

```text
rediss://default:secret@redis.internal:25061/0?verify_peer=0&verify_peer_name=0
```

Only disable verification when we understand the security trade-off.

## WebEngine configuration

In WebEngine, the same handler can be configured in `config.ini`:

```ini
[session]
handler=GT\Session\RedisHandler
path=rediss://default:secret@example-redis.internal:25061/0?prefix=GT:&ttl=1440
name=GT
use_cookies=true
```

> [!NOTE]
> WebEngine passes `[session] path` to this library as `save_path`. For Redis, that value should be the Redis DSN rather than a filesystem path.

---

Next, learn how to show one-request notices in [[Flash messages]].


Flash messages are short-lived messages that are written during one request and consumed during a later request.

They are commonly used after a redirect:

- "Your profile has been saved."
- "Please sign in before continuing."
- "That item has been removed from your basket."

## Create a Flash object

`Flash` works with a `SessionStoreInterface`.

```php
use GT\Session\Flash;
use GT\Session\Session;

function example(Session $session):void {
	$flash = new Flash($session->getStore("flash", true));
}
```

Using a dedicated `flash` store keeps flash message data away from other session data.

## Put a message

```php
$flash->put("success", "Your profile has been saved.");
```

Internally, messages are stored in a queue under `queue.<name>`.

## Consume a message

```php
$flashStore = $session->getStore("flash", true);
$flash = new Flash($flashStore);

if($flashStore->contains("queue.success")) {
	$message = $flash->consume("success");

	if($message) {
		echo $message->message;
	}
}
```

`consume()` removes one message from the queue and returns a `FlashMessage`.

`FlashMessage` has two read-only properties:

- `name`
- `message`

## Multiple messages with the same name

Messages with the same name are queued in order.

```php
$flash->put("notice", "First message");
$flash->put("notice", "Second message");

echo $flash->consume("notice")?->message; // First message
echo $flash->consume("notice")?->message; // Second message
echo $flash->consume("notice")?->message; // null
```

When an existing queue is empty, `consume()` removes the queue from the session and returns `null`.

> [!IMPORTANT]
> `consume()` expects the named queue to exist. If we are not sure a message has been queued, check the underlying flash store with `contains("queue.<name>")` before consuming it.

## A redirect example

```php
use GT\Session\Flash;
use GT\Session\Session;

function do_save(Session $session):void {
	$flash = new Flash($session->getStore("flash", true));
	$flash->put("success", "Saved.");

	header("Location: /account");
}

function go(Session $session):void {
	$flashStore = $session->getStore("flash", true);
	$flash = new Flash($flashStore);

	if(!$flashStore->contains("queue.success")) {
		return;
	}

	$message = $flash->consume("success");

	if($message) {
		echo $message->message;
	}
}
```

> [!NOTE]
> WebEngine applications often redirect after `do_*()` functions. Flash messages fit that flow because the message can be written before the redirect and displayed on the next page load.

---

Next, see the class-level summary in the [[API reference]].


This page summarises the public classes in `phpgt/session`.

It is not a replacement for the source code, but it gives a quick map of what each class is for.

## Session

Namespace: `GT\Session\Session`

`Session` represents the whole PHP session.

Constructor:

```php
public function __construct(
	SessionHandlerInterface $sessionHandler,
	iterable $config = [],
	?string $id = null,
)
```

Common methods:

- `getStore(string $namespace, bool $createIfNotExists = false): ?SessionStoreInterface`
- `get(string $key): mixed`
- `set(string $key, mixed $value): void`
- `contains(string $key): bool`
- `remove(string $key): void`
- `getId(): string`
- `write(): bool`
- `kill(): void`

Typed getter methods come from `TypeSafeGetter`.

## SessionStore

Namespace: `GT\Session\SessionStore`

`SessionStore` represents one area of the session. It extends `ArrayIterator` and implements `SessionStoreInterface`.

Common methods:

- `get(string $key): mixed`
- `set(string $key, mixed $value): void`
- `contains(string $key): bool`
- `remove(?string $key = null): void`
- `getStore(string $namespace, bool $createIfNotExists = false): ?SessionStore`
- `createStore(string $namespace): SessionStore`
- `write(): void`

`set()` and `remove()` persist the root session data through the owning `Session`.

## SessionStoreInterface

Namespace: `GT\Session\SessionStoreInterface`

This is the interface to type-hint when a class only needs one session area.

```php
use GT\Session\SessionStoreInterface;

class Preferences {
	public function __construct(
		private SessionStoreInterface $session
	) {}
}
```

It extends:

- `SessionContainer`
- `Gt\TypeSafeGetter\TypeSafeGetter`
- `Countable`

## SessionContainer

Namespace: `GT\Session\SessionContainer`

Small interface for basic key/value access:

- `get(string $key): mixed`
- `set(string $key, mixed $value): void`
- `contains(string $key): bool`
- `remove(string $key): void`

## SessionArrayWrapper

Namespace: `GT\Session\SessionArrayWrapper`

`SessionArrayWrapper` adapts an array to the `SessionContainer` interface.

```php
use GT\Session\SessionArrayWrapper;

$data = [];
$container = new SessionArrayWrapper($data);
$container->set("name", "Cody");
```

The array is held by reference, so changes through the wrapper update the original array.

## SessionSetup

Namespace: `GT\Session\SessionSetup`

`SessionSetup` creates a handler class and registers it with PHP when needed.

```php
use GT\Session\FileHandler;
use GT\Session\SessionSetup;

$handler = (new SessionSetup())->attachHandler(FileHandler::class);
```

It returns a `SessionHandlerInterface`.

## Handler

Namespace: `GT\Session\Handler`

Abstract base class for handlers. It implements `SessionHandlerInterface` and declares the standard session handler methods.

Most applications use `FileHandler`, `RedisHandler`, PHP's built-in `SessionHandler`, or a custom handler.

## FileHandler

Namespace: `GT\Session\FileHandler`

Stores session data as files under `<save-path>/<session-name>/`.

Public methods are the standard `SessionHandlerInterface` methods:

- `open()`
- `close()`
- `read()`
- `write()`
- `destroy()`
- `gc()`

## RedisHandler

Namespace: `GT\Session\RedisHandler`

Stores session data in Redis-compatible storage. The handler expects a Redis DSN as `save_path`.

See [[Redis session storage]] for DSN examples and query parameters.

## Flash

Namespace: `GT\Session\Flash`

Small helper for queued one-request messages.

Methods:

- `put(string $name, string $message): void`
- `consume(string $name): ?FlashMessage`

## FlashMessage

Namespace: `GT\Session\FlashMessage`

Read-only value object returned by `Flash::consume()`.

Properties:

- `name`
- `message`




---

# Documentation: SqlBuilder

`phpgt/sqlbuilder` gives us a structured way to write SQL in PHP without giving up control of the SQL itself.

Instead of concatenating fragments of query strings throughout application code, we can represent a query as a class, extend it when a new use case appears, or build one fluently at the point of use.

> [!NOTE]
> In PHP.GT/WebEngine applications, this library is most commonly used alongside `phpgt/database` when writing PHP-backed query collections.

## Features

- Class-based `select`, `insert`, `update`, and `delete` queries.
- Fluent builders for common one-off query construction.
- Reusable condition objects for grouped `where` and `having` clauses.
- Helper condition classes for equality and comparison expressions.
- Subqueries and nested query composition.
- Table-definition query classes for `create table`, `alter table`, and `drop table`.
- Simple, portable SQL syntax generation.

## Out of scope

- It does not execute SQL.
- It does not inspect your schema.

## A small example

```php
use GT\SqlBuilder\Query\SelectQuery;

class StudentSelect extends SelectQuery {
	public function select():array {
		return [
			"id",
			"name",
			"dateOfBirth",
		];
	}

	public function from():array {
		return [
			"student",
		];
	}

	public function where():array {
		return [
			"deletedAt is null",
		];
	}
}
```

```php
class ActiveStudentSelect extends StudentSelect {
	public function where():array {
		return array_merge(parent::where(), [
			"status = 'active'",
		]);
	}
}
```

```php
echo new ActiveStudentSelect();
```

Output:

```sql
select
	`id`,
	`name`,
	`dateOfBirth`
from
	`student`
where
	`deletedAt` is null
and
	`status` = 'active'
```

That prints a valid SQL query, but the important part is the shape of the code: the base query stays in one place, and the variation extends it instead of repeating it.

*****

To see the two main ways of working with the library before we start building anything, continue with [[Overview]].


SqlBuilder has two main styles of use:

1. define reusable query classes by extending one of the base query types
2. build a query fluently with a builder object

Both styles produce SQL by implementing `__toString()`, so in everyday code they can be treated as strings when needed.

## Query classes

Query classes are the core of the library.

For example, a `SelectQuery` subclass can define:

- `select()`
- `from()`
- `where()`
- `groupBy()`
- `having()`
- `orderBy()`
- `limit()`
- `offset()`

Each method returns the part of the SQL statement it is responsible for, and the parent class assembles the final query in the correct SQL order.

This is the style to prefer when:

- the query is reused
- one query naturally extends another
- the query deserves its own name in the application
- you want to test the query shape directly

## Builders

Builders are the convenient, one-off version of the same idea.

Instead of subclassing a query type, we call fluent methods:

```php
use GT\SqlBuilder\SelectBuilder;

$query = new SelectBuilder();
$query->select("id", "email")
	->from("user")
	->where("deletedAt is null")
	->orderBy("email");
```

Builders are useful when:

- the query is local to one small piece of code
- creating a dedicated class would add more noise than value
- you want the same SQL shape as the class-based API, but inline

## Fixed output order

One detail that often surprises people at first: builders do not output query parts in the order the methods were called. They output them in the normal SQL order for that query type.

That means this is still fine:

```php
$query->having("count(*) > 1")
	->where("deletedAt is null")
	->groupBy("email");
```

The rendered SQL will still place `where` before `group by`, and `group by` before `having` to produce valid SQL syntax.

## Each query part is stored once

Builder methods replace the whole part they refer to.

For example, calling:

```php
$query->where("id = :id");
$query->where("enabled = true");
```

will leave only the second `where` clause in place. If you need more than one expression for a part, pass them together in one call:

```php
$query->where(
	"id = :id",
	"enabled = true",
);
```

## Conditions are first-class objects

Plain strings are allowed in `where()` and `having()`, but those clauses also support condition objects for grouping and comparison logic.

That means we can write code such as:

```php
use GT\SqlBuilder\Condition\GreaterThan;
use GT\SqlBuilder\Condition\MultipleCondition;
use GT\SqlBuilder\Condition\MatchAny;

$query->where(
	"deletedAt is null",
	new MultipleCondition(
		new MatchAny(),
		new GreaterThan("score", 50),
		"status = 'priority'",
	),
);
```

We will cover those properly in [[Working with conditions]].

## Query execution is someone else's job

SqlBuilder only builds SQL text. It does not bind parameters or talk to the database server.

That separation is useful because it lets this library stay small and predictable. If you need execution, pair it with your own database layer or with `phpgt/database`.

> [!NOTE]
> In WebEngine applications, `phpgt/database` is the usual layer that executes queries. SqlBuilder or plain PHP files can be used to store queries, and WebEngine will load and execute the queries automatically.

***

Next, we will build a first working query in [[Getting started]].


In this guide we will create one class-based query and one builder-based query, then look at when each style makes sense.

## 1. Install the package

```bash
composer require phpgt/sqlbuilder
```

## 2. Create your first query class

Create a PHP class that extends `SelectQuery`:

```php
use GT\SqlBuilder\Query\SelectQuery;

class StudentSelect extends SelectQuery {
	public function select():array {
		return [
			"id",
			"name",
			"dateOfBirth",
		];
	}

	public function from():array {
		return [
			"student",
		];
	}
}
```

Now render it:

```php
echo new StudentSelect();
```

Output:

```sql
select
	id,
	name,
	dateOfBirth
from
	student
```

At this point there is no database connection involved. We have only built the SQL string.

## 3. Extend the query instead of copying it

Now imagine we need a second query for active students only. We can extend the first query:

```php
class ActiveStudentSelect extends StudentSelect {
	public function where():array {
		return [
			"deletedAt is null",
			"status = 'active'",
		];
	}
}
```

That gives us reuse without string duplication.

## 4. Build the same kind of query inline

Sometimes a named class is too much ceremony for a tiny one-off query. In that case, use `SelectBuilder`:

```php
use GT\SqlBuilder\SelectBuilder;

$query = new SelectBuilder();
$query->select(
	"id",
	"name",
	"dateOfBirth",
)->from(
	"student",
)->where(
	"deletedAt is null",
	"status = 'active'",
);

echo $query;
```

This produces the same shape of SQL, but the query stays close to the place where it is used.

## 5. Know when to choose which style

As a rule of thumb:

- use a query class when the query has a name in your domain.
- use a query class when other queries will extend it.
- use a builder when the query is stored as a variable in code, rather than file on disk.

If you are not sure, start with the query class. It scales better as the application grows.

## 6. Keep placeholders as placeholders

SqlBuilder will happily render parameter placeholders such as `:id` or `?`, but it does not bind them itself.

```php
class StudentByIdSelect extends StudentSelect {
	public function where():array {
		return [
			":id",
		];
	}
}
```

This renders:

```sql
where
	id = :id
```

That is often exactly what we want, because the database layer can bind the real value later.

> [!TIP]
> If you are using `phpgt/database`, this pairs naturally with named or positional parameter binding in the execution layer.

---

Now that we have seen the basic shape, move on to [[Writing query classes]] for the full class-based API.


Query classes are the centre of this library. They are small PHP classes whose methods each describe one part of an SQL statement.

## The base query types

SqlBuilder provides these abstract query bases:

- `GT\SqlBuilder\Query\SelectQuery`
- `GT\SqlBuilder\Query\InsertQuery`
- `GT\SqlBuilder\Query\UpdateQuery`
- `GT\SqlBuilder\Query\DeleteQuery`
- `GT\SqlBuilder\Query\Table\CreateTableQuery`
- `GT\SqlBuilder\Query\Table\AlterTableQuery`
- `GT\SqlBuilder\Query\Table\DropTableQuery`

Each base type knows how to assemble its own SQL statement.

## `SelectQuery`

`SelectQuery` is the most feature-rich query type.

The available methods are:

- `select(): array`
- `from(): array`
- `innerJoin(): array`
- `crossJoin(): array`
- `leftJoin(): array`
- `leftOuterJoin(): array`
- `where(): array`
- `groupBy(): array`
- `having(): array`
- `orderBy(): array`
- `limit(): ?int`
- `offset(): ?int`
- `preQuery(): string`
- `postQuery(): string`

Most of these default to an empty array or `null`, so you only override what you need.

```php
use GT\SqlBuilder\Query\SelectQuery;

class StudentSelect extends SelectQuery {
	public function select():array {
		return [
			"id",
			"name",
			"dateOfBirth",
		];
	}

	public function from():array {
		return [
			"student",
		];
	}

	public function where():array {
		return [
			"deletedAt is null",
		];
	}
}
```

## Extending a query

Inheritance is the main design idea behind query classes.

```php
class StudentInDistrictSelect extends StudentSelect {
	public function where():array {
		return array_merge(parent::where(), [
			":district",
		]);
	}
}
```

That renders the base `where` clause first, then your additional one.

## `InsertQuery`

`InsertQuery` can be defined in two main ways:

1. with `columns()` and `values()`
2. with `set()`

```php
use GT\SqlBuilder\Query\InsertQuery;

class InsertStudent extends InsertQuery {
	public function into():array {
		return [
			"student",
		];
	}

	public function set():array {
		return [
			"name" => ":name",
			"dateOfBirth" => ":dateOfBirth",
		];
	}
}
```

When `set()` is present and `columns()` / `values()` are empty, the query uses `set()` to infer both lists.

`InsertQuery` also supports `select()` for `insert ... select ...` statements. That is covered in [[Subqueries and composition]].

## `UpdateQuery`

`UpdateQuery` provides:

- `table(): array`
- `set(): array`
- `where(): array`
- `preQuery(): string`
- `postQuery(): string`

```php
use GT\SqlBuilder\Query\UpdateQuery;

class MarkStudentProcessed extends UpdateQuery {
	public function table():array {
		return [
			"student",
		];
	}

	public function set():array {
		return [
			":processedAt",
		];
	}

	public function where():array {
		return [
			":id",
		];
	}
}
```

That renders the `set()` shorthand as `processedAt = :processedAt`.

## `DeleteQuery`

`DeleteQuery` is intentionally small:

- `from(): array`
- `where(): array`
- `preQuery(): string`
- `postQuery(): string`

```php
use GT\SqlBuilder\Query\DeleteQuery;

class DeleteStudent extends DeleteQuery {
	public function from():array {
		return [
			"student",
		];
	}

	public function where():array {
		return [
			"id = :id",
		];
	}
}
```

## `preQuery()` and `postQuery()`

All query bases inherit these two hooks from `SqlQuery`:

- `preQuery()`
- `postQuery()`

They return plain strings that are inserted before or after the main statement.

That is mostly useful for comments or engine-specific clauses:

```php
public function preQuery():string {
	return "/* reporting query */";
}
```

## Subqueries

`SelectQuery` accepts a boolean constructor argument. When `true`, the final SQL is wrapped in parentheses so it can be embedded inside another query.

```php
$subQuery = new class(true) extends SelectQuery {
	// ...
};
```

We will use that properly in [[Subqueries and composition]].

## The library does not validate SQL semantics

The library assembles query text, but it does not know whether:

- the table exists
- the selected columns are valid
- a `group by` matches the selected columns
- the target database supports your syntax

***

If you prefer inline query construction, continue with [[Working with builders]].


Builders provide the same general query shapes as the class-based API, but in a fluent style.

Available builders:

- `GT\SqlBuilder\SelectBuilder`
- `GT\SqlBuilder\InsertBuilder`
- `GT\SqlBuilder\UpdateBuilder`
- `GT\SqlBuilder\DeleteBuilder`

There are currently no builder classes for the table-query types.

## `SelectBuilder`

`SelectBuilder` supports:

- `select(string ...$args)`
- `from(string ...$args)`
- `innerJoin(string ...$args)`
- `crossJoin(string ...$args)`
- `leftJoin(string ...$args)`
- `leftOuterJoin(string ...$args)`
- `where(string ...$args)`
- `groupBy(string ...$args)`
- `having(string ...$args)`
- `orderBy(string ...$args)`
- `limit(int $limit)`
- `offset(int $offset)`

```php
use GT\SqlBuilder\SelectBuilder;

$query = new SelectBuilder();
$query->select(
	"id",
	"email",
	"max(loginDateTime) as lastLogin",
)->from(
	"user",
)->leftJoin(
	"user_access on user.id = user_access.userId",
)->where(
	"email like '%@example.com'",
	"deletedAt is null",
)->groupBy(
	"email",
)->having(
	"lastLogin > '2020-01-01'",
)->orderBy(
	"email",
)->limit(100);
```

## `InsertBuilder`

`InsertBuilder` supports:

- `into(string ...$args)`
- `columns(string ...$args)`
- `values(string ...$args)`
- `set(array|string ...$args)`

```php
use GT\SqlBuilder\InsertBuilder;

$query = new InsertBuilder();
$query->into("student")
	->set([
		"id" => 123,
		"name" => "'example'",
	]);
```

That renders:

```sql
insert into
	student
(
	id,
	name
)

values (
	123,
	'example'
)
```

We will look at `set()` in more detail in [[Insert and update assignment syntax]].

## `UpdateBuilder`

`UpdateBuilder` supports:

- `table(string ...$args)`
- `set(array|string ...$args)`
- `where(string ...$args)`

```php
use GT\SqlBuilder\UpdateBuilder;

$query = new UpdateBuilder();
$query->table("student")
	->set(":processedAt")
	->where(":id");
```

## `DeleteBuilder`

`DeleteBuilder` supports:

- `from(string ...$args)`
- `where(string|Condition ...$args)`

```php
use GT\SqlBuilder\DeleteBuilder;

$query = new DeleteBuilder();
$query->from("student")
	->where("softDelete is not null");
```

## Builder calls return the builder itself

Every builder method returns the same builder instance, so chaining works naturally:

```php
$query->select("id")->from("student")->where(":id");
```

## `getQuery()` returns the corresponding query object

Each builder can also produce the query object it wraps:

```php
$builder = new SelectBuilder();
$builder->select("id")->from("student");

$query = $builder->getQuery();
echo $query;
```

This is useful when another part of the code expects a `SqlQuery` object rather than the builder itself.

## Invalid builder methods fail loudly

If you call a method that is not a supported query part, the builder throws an `Error`.

This is important because the builder methods are implemented through `__call()`. In other words, you get a fluent API, but only for the query parts the builder actually defines.

## A practical limitation

Builders are good for expressing a query, not for building a mutating query object over many stages.

Remember:

- calling the same builder method again replaces the previous part
- builders do not automatically append to earlier `where()` or `select()` calls

So if you find yourself repeatedly revisiting the same builder in different parts of the code, that is often a sign the query should become a named query class instead.

***

For grouped logic and helper condition objects, continue with [[Working with conditions]].


`where` and `having` clauses can be written as plain strings, but the library becomes much more useful once we start using condition objects.

Condition objects help with:

- logical grouping
- repeated comparison patterns
- short placeholder syntax
- composing nested boolean logic without hand-writing every bracket

## Plain strings are still valid

This is fine:

```php
public function where():array {
	return [
		"deletedAt is null",
		"enabled = true",
	];
}
```

Multiple plain strings are joined with `and`.

## `AndCondition` and `OrCondition`

For explicit logic, use:

- `GT\SqlBuilder\Condition\AndCondition`
- `GT\SqlBuilder\Condition\OrCondition`

```php
// This query's where performs two logic conditions:
// 1) It ensures that deletedAt AND archivedAt is null
// ... and ...
// 2) It ensures that status is active OR pending
public function where():array {
	return [
		new AndCondition(
			"deletedAt is null",
			"archivedAt is null",
		),
		new OrCondition(
			"status = 'active'",
			"status = 'pending'",
		),
	];
}
```

Nested conditions are wrapped in brackets automatically where needed.

## `MultipleCondition`

`MultipleCondition` is the reusable grouped-condition helper. It takes:

1. a matcher object
2. one or more conditions or plain strings

The matcher decides whether the parts are joined with `and` or `or`.

Available matchers:

- `GT\SqlBuilder\Condition\MatchAll`
- `GT\SqlBuilder\Condition\MatchAny`

```php
use GT\SqlBuilder\Condition\Equals;
use GT\SqlBuilder\Condition\GreaterThan;
use GT\SqlBuilder\Condition\MatchAny;
use GT\SqlBuilder\Condition\MultipleCondition;

public function where():array {
	return [
		"deletedAt is null",
		new MultipleCondition(
			new MatchAny(),
			new Equals("status", "active"),
			new GreaterThan("score", 50),
		),
	];
}
```

This keeps the intent much clearer than manually juggling brackets inside a string.

## Comparison helpers

The repository currently provides these comparison condition classes:

- `Equals`
- `GreaterThan`
- `LessThan`
- `Between`

### `Equals`

```php
use GT\SqlBuilder\Condition\Equals;

new Equals("score", 42);
new Equals("status", "active");
new Equals("deletedAt", null);
```

Rendered results:

- `score = 42`
- `status = 'active'`
- `deletedAt is null`

Single quotes inside strings are escaped for SQL string literal syntax:

```php
new Equals("surname", "O'Reilly");
```

renders as:

```sql
surname = 'O\'Reilly'
```

### `GreaterThan` and `LessThan`

```php
new GreaterThan("score", 100);
new LessThan("score", 10);
```

These also format booleans and `DateTimeInterface` values correctly for SQL text output.

### `Between`

```php
use GT\SqlBuilder\Condition\Between;

new Between("score", 10, 20);
```

renders:

```sql
score between 10 and 20
```

It also supports `DateTimeInterface` values.

## Short placeholder syntax inside conditions

There are two shorthand forms for simple equality conditions:

- `":id"` becomes `id = :id`
- `"?id"` becomes `id = ?`

```php
public function where():array {
	return [
		":id",
		":name",
	];
}
```

renders as:

```sql
where
	id = :id
and
	name = :name
```

## Do not mix named and indexed shorthand in one clause

The library explicitly rejects this:

```php
public function where():array {
	return [
		":id",
		"?name",
	];
}
```

That throws `MixedIndexedAndNamedParametersException`.

The reason is simple: one clause should commit to either named placeholders or positional placeholders so the SQL stays predictable.

## Prefer helper conditions when the value is data

If the right-hand side is user or application data, the helper classes often read better than assembling a literal string yourself:

```php
new Equals("enabled", true);
new Between("createdAt", $from, $to);
```

If the expression is already a full SQL fragment, a plain string is usually clearer:

```php
"coalesce(lastLogin, createdAt) > now() - interval 1 day"
```

***

Learn about [[Insert and update assignment syntax]] in the next section.


`InsertQuery`, `InsertBuilder`, `UpdateQuery`, and `UpdateBuilder` all support assignment-like data, but there are a few different ways to express it.

This page explains the supported forms.

## `columns()` with `values()`

This is the most explicit insert form:

```php
use GT\SqlBuilder\InsertBuilder;

$query = new InsertBuilder();
$query->into("student")
	->columns("id", "name")
	->values(123, "'example'");
```

That renders an ordinary `insert into ... values ...` statement.

Use this form when:

- the column list and value list are already separate in your code
- you want to mirror the SQL structure closely

## `set()` with an associative array

For inserts and updates, `set()` also accepts an associative array:

```php
$query->set([
	"id" => 123,
	"name" => "'example'",
]);
```

In an insert, that becomes:

```sql
insert into student(id, name) values(123, 'example')
```

In an update, that becomes:

```sql
update student set id = 123, name = 'example'
```

## `set()` with short placeholder syntax

The shorthand form is often the most convenient:

```php
$query->set(
	":title",
	":updatedAt",
);
```

In an update, that becomes:

```sql
set
	title = :title,
	updatedAt = :updatedAt
```

In an insert, it becomes matching inferred columns and values:

```sql
(
	title,
	updatedAt
)

values (
	:title,
	:updatedAt
)
```

Indexed short syntax also supports positional placeholders:

- `"?title"` becomes `title = ?` in an update
- `"?title"` becomes column `title` with value `?` in an insert

## Indexed `set()` values must be explicit

This is not allowed:

```php
$query->set("title");
```

It throws `SqlBuilderException` with the message:

```text
Indexed set() values must use explicit short syntax
```

That rule prevents ambiguity. If a value is indexed rather than associative, the library needs to know whether it is:

- a shorthand placeholder such as `:title`
- or a full assignment expression such as `title = trim(:title)`

## Explicit assignment expressions

You can always provide the full SQL expression yourself:

```php
$query->set(
	"id = uuid()",
	"name = trim(:name)",
);
```

For inserts, the library splits these into column names and right-hand expressions.

For updates, it keeps them as assignments.

## How scalar values are formatted

When `set()` receives an associative array, scalar values are formatted as SQL literals:

- strings are used as provided
- integers are rendered as numbers
- booleans are rendered as `true` or `false`

For example:

```php
$query->set([
	"enabled" => true,
	"archived" => false,
]);
```

renders:

```sql
enabled = true,
archived = false
```

## Prefer placeholders for external data

Even though the library can render literal values, placeholders are usually the better option for real application input:

```php
$query->set([
	"title" => ":title",
	"updatedAt" => ":updatedAt",
]);
```

That keeps SQL construction and parameter binding as separate concerns.

## A practical rule

Choose the simplest form that still makes the intent obvious:

- use `columns()` / `values()` when you already have two ordered lists
- use associative `set()` when you have column-to-value pairs
- use short syntax when the placeholder name should match the column name
- use explicit assignment expressions when the right-hand side is an SQL expression

---

Next, we will look at nesting queries and reusing them in [[Subqueries and composition]].


One of the most useful features of SqlBuilder is that query objects can be composed inside other query objects.

Because every query implements `Stringable`, a query can appear anywhere a string expression would make sense.

## Select used as a subquery

`SelectQuery` accepts a boolean constructor argument. When set to `true`, the rendered query is wrapped in brackets.

```php
use GT\SqlBuilder\Query\SelectQuery;

class ConsentMinAgeSelect extends SelectQuery {
	public function __construct() {
		parent::__construct(true);
	}

	public function select():array {
		return [
			"minAge",
		];
	}

	public function from():array {
		return [
			"consent",
		];
	}

	public function where():array {
		return [
			"consent.district = student.district",
		];
	}
}
```

Now it can be embedded in another query:

```php
use GT\SqlBuilder\Query\SelectQuery;

class StudentSelect extends SelectQuery {
	public function select():array {
		return [
			"id",
			"name",
			"dateOfBirth",
		];
	}

	public function from():array {
		return [
			"student",
		];
	}

	public function where():array {
		return [
			"deletedAt is null",
			"age > " . new ConsentMinAgeSelect(),
		];
	}
}
```

That produces:

```sql
age > ( select minAge from consent where consent.district = student.district )
```

## `insert ... select ...`

`InsertQuery` supports a `select(): ?SelectQuery` method for `insert ... select ...` workflows.

```php
use GT\SqlBuilder\Query\InsertQuery;
use GT\SqlBuilder\Query\SelectQuery;

class ImportStudentRows extends InsertQuery {
	public function into():array {
		return [
			"student",
		];
	}

	public function columns():array {
		return [
			"name",
			"dateOfBirth",
		];
	}

	public function select():?SelectQuery {
		return new class extends SelectQuery {
			public function select():array {
				return [
					"legalName",
					"assignedDOB",
				];
			}

			public function from():array {
				return [
					"temp",
				];
			}

			public function where():array {
				return [
					"example is not null",
				];
			}
		};
	}
}
```

## Queries inside query parts

Several query parts accept `SqlQuery` objects directly, not just raw strings. That means you can:

- return a `SelectQuery` from `InsertQuery::select()`
- return `SqlQuery` objects in some table-definition arrays
- concatenate or interpolate stringable queries into custom expressions

## Composition works best when each query has one job

As with normal PHP classes, composition stays readable when the smaller queries are focused.

Good:

- one query that represents a base `student` selection
- one query that represents a reporting subquery
- one query that imports rows from a staging table

Less good:

- one giant class that tries to model every possible report shape through conditionals

If the query is starting to branch in several directions, that is usually a sign to split it into a base query and a few specific subclasses.

## A note on execution layers

Subqueries are rendered as SQL text only. The surrounding execution layer still handles placeholders and bound values in the normal way.

That is one reason it pairs well with repository or query-collection patterns: the query shape stays in the query object, while the data still arrives from the caller.

> [!NOTE]
> In a WebEngine application using `phpgt/database`, this often means a page or service class chooses the query object, and the database layer deals with connection management and execution automatically.

***

The remaining query family is the table-definition API, covered in [[Table queries]].


SqlBuilder also includes query classes for table-definition statements.

These are:

- `CreateTableQuery`
- `AlterTableQuery`
- `DropTableQuery`

Unlike the select/insert/update/delete APIs, these are class-based only. There are no builder equivalents at the moment.

## `CreateTableQuery`

To define a create-table query, implement:

- `createTable(): string`
- `createDefinition(): array`

```php
use GT\SqlBuilder\Query\Table\CreateTableQuery;

class CreateStudentTable extends CreateTableQuery {
	public function createTable():string {
		return "student";
	}

	public function createDefinition():array {
		return [
			"id varchar(32) not null",
			"first_name varchar(32)",
			"last_name varchar(32)",
			"dob date",
			"primary key(id)",
		];
	}
}
```

If `createDefinition()` returns an empty array, the query throws `SqlBuilderException`.

## `AlterTableQuery`

To define an alter-table query, implement:

- `alterTable(): string`
- `alterOptions(): array`

```php
use GT\SqlBuilder\Query\Table\AlterTableQuery;

class AlterStudentTable extends AlterTableQuery {
	public function alterTable():string {
		return "student";
	}

	public function alterOptions():array {
		return [
			"add column telephone int after dob",
			"add column email varchar(256) after id",
		];
	}
}
```

If `alterOptions()` is empty, the query throws `SqlBuilderException`.

## `DropTableQuery`

`DropTableQuery` is the simplest of the three:

```php
use GT\SqlBuilder\Query\Table\DropTableQuery;

class DropStudentTable extends DropTableQuery {
	public function dropTable():string {
		return "student";
	}
}
```

If you want `if exists`, include it in the returned string:

```php
public function dropTable():string {
	return "if exists student";
}
```

## `SqlQuery` objects inside definitions and options

`CreateTableQuery` definitions and `AlterTableQuery` options can include `SqlQuery` objects, not only plain strings.

That is a niche feature, but it is useful when one fragment is easier to model as its own object.

## `preQuery()` and `postQuery()` still apply

All three table-query classes inherit the usual `preQuery()` and `postQuery()` hooks.

That means you can add comments or engine-specific fragments around the main statement when needed.

## Keep these classes focused

It is often tempting to make a schema query class highly dynamic. In practice, these classes are easiest to maintain when they represent one concrete statement:

- create one specific table
- alter one table in one defined way
- drop one table

If you need a full migration system, pair these queries with the tool that coordinates execution order and safety in your application.

***

To see the library patterns gathered into one place, continue with [[Examples]].


A set of examples are contained in the runnable `example/` directory and the PHPUnit helper queries.

## Running the repository example

From the repository root:

```bash
php example/01-simple-select.php
```

That example shows the smallest class-based `SelectQuery` setup.

## Example index

1. [example/01-simple-select.php](https://github.com/PhpGt/SqlBuilder/blob/master/example/01-simple-select.php)
   A simple `SelectQuery` subclass.
2. `test/phpunit/Helper/Query/SelectExample.php`
   A base `select` query with a reusable `where` clause.
3. `test/phpunit/Helper/Query/SelectExampleExtendWhere.php`
   Extending a base query to add one more condition.
4. `test/phpunit/Helper/Query/SelectExampleExtendComplex.php`
   Nested conditions with grouped boolean logic.
5. `test/phpunit/Helper/Query/SelectExampleSubquery.php`
   A select containing a subquery.
6. `test/phpunit/Helper/Query/InsertExample.php`
   Insert with associative `set()` syntax.
7. `test/phpunit/Helper/Query/InsertSelectInlineExample.php`
   `insert ... select ...`.
8. `test/phpunit/Helper/Query/UpdateExample.php`
   Update with short placeholder assignment syntax.
9. `test/phpunit/Helper/Query/DeleteExample.php`
   A straightforward delete query.
10. `test/phpunit/Helper/Query/Table/CreateTableExample.php`
    Create-table query class.
11. `test/phpunit/Helper/Query/Table/AlterTableExample.php`
    Alter-table query class.
12. `test/phpunit/Helper/Query/Table/DropTableExample.php`
    Drop-table query class.

## A few patterns worth copying

### Base query plus subclass

This is the most important pattern in the library:

```php
use GT\SqlBuilder\Query\SelectQuery;

class StudentSelect extends SelectQuery {
	public function select():array {
		return ["id", "name", "dateOfBirth"];
	}

	public function from():array {
		return ["student"];
	}

	public function where():array {
		return ["deletedAt is null"];
	}
}

class StudentWithTestFlagSelect extends StudentSelect {
	public function where():array {
		return array_merge(parent::where(), [
			"test = 123",
		]);
	}
}
```

### Inline builder

This is the equivalent small-query pattern:

```php
use GT\SqlBuilder\SelectBuilder;

$query = new SelectBuilder();
$query->select("id", "email")
	->from("user")
	->where("deletedAt is null")
	->limit(100);
```

### Grouped conditions

```php
use GT\SqlBuilder\Condition\Equals;
use GT\SqlBuilder\Condition\GreaterThan;
use GT\SqlBuilder\Condition\MatchAny;
use GT\SqlBuilder\Condition\MultipleCondition;

$where = new MultipleCondition(
	new MatchAny(),
	new Equals("status", "active"),
	new GreaterThan("score", 50),
);
```

## Where these examples fit in a real application

In a small application, one or two builders may be enough.

In a growing application, the helper query classes in the test suite reflect the style that tends to age better:

- give queries names
- extend base queries
- keep condition logic in the query object
- keep execution somewhere else

> [!NOTE]
> In WebEngine projects, that usually means page logic or services decide which query to use, while database execution lives in the database layer rather than in the query class itself.




---

# Documentation: Sync

Sync provides one-way filesystem synchronisation from a source path to a destination path.

The package can be used from PHP code or from the command line. It can copy files from one directory to another, delete destination files that are no longer present in the source, or create symbolic links.

> [!NOTE]
> In WebEngine applications, this package is used by the build system to move client-side files into the public `www/` directory. The same package can also be used on its own, without WebEngine.

## A small example

```php
use GT\Sync\DirectorySync;

$sync = new DirectorySync("asset", "www/asset");
$sync->exec();

echo "Copied: " . count($sync->getCopiedFilesList());
```

The destination is made to match the source. Files that already match are skipped.

---

To set up the package in a small script, move on to [[getting started]].


In this guide we will install `phpgt/sync`, copy a directory and inspect what happened.

> [!NOTE]
> In WebEngine applications, this package is usually used through the build system. The default build configuration calls `vendor/bin/sync` to copy or link files from directories such as `script/`, `style/` and `asset/` into `www/`.
> 
> This guide installs the package directly, for when we want the same sync behaviour in a standalone PHP script or in another framework.

## 1. Install the package

```bash
composer require phpgt/sync
```

The package provides PHP classes and a command line script at `vendor/bin/sync`.

## 2. Copy one directory to another

```php
use GT\Sync\DirectorySync;

$sync = new DirectorySync("asset", "www/asset");
$sync->exec();
```

If the destination directory does not exist, it is created. Files that do not exist in the destination are copied across, and files that already match are skipped.

## 3. Read the summary

After `exec()` has finished, the object keeps track of what happened during that run:

```php
printf(
	"Copied %d, skipped %d, deleted %d",
	count($sync->getCopiedFilesList()),
	count($sync->getSkippedFilesList()),
	count($sync->getDeletedFilesList()),
);
```

The lists are reset each time `exec()` is called.

## 4. Check whether two directories match

If we only need to know whether the destination is already in sync, call `check()`:

```php
if(!$sync->check()) {
	$sync->exec();
}
```

By default, files are compared using their modification time. We can use content hashes instead:

```php
$sync->check(DirectorySync::COMPARE_HASH);
$sync->exec(DirectorySync::COMPARE_HASH);
```

Do not combine `COMPARE_FILEMTIME` and `COMPARE_HASH` in one call. The library will throw `GT\Sync\SyncException`.

---

Next, move on to [[directory sync]] to see how copying, filtering and deletion work.


`GT\Sync\DirectorySync` synchronises files from one source directory into one destination directory.

The sync is one-way: the source is treated as the current state, and the destination is updated to match it.

## Constructing

```php
use GT\Sync\DirectorySync;

$sync = new DirectorySync(
	"asset",
	"www/asset"
);
```

The source directory must exist. The destination directory is created when `exec()` runs.

The constructor accepts an optional glob pattern:

```php
$sync = new DirectorySync(
	"script",
	"www/script",
	"**/*.js"
);
```

The default pattern is `**/*`, which matches all files under the source directory, recursively.

When a pattern is used, it limits which source files are copied and which destination files are deleted. Source files that do not match the pattern are left alone and are counted in the skipped list for that run.

> [!NOTE]
> The pattern uses an extended glob, sometimes known as a [globstar](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html), which is augments the inbuilt [`glob` function](https://www.php.net/manual/en/function.glob.php) of PHP, causing `**` to match patterns recursively.

## Executing

```php
$sync->exec();
```

During an exec, the library:

- creates the destination directory if needed
- deletes destination files that match the glob but no longer exist in the source
- removes empty destination directories that no longer exist in the source
- copies files that are missing or different
- skips files that already match or do not match the configured pattern

When a file is copied, the destination file's modification time is set to match the source file's modification time.

## Comparing files

By default, files are compared using `filemtime()`:

```php
$sync->exec(DirectorySync::COMPARE_FILEMTIME);
```

This compares file metadata, so it only notices changes when the file modification time changes. If the actual contents of the file is important, use hashes:

```php
$sync->exec(DirectorySync::COMPARE_HASH);
```

The same comparison setting can be passed to `check()`:

```php
if($sync->check(DirectorySync::COMPARE_HASH)) {
	echo "Already in sync", PHP_EOL;
}
```

## Operation lists

Each call to `exec()` clears the previous lists and fills them with paths from the current run:

```php
$copied = $sync->getCopiedFilesList();
$skipped = $sync->getSkippedFilesList();
$deleted = $sync->getDeletedFilesList();
```

The paths are relative to the source or destination root.

## Exceptions

`GT\Sync\SyncException` is thrown when:

- the source directory does not exist
- both comparison modes are requested at the same time

---

Next, move on to [[symbolic links]] to see how this package can create links instead of copying files.


`GT\Sync\SymlinkSync` creates a symbolic link from a source path to a destination path.

Use this when one public path should point at another directory or file without needing to copy the contents.

## Link a directory

```php
use GT\Sync\SymlinkSync;

$sync = new SymlinkSync(
	"data/upload",
	"www/data/upload"
);

$sync->exec();
```

If the parent directory for the destination does not exist, it is created.

## Link a file

```php
$sync = new SymlinkSync(
	"asset/logo.svg",
	"www/logo.svg"
);

$sync->exec();
```

The same class handles both files and directories.

## Existing links

If the destination is already a symbolic link to the same source, the operation is skipped.

If the destination is a symbolic link to a different source, the old link is removed and a new one is created.

If the destination already exists and is not a symbolic link, `symlink()` fails and the destination path is added to the failed list.

## Operation lists

After `exec()` has run, these methods describe the result:

```php
$linkedFiles = $sync->getLinkedFilesList();
$linkedDirectories = $sync->getLinkedDirectoriesList();
$allLinked = $sync->getCombinedLinkedList();
$skipped = $sync->getSkippedList();
$failed = $sync->getFailedList();
```

Each call to `exec()` clears the previous lists before trying again.

---

Next, move on to [[command line]] to use the same functionality from the terminal.


The package installs a command line script at `vendor/bin/sync`.

It uses the same `DirectorySync` and `SymlinkSync` classes that we can use from PHP.

## Copy files

```bash
vendor/bin/sync asset www/asset
```

The command prints a short summary:

```text
Copied 3, skipped 12, deleted 1.
```

## Filter by pattern

Use `--pattern` or `-p` to copy only matching files:

```bash
vendor/bin/sync script www/script --pattern "**/*.js"
```

The pattern is matched relative to the source directory.

## Create a symbolic link

Use `--symlink` or `-l` to create a symbolic link instead of copying files:

```bash
vendor/bin/sync data/upload www/data/upload --symlink
```

When a link is created, the command prints the number of linked directories, linked files, skipped links and failed links.

## Silence output

Use `--silent` or `-s` when the command should not print its summary:

```bash
vendor/bin/sync asset www/asset --silent
```

## About `--delete`

The command currently accepts `--delete` or `-d`, but deletion is already part of normal directory sync behaviour. Destination files that match the configured pattern and no longer exist in the source are deleted during a directory sync.

## Use from WebEngine

WebEngine includes `phpgt/sync` so its build system can copy client-side assets into `www/`.

In a WebEngine project, we usually do not call `vendor/bin/sync` by hand. Instead, `gt build` reads `build.json`, and the default WebEngine build configuration uses commands like:

```ini
[asset/**/*]
name=Publish static assets
require=vendor/bin/sync ^1.3
execute=vendor/bin/sync ./asset ./www/asset --symlink
```

The command still works the same way. WebEngine is just deciding when to run it.




---

# Documentation: TypeSafeGetter

This library defines a small contract for reading named values as specific PHP types.

It contains:

- `TypeSafeGetter`, an interface for objects that expose named values
- `NullableTypeSafeGetter`, a trait that implements the common typed getter methods
- `CallbackTypeSafeGetter`, an interface for callback-driven lookups

The library does not decide where values come from. That part is left to the class implementing `get()`. One class might read from an array, another from session storage, and another from HTTP data.

## Where this library fits in

This package can be used on its own in any PHP project, but in practice it is often used by other PHP.GT packages rather than directly by application code.

For example, across PHP.GT you will come across these typed getter methods on objects such as:

- configuration containers
- session stores
- HTTP header collections
- form and query data wrappers
- database row objects

In WebEngine projects, that usually means you benefit from this package indirectly through those higher-level services.

## A minimal example

```php
use GT\TypeSafeGetter\NullableTypeSafeGetter;
use GT\TypeSafeGetter\TypeSafeGetter;

class UserData implements TypeSafeGetter {
	use NullableTypeSafeGetter;

	public function __construct(
		private readonly array $data = [],
	) {}

	public function get(string $name):mixed {
		return $this->data[$name] ?? null;
	}
}

$user = new UserData([
	"id" => "42",
	"isAdmin" => 1,
	"registered" => "2024-01-15 10:30:00",
]);

echo $user->getInt("id");
var_dump($user->getBool("isAdmin"));
echo $user->getDateTime("registered")?->format("Y-m-d");
```

In this example, the class only needs to provide `get()`. The trait handles the common conversions for strings, integers, floats, booleans, dates, and object instances.

---

Install the library from scratch in [[Getting started]]


In this section we will build the smallest useful implementation of `TypeSafeGetter`.

> [!NOTE]
> In WebEngine, you will usually use these methods through another package such as Input, Session, Config, Http, or Database rather than wiring this package directly into page logic, and you'll never need to require the package yourself using Composer.

## 1. Install the package

```bash
composer require phpgt/typesafegetter
```

## 2. Implement `TypeSafeGetter`

The only method you must supply yourself is `get()`.

```php
use GT\TypeSafeGetter\NullableTypeSafeGetter;
use GT\TypeSafeGetter\TypeSafeGetter;

class KeyValueStore implements TypeSafeGetter {
	use NullableTypeSafeGetter;

	public function __construct(
		private array $data = [],
	) {}

	public function get(string $name):mixed {
		return $this->data[$name] ?? null;
	}
}
```

The trait adds the typed methods on top of whatever `get()` returns.

## 3. Read scalar values

```php
$store = new KeyValueStore([
	"name" => "Cody",
	"age" => "9",
	"weight" => "5.16",
	"microchip" => true,
]);

echo $store->getString("name");
echo $store->getInt("age");
echo $store->getFloat("weight");
var_dump($store->getBool("microchip"));
```

Missing keys return `null`:

```php
var_dump($store->getString("missing")); // null
```

## 4. Read dates

`getDateTime()` accepts:

- a `DateTimeInterface` object
- a Unix timestamp
- a date/time string understood by `DateTimeImmutable`

```php
$store = new KeyValueStore([
	"created" => "2024-05-01 09:15:00",
]);

echo $store->getDateTime("created")?->format(DateTimeInterface::ATOM);
```

## 5. Read object instances

`getInstance()` is for values that are already objects.

```php
$user = new stdClass();
$user->name = "Cody";

$store = new KeyValueStore([
	"user" => $user,
]);

$loadedUser = $store->getInstance("user", stdClass::class);
echo $loadedUser?->name;
```

This method does not construct a new object. It returns the stored object after checking that it matches the requested class or interface. This is useful for static analysis - your IDE will know the value type of the returned object from `getInstance`, so intellisense will work for dynamic object typing.

---

See a breakdown of all [[Typed methods]].


Once a class implements `get()`, the `NullableTypeSafeGetter` trait provides the rest of the public API.

## `get()`

```php
public function get(string $name):mixed;
```

This is the raw lookup method. It returns whatever the underlying store contains, or `null` when the key is missing.

The trait uses this method internally for all typed lookups.

## Scalar getters

These methods cast non-null values using PHP's normal scalar casting rules:

- `getString(string $name): ?string`
- `getInt(string $name): ?int`
- `getFloat(string $name): ?float`
- `getBool(string $name): ?bool`

Example:

```php
$store = new KeyValueStore([
	"intString" => "105",
	"price" => "19.99",
	"enabled" => "1",
]);

echo $store->getInt("intString");
echo $store->getFloat("price");
var_dump($store->getBool("enabled"));
```

If the key is missing, each method returns `null`.

## `getDateTime()`

```php
public function getDateTime(string $name): ?DateTimeInterface;
```

This method handles three cases:

- if the stored value is already a `DateTimeInterface`, it is returned as-is
- if the stored value is numeric, it is treated as a Unix timestamp
- otherwise the value is passed to `DateTimeImmutable`

Example:

```php
$store = new KeyValueStore([
	"published" => 1714550400,
]);

echo $store->getDateTime("published")?->format("Y-m-d");
```

## `getInstance()`

```php
public function getInstance(string $name, string $className);
```

Use this when the stored value should already be an object instance.

```php
$store = new KeyValueStore([
	"date" => new DateTimeImmutable("2024-05-01"),
]);

$date = $store->getInstance("date", DateTimeInterface::class);
```

If the key is missing, `null` is returned.

If the value exists but is not an instance of the requested class or interface, a `TypeError` is thrown.

This is useful when the storage contains mixed values but a particular key is expected to hold one object type.

## Choosing between `get()` and the typed methods

Use `get()` when:

- the value is not one of the common built-in scalar or date types
- you want to handle conversion yourself
- the value may be an array or another mixed structure

Use the typed methods when:

- the underlying data source stores strings that need casting
- you want a consistent `null` result for missing keys
- you want the calling code to be explicit about the expected type

---

Finally, see how values from [[Callbacks]] can be implemented.


`CallbackTypeSafeGetter` is a separate interface for lookups that may need to compute or fetch a value on demand.

## When the callback form is useful

This pattern is useful when a value might not already exist in the store.

Common examples include:

- caches
- lazy-loaded values
- derived values that are expensive to compute

Instead of simply returning a stored value, the implementation can decide whether to call the callback.

## The interface

`CallbackTypeSafeGetter` defines the same family of typed methods as `TypeSafeGetter`, but each one accepts a callback as well.

For example:

```php
public function get(string $name, callable $callback):mixed;
public function getString(string $name, callable $callback):?string;
public function getDateTime(string $name, callable $callback):?DateTimeInterface;
```

Unlike `NullableTypeSafeGetter`, this repository does not provide a trait implementation for the callback interface. Each implementing class defines its own callback behaviour.

## A small example

```php
use DateTimeImmutable;
use DateTimeInterface;
use GT\TypeSafeGetter\CallbackTypeSafeGetter;
use TypeError;

class LazyStore implements CallbackTypeSafeGetter {
	private array $data = [];

	public function get(string $name, callable $callback):mixed {
		if(!array_key_exists($name, $this->data)) {
			$this->data[$name] = $callback();
		}

		return $this->data[$name];
	}

	public function getString(string $name, callable $callback):?string {
		return (string)$this->get($name, $callback);
	}

	public function getInt(string $name, callable $callback):?int {
		return (int)$this->get($name, $callback);
	}

	public function getFloat(string $name, callable $callback):?float {
		return (float)$this->get($name, $callback);
	}

	public function getBool(string $name, callable $callback):?bool {
		return (bool)$this->get($name, $callback);
	}

	public function getDateTime(string $name, callable $callback):?DateTimeInterface {
		return new DateTimeImmutable($this->get($name, $callback));
	}

	public function getInstance(string $name, string $className, callable $callback):object {
		$value = $this->get($name, $callback);
		if(!$value instanceof $className) {
			throw new TypeError("Value is not of type $className");
		}

		return $value;
	}
}
```

The important point is that the callback is part of the contract, but the rules for when it runs are up to the implementing class.

## Relation to the rest of PHP.GT

Most PHP.GT packages that expose typed getters use `TypeSafeGetter` together with `NullableTypeSafeGetter`.

`CallbackTypeSafeGetter` appears in narrower cases where loading the value is part of the lookup operation itself, such as cache-style APIs.




---

# Documentation: Ulid

Create a `new Ulid()` anywhere in your application, and you have a stringable object that can be used as the primary key in a database. Ulid strings look something like `01G2J6MYN0PGC5Q21W9C` or can be prefixed with a type like `CUSTOMER_01G2J6MYN0PGC5Q21W9C`. They are cryptographically pseudo-random, and sort so that newer Ulids compare "greater than" older Ulids.

This solves the problems exposed with working with auto-incrementing integer primary keys, which are predictable and difficult to work with in distributed databases.

This library can be used when we want identifiers that:

- do not expose sequential database IDs
- can be created before a database insert happens
- sort in creation order
- carry a lightweight type prefix for readability

This library defaults to a compact 20-character identifier made from a 10-character timestamp section and a 10-character random section. If we need a different shape, both lengths can be configured.

## What this library covers

- Creating sortable IDs with `new GT\Ulid\Ulid()`
- Adding uppercase prefixes such as `INVOICE_`
- Reading timestamp and `DateTime` information back from an ID
- Parsing existing ULID strings
- Extracting prefixes, timestamps, and random sections explicitly
- Converting to and from the library's Base32 alphabet

## Recommended reading order

1. [[Quick start guide]]
2. [[Prefixes and typed identifiers]]
3. [[Reading timestamp information]]
4. [[Parsing existing ULIDs]]
5. [[Custom lengths and timestamp sections]]
6. [[Base32 encoding]]
7. [[Examples]]

## A small example

```php
use GT\Ulid\Ulid;

$orderId = new Ulid("order");

echo $orderId, PHP_EOL;
echo $orderId->getTimestampString(), PHP_EOL;
```

Example output:

```text
ORDER_01KPKT4PFTKVQ9P1E72F
01KPKT4PFT
```

The important thing to notice is that we do not have to manage any external state. We construct the object, use it as a string, and keep the helper methods nearby if we later want to inspect it.

---

Start with the [[Quick start guide]] to build the smallest useful setup from scratch.


In this guide we will build the smallest useful `phpgt/ulid` setup from scratch.

The main public entry point is `GT\Ulid\Ulid`. Most projects can stop there. The rest of the library exists to help us inspect or customise IDs when we need more control.

## 1. Install the package

```bash
composer require phpgt/ulid
```

## 2. Construct an ID

```php
use GT\Ulid\Ulid;

$id = new Ulid();
echo $id;
```

Example output:

```text
01KPKT4PFTKVQ9P1E72F
```

This is the default shape of the identifier:

- `10` characters of timestamp
- `10` characters of randomness

The timestamp section sorts lexicographically, so newer IDs compare greater than older ones.

## 3. Add a prefix when it helps readability

```php
$customerId = new Ulid("customer");
echo $customerId;
```

Example output:

```text
CUSTOMER_01KPKT4PFTKVQ9P1E72F
```

Prefixes are automatically converted to uppercase, which keeps the identifiers visually consistent throughout logs, URLs, and SQL output.

## 4. Store it as a string

`Ulid` implements `Stringable`, so it fits naturally into the places where we already expect an identifier string:

```php
$db->insert("user/insert", [
	"id" => (string)$customerId,
	"email" => "dev@example.com",
]);
```

We can cast explicitly, or let PHP convert the object to a string when that is appropriate.

## 5. Read the timestamp back out

```php
echo $customerId->getTimestampString(), PHP_EOL;
echo $customerId->getDateTime()->format("Y-m-d H:i:s"), PHP_EOL;
```

That gives us an easy bridge between the identifier and its creation time, without storing a second value just to reconstruct it later.

## 6. Rehydrate an existing string

If we already have a ULID string from a database or request parameter, we can rebuild the object:

```php
$existing = "CUSTOMER_01KPKT4PFTKVQ9P1E72F";
$id = new Ulid(init: $existing);

echo $id->getPrefix();           // CUSTOMER
echo $id->getTimestampString();  // 01KPKT4PFT
```

This is useful when the rest of our application prefers to work with an object instead of passing raw strings around.

## 7. Know when to reach for the other classes

Most of the time, `Ulid` is all we need.

- Use `Ulid` to create and inspect whole identifiers.
- Use `Extractor` when we already have an ID string and only want one section from it.
- Use `Base32` when we want direct access to the library's encoding rules.

---

Once the basic flow is in place, continue with [[Prefixes and typed identifiers]] to decide when prefixed IDs improve the design of an application.


Prefixes let us add a small amount of human meaning to an identifier without giving up the sortable ULID structure.

For example, these are all valid outputs from the library:

```text
USER_01KPKT4PFTKVQ9P1E72F
ORDER_01KPKT4PFTJH2WQ7M3CB
PET_01KPKT4PFT3EAJY4T1Q9
```

That can make logs, dashboards, and support tooling much easier to read at a glance.

## Creating a prefixed ULID

```php
use GT\Ulid\Ulid;

$invoiceId = new Ulid("invoice");
echo $invoiceId;
```

Output:

```text
INVOICE_01KPKT4PFTKVQ9P1E72F
```

The prefix is always returned in uppercase, regardless of the original input.

## Reading the prefix back

```php
echo $invoiceId->getPrefix();
```

Output:

```text
INVOICE
```

If no prefix was provided, `getPrefix()` returns `null`.

## When prefixes are useful

Prefixes work well when the same system handles several categories of entity and we want the ID itself to give us a clue about what it belongs to.

Common examples:

- `USER_...`
- `ORDER_...`
- `INVOICE_...`
- `SESSION_...`

This can be especially helpful when identifiers move through external systems such as log aggregators, message queues, or support emails where surrounding context may be limited.

## When not to use them

A prefix is not a substitute for proper typing in PHP, nor is it a substitute for relational integrity in a database.

If the identifier never leaves a tightly scoped part of the system, or if the prefix would simply duplicate obvious context, plain unprefixed ULIDs are often the cleaner choice.

## One style decision to make early

It helps to settle on one prefix vocabulary across the application:

- singular or plural nouns
- domain terms or table names
- short codes or whole words

The library will uppercase whatever we provide, but it will not enforce naming conventions beyond that.

---

Now that we can identify what an ID belongs to, the next step is to inspect when it was created in [[Reading timestamp information]].


One of the most useful parts of a sortable identifier is that the creation time is embedded in the string itself.

With `phpgt/ulid`, we can read that information in three main ways:

- as the raw integer timestamp
- as the encoded timestamp section
- as a `DateTime`

## Getting the raw timestamp

```php
use GT\Ulid\Ulid;

$id = new Ulid();
echo $id->getTimestamp();
```

When the library generates a fresh ID with no explicit timestamp argument, it uses the current Unix time in milliseconds.

## Getting the encoded timestamp section

```php
echo $id->getTimestampString();
```

Example output:

```text
01KPKT4PFT
```

This is the part that makes lexicographic sorting work. If we compare two ULID strings created at different times, the newer one sorts after the older one.

## Converting to `DateTime`

```php
echo $id->getDateTime()->format("Y-m-d H:i:s");
```

This is usually the most convenient choice when we want to display or compare the creation time in application code.

## Setting an explicit timestamp

If we need a ULID for a known point in time, we can pass the timestamp into the constructor:

```php
$knownTime = strtotime("2024-05-04 17:24:00 UTC") * 1000;
$id = new Ulid(timestamp: $knownTime);

echo $id->getDateTime()->format("Y-m-d H:i:s");
```

> [!IMPORTANT]
> To keep `getDateTime()` and lexicographic ordering aligned with generated IDs, pass Unix time in milliseconds when supplying your own timestamp.

## Sorting behaviour

Because the timestamp section comes first, ordinary string sorting is enough:

```php
$a = new Ulid(timestamp: strtotime("2024-01-01 00:00:00 UTC") * 1000);
$b = new Ulid(timestamp: strtotime("2024-02-01 00:00:00 UTC") * 1000);

var_dump((string)$a < (string)$b);
```

## A practical use

If we already have the identifier, we may not need to store an extra `created_at` column purely to answer broad questions such as:

- was this record created before or after another record?
- roughly when was it created?
- how should a list of IDs be ordered by default?

We may still want a dedicated timestamp column for indexing, reporting, or database-native date logic, but the ULID already carries useful timing information for application-level decisions.

---

Next we will look at rebuilding and dissecting IDs that already exist in [[Parsing existing ULIDs]].


In a real application, we often receive an identifier long after it was first created.

That might be from:

- a database row
- a route parameter
- an API payload
- a message queue
- a log line we want to inspect

This library gives us two ways to work backwards from the string.

## Option 1: reconstruct an `Ulid` object

If we want the full helper API again, construct a new object with `init`:

```php
use GT\Ulid\Ulid;

$string = "ORDER_01KPKT4PFTKVQ9P1E72F";
$id = new Ulid(init: $string);

echo $id->getPrefix(), PHP_EOL;
echo $id->getTimestampString(), PHP_EOL;
echo $id->getRandomString(), PHP_EOL;
```

This is the most natural choice when our codebase already expects an `Ulid` object.

## Option 2: use `Extractor`

If we only need one section, `Extractor` is more direct:

```php
use GT\Ulid\Extractor;

$extractor = new Extractor();
$string = "ORDER_01KPKT4PFTKVQ9P1E72F";

echo $extractor->extractPrefix($string), PHP_EOL;
echo $extractor->extractTimestamp($string), PHP_EOL;
echo $extractor->extractRandomString($string), PHP_EOL;
```

## What each extractor method returns

- `extractPrefix()` returns the prefix before the underscore, or `null`
- `extractTimestamp()` returns the decoded integer timestamp
- `extractRandomString()` returns the random suffix section

## Parsing IDs without prefixes

Prefixed and unprefixed ULIDs are both supported:

```php
$plain = "01KPKT4PFTKVQ9P1E72F";
$prefixed = "ORDER_01KPKT4PFTKVQ9P1E72F";

$extractor = new Extractor();

var_dump($extractor->extractPrefix($plain));    // null
var_dump($extractor->extractPrefix($prefixed)); // ORDER
```

The extractor checks for the underscore separator and adjusts automatically.

## Rehydrating before domain validation

One practical pattern is to reconstruct the `Ulid` as early as possible when an identifier enters the application:

```php
$userId = new Ulid(init: $_GET["id"]);
```

That keeps parsing logic in one place and lets the rest of the application work with one consistent representation.

---

If you need to change the shape of the identifier itself, continue with [[Custom lengths and timestamp sections]].


The library defaults to a 20-character identifier:

- `10` characters for the timestamp
- `10` characters for the random section

That is a sensible default for most applications, but both parts can be configured when a different trade-off makes more sense.

## Changing the total length

```php
use GT\Ulid\Ulid;

$id = new Ulid(length: 30);
echo $id;
echo strlen((string)$id);
```

Increasing the total length gives the identifier a longer random section, because the timestamp section remains at its default length unless we change that too.

## Changing the timestamp section length

```php
$id = new Ulid(timestampLength: 8);
echo $id->getTimestampString();
```

This changes how much of the encoded timestamp is exposed at the front of the string.

## Changing both together

```php
$id = new Ulid(length: 24, timestampLength: 12);
```

This gives us explicit control over the balance between:

- how much room is allocated to time ordering
- how much room is allocated to randomness
- how long the final ID should be in storage and interfaces

## When to customise

Custom lengths can be useful when:

- a legacy schema has a strict column length
- an external format expects a particular identifier width
- we want longer random sections for application-specific reasons

## One important rule

Once an application is using a particular ULID shape in production data, changing that shape mid-stream should be a deliberate migration decision.

For example, if one part of the system expects:

```text
01KPKT4PFTKVQ9P1E72F
```

and another suddenly starts producing a different layout, any code that validates length or slices sections by position will need to change at the same time.

## Matching `Extractor` to customised IDs

If we are parsing ULIDs with non-default lengths, construct `Extractor` with matching values:

```php
use GT\Ulid\Extractor;

$extractor = new Extractor(
	length: 24,
	timestampLength: 12,
);
```

That keeps the extractor aligned with the IDs our application is producing.

---

For the encoding rules underneath these sections, move on to [[Base32 encoding]].


Throughout the library, a base32 alphabet is used for converting numbers.

The public `Base32` class is useful when we want to work with the encoding directly, or when we want to understand why the generated IDs avoid certain characters.

## Why 32?

Base64 is a commonly used encoding type. The "64" part of Base64 means that there are 64 different characters available for encoding. That's A-Z upper and lower case, 0-9, and a few symbols.

Base32 includes numbers 0-9 and an upper-case alphabet, minus some ambiguous characters.

Identifiers are often copied by people:

- from a terminal
- from a browser address bar
- from a support ticket
- from a printed label

This library deliberately avoids ambiguous characters such as:

- `I`
- `L`
- `O`
- `U`

That reduces mistakes when reading or typing an identifier.

## Encoding a number

```php
use GT\Ulid\Base32;

$base32 = new Base32();
echo $base32->fromDec(105);
```

## Decoding back to decimal

```php
$number = $base32->toDec("39");
var_dump($number);
```

The important point is that the encoding is reversible within the library's rules.

## Where this shows up in normal usage

Most of the time we do not call `Base32` ourselves. `Ulid` uses it internally to:

- encode the timestamp section
- encode each random value in the random section

`Extractor` also uses it to decode timestamp strings back into integers.

## Custom skipped characters

The constructor allows a different skip-character list:

```php
$base32 = new Base32("ilou");
```

That is the default used by the library itself.

In practice, changing it would only make sense if the whole application controls both encoding and decoding and has a good reason to diverge from the default alphabet.

---

To see the pieces together in small, practical scripts, continue with [[Examples]].


This page gathers a few complete examples that mirror the most common ways we use `phpgt/ulid` in an application.

## Generate IDs for new records

```php
use GT\Ulid\Ulid;

$userId = new Ulid("user");
$orderId = new Ulid("order");

echo $userId, PHP_EOL;
echo $orderId, PHP_EOL;
```

## Use a ULID as a database key

```php
use GT\Ulid\Ulid;

$id = new Ulid("customer");

$db->insert("customer/insert", [
	"id" => (string)$id,
	"name" => "A. Example",
]);
```

Because the object is stringable, it fits naturally into insert payloads.

## Rebuild an object from stored data

```php
use GT\Ulid\Ulid;

$storedId = $row->getString("id");
$id = new Ulid(init: $storedId);

echo $id->getPrefix(), PHP_EOL;
echo $id->getDateTime()->format("Y-m-d H:i:s"), PHP_EOL;
```

## Sort ULIDs as strings

```php
$ids = [
	(string)new Ulid(timestamp: strtotime("2024-03-01 10:00:00 UTC") * 1000),
	(string)new Ulid(timestamp: strtotime("2024-01-01 10:00:00 UTC") * 1000),
	(string)new Ulid(timestamp: strtotime("2024-02-01 10:00:00 UTC") * 1000),
];

sort($ids, SORT_STRING);
print_r($ids);
```

Because the timestamp comes first, plain string sorting gives us chronological order.

## Pull individual sections from an ID

```php
use GT\Ulid\Extractor;

$id = "INVOICE_01KPKT4PFTKVQ9P1E72F";
$extractor = new Extractor();

printf("Prefix: %s\n", $extractor->extractPrefix($id));
printf("Timestamp: %d\n", $extractor->extractTimestamp($id));
printf("Random: %s\n", $extractor->extractRandomString($id));
```




---

# Documentation: WebEngine

WebEngine is an ergonomic toolkit for building web applications using HTML and PHP. It follows a static-first approach: page development begins using plain HTML files, with PHP introduced only when needed. Dynamic behaviour is handled through server-side DOM manipulation, mirroring well-known client-side techniques.

Web frameworks offer many features, but often come with steep learning curves or imposing rules. The motivation behind this project is the belief that what a framework can offer can be achieved by **eliminating code rather than adding more**.

The core concept behind WebEngine is that **applications start static first**, the simplest application consisting of a single file at `page/index.html` (see the [[Hello World tutorial]]).

A clean separation of concerns is promoted, as described in [[application architecture]], so that the business logic, page logic and any client side code can be written and maintained separately.

When a page is ready to be made dynamic, PHP files can be added with the same name as their HTML counterparts; `index.html` is powered by `index.php`, `about.html` is powered by `about.php`, etc. Read more about the relationship between [[Page Views]] and [[Page Logic]]. Dynamic pages are made possible by [[binding data to the DOM]], and [[dynamic URIs]] are made possible by the [router](routing-reference).

## Who is PHP.GT WebEngine for?

The overall aim throughout GT repositories is to provide an alternative, minimalistic approach to web development. If you're tired of working with the so-called "full stack", there might be something of interest to you here.

All GT repositories are designed to be inclusive to novice developers. Each repository is designed to operate independently, allowing developers to leverage individual components without necessarily needing to adopt the entire framework or possess prior knowledge of WebEngine. This modular approach not only enhances flexibility but also promotes a more focused, purpose-driven development experience.

WebEngine itself provides a "batteries-included" default configuration and has an accessible entry point for beginners. However, its capabilities extend far beyond basic use-cases; WebEngine is robust enough to power large-scale, real-world applications serving millions of users.

## Main features

The easiest way to understand WebEngine's feature set is to think in terms of one web request. The browser asks for a URL, WebEngine maps that URL to a page, optional PHP logic runs, and the final document is sent back to the browser.

Some of the main parts of that flow are:

- [[File-based routing]] so URLs map directly to files and directories in your project.
- [[Page Views]] and [[Page Logic]] so HTML and PHP can sit side by side without being mixed together.
- [[Binding data to the DOM]] so the page can be made dynamic without building large HTML strings in PHP.
- [[User input]], [[Cookies]], [[Sessions]], and [[Protected globals]] so request state stays explicit and easy to trace.
- [[Databases]] and [[Application classes]] so persistence and business rules live outside the page entry point.
- [[Build system]] and [[gt commands]] so a project can be created, run, tested, and prepared for the browser using one set of tools.

These topics are all covered in the rest of this wiki, and where a subject is maintained in more detail by another PHP.GT package, links are provided out to that package's own documentation.

### Separation of concerns

WebEngine is built from small, separately maintained PHP.GT repositories, each with a focused responsibility. You can see the wider set of packages in the [PhpGt GitHub organisation](https://github.com/PhpGt) or browse the published docs at [php.gt/docs](https://www.php.gt/docs/).

That separation in the framework encourages the same separation in the applications built with it. HTML can stay in page views, page logic can stay thin, application classes can hold business rules, queries can stay in their own files, and client-side assets can be built separately from PHP. The result is not that there are more moving parts, but that each part has a clear place to live.

## How to Read These Docs

These docs are arranged to be read mostly in order. The Overview chapter introduces the ideas behind WebEngine. The next two chapters then move from a tiny working app into the normal page-building workflow of routes, views, logic, input, state, and data.

The tutorials in the Production applications chapter are there to turn those ideas into complete examples. If you're new to WebEngine, it is worth following them in order rather than jumping straight into the reference pages.

The Reference chapter is written for lookup. When you already know that a feature exists and simply want the rule, config key, or command syntax, head there. The Further reading chapter is where the more architectural and opinionated ideas live.

*****

Let's ask the question, [[What is WebEngine]]?.


WebEngine is a static-first PHP toolkit for building web applications with HTML, PHP, and server-side DOM manipulation.

## Main purpose

In plain PHP projects it's very easy for one file to end up doing everything at once: read input, run business rules, talk to the database, output HTML, set cookies, redirect the browser, and so on. That is often fine at the start of a project, but once a few pages and features are added it becomes difficult to follow what happens during a request.

WebEngine gives that work a more obvious shape. A page view holds the HTML, a matching page logic file can make it dynamic, and application classes can hold the behaviour that does the real work. The aim is not to hide the web behind lots of abstraction, but to let the structure of the application reflect the structure of the request.

That is why the framework stays close to the web platform. URLs are still important. HTML is still the response. Forms and links still matter. PHP is used where server-side logic is needed, but the page can begin life as a normal static document.

## How it works

At the centre of WebEngine is the pairing of a page view and page logic. A file such as `page/about.html` is the [[page view]]. If the page needs behaviour, `page/about.php` can be added beside it. When the browser requests `/about`, WebEngine routes the request to those files automatically.

Inside the [[page logic]], the page is made dynamic by working with the server-side document object model (DOM) rather than by echoing strings of markup. The page is made dynamic by [[binding data to the DOM]]. If you need lower-level control, manual [[DOM manipulation]] is available and already feels familiar to web developers. 

## PHP.GT repositories

WebEngine brings together a collection of smaller PHP.GT packages and wires them into one request pipeline. That includes:

- routing and request handling - https://www.php.gt/routing
- page rendering for HTML and API responses - https://www.php.gt/routing and https://www.php.gt/json
- DOM templating and server-side binding - https://www.php.gt/dom and https://www.php.gt/domtemplate
- input, cookies, and sessions - https://www.php.gt/input, https://www.php.gt/cookie and https://www.php.gt/session
- configuration loading - https://www.php.gt/config
- database access - https://www.php.gt/database
- a service container - https://www.php.gt/servicecontainer
- local server and build tooling - https://www.php.gt/server, https://www.php.gt/build
- command line helpers through `gt` - https://www.php.gt/gtcommand

Because those parts are maintained as separate projects, the docs often link out when a subject deserves more detail than the WebEngine guide needs to carry.

## Who is it for?

The overall aim throughout GT repositories is to provide an alternative, minimalistic approach to web development. If you're tired of working with the so-called "full stack", there might be something of interest to you here.

All GT repositories are designed to be inclusive to novice developers. Each repository is designed to operate independently, allowing developers to leverage individual components without necessarily needing to adopt the entire framework or possess prior knowledge of WebEngine. This modular approach not only enhances flexibility but also promotes a more focused, purpose-driven development experience.

WebEngine itself provides a "batteries-included" default configuration and has an accessible entry point for beginners. However, its capabilities extend far beyond basic use-cases; WebEngine is robust enough to power large-scale, real-world applications serving millions of users.

*****

Learn about WebEngine's [[core principals]], or go straight to the [[quick start]].


# 1. The web is the best platform

Building for the web is the fastest and easiest way to share what you've created. Nearly [everything you could want a computer to do](https://developer.mozilla.org/en-US/docs/Web/API) is possible using the web platform: playing and recording audio and video media, interacting with MIDI musical instruments, building interactive 3D VR worlds... and making a form-based CRM save to a database. Whatever you can dream, the web has you covered.

The web was designed in the early 1990s. The functionality (and changes to functionality) is discussed in depth by an international collection of businesses and individuals that make up the W3C to form web standards. These standards are designed with such clever foresight that there have only been a handful of version increases over the decades, and everything is designed to be backwards compatible. What other engineering job comes with this much clarity, stability, and [fantastic documentation](https://developer.mozilla.org)?

WebEngine is designed to work with existing web technologies, rather than inventing new ones.

# 2. Optimise for humans

People choose a web framework because it aligns with their personal values of what it means to be a developer, not just because it's the fastest, securest, lightweightest, etc.

A good developer experience breeds a good user experience.

WebEngine development is designed to incite joy, and with that, everyone can be happy.

# 3. Start static: HTML is excellent

HTML can be used to build interfaces for desktop computers, VR headsets, laptops, mobile phones, smart watches, and everything in between.

Tools and techniques can be used to convert HTML into other native user interfaces.

The barrier to entry of writing HTML is simply having access to a computer with a text editor.

Web servers and web browsers are unbelievably efficient at sending content over the internet and rendering it in near real-time.

WebEngine is designed to embrace HTML-first development. Allow splitting HTML into different pages and components, and then treat PHP the same: a single file with a [single, obvious responsibility](Distinct-Logic-Authority) is perfect.

That also means a page does not need to stop being useful just because it starts static. A complete HTML page can be put in front of a user very early, then later gain form handling, data binding, richer interactions, and background updates without being thrown away and rebuilt. In web development this is usually called progressive enhancement, and WebEngine is designed to make that style of growth feel natural.

# 4. No surprises

When picking up someone else's code, or even when looking at your own code from 6 months ago, it's difficult to get into the flow of what's happening. How does the routing work? Where is that class getting instantiated? Why is this parameter this value?

WebEngine is designed to be as quick to pick up by anyone who's ever seen or heard of HTML and PHP. WebEngine and the applications built in it are understood by IDEs and LLMs, so accelerating development with the right tools is a breeze.

# 5. Optimise for humans

Code layout should help people reason about requests and changes. When a new developer opens a project, they should be able to answer simple questions quickly: where does `/account/settings` live, which file handles the form submit, where is the SQL, and which class applies the business rule?

That is why obvious file locations matter. If a file maps to a URL, that should be clear from its path. If a class is part of the application domain, it should live in an obvious namespace. If a page depends on a template, component, or query file, those should be easy to find without detective work.

This also explains the preference for reducing framework-shaped code. The more a project reads like ordinary HTML, PHP, SQL, and browser behaviour, the easier it is for people to understand and maintain. Modern tools also benefit from that clarity. IDEs, static analysis tools, and large language models (AI) all work better when the codebase has an obvious shape, but the point is still to **help the humans stay in control** of what is being built.

*****

Continue to the [[installation]] page, or write our first page in the [[Hello World tutorial]].


The quickest way to get started is to install the PHP.GT tooling so the `gt` commands are available in your terminal. Those commands create projects, run the local development server, start the asset build watcher, run tests, and handle a few other common tasks while you're building an application.

If you already have PHP and Composer installed, the fastest route is:

```bash
curl https://install.php.gt | sh
```

That script is intended for a development machine. Like any script piped from the internet into a shell, it is worth reading before running if you are unsure. A cautious way to do that is:

```bash
wget https://install.php.gt -O install.sh
less install.sh
sh install.sh
```

WebEngine itself requires a modern PHP installation (>=8.5) with the usual extensions for DOM, JSON, and cURL. Composer is used to install the package and manage the rest of the dependencies.

## Installing the tooling

The installer script aims to put the `gt` command somewhere sensible on your machine and make sure the underlying PHP.GT installer package is available. Once that is done, creating a new WebEngine project becomes a one-line command rather than a manual Composer setup.

If you would rather install things manually, that is fine too. Composer can be used to install `phpgt/installer` globally, which exposes the same `gt` command through Composer's global `vendor/bin` directory. The separate installer docs are at https://www.php.gt/docs/Installer/ for more information on manually installing.

WebEngine can also be used without a global `gt` command at all. In that case, create a normal PHP project and require `phpgt/webengine` in the project's own `composer.json`. The [[Quick start]] page shows both approaches.

## Verifying the install

Once the tooling is installed, run:

```bash
gt
```

If the install is working, you should see a list of available commands. It is also worth checking the versions of PHP and Composer that your shell can see:

```bash
php -v
composer --version
```

If either command is missing, or points at a different PHP version than you expected, sort that out now before creating a project - it usually saves time later.

*****

Next, move on to the [[quick start]] guide.


This page is the shortest route from a fresh machine to a running WebEngine application. If you want more background on installation choices, see [[Installation]]. Here we will keep to the fastest useful path first.

## Install `gt`

The `gt` command is the small command line wrapper around the normal tasks of starting, building, and testing a WebEngine project. If you have not installed it yet, follow the short install route:

```bash
curl https://install.php.gt | sh
```

Once that is done, run `gt` on its own. If a command list appears, the tooling is ready.

## Create a new project

To create a new project, choose a directory where you keep your code and run:

```bash
gt create my-first-app
```

By default this creates a minimal WebEngine project with the standard directory layout and a starter page. You can also choose a namespace and blueprint via command line arguments, otherwise `gt` will interactively ask you how to proceed.

```bash
gt create my-first-app --namespace App --blueprint Hello-World
```

The project name becomes the directory on disk. The namespace controls the PHP namespace used for classes in the project. A blueprint is a starter project shape. If you omit it, you get an empty application scaffold.

### Manually create a project without `gt create`

If you prefer not to use `gt create`, you can still create a project by hand:

```bash
mkdir my-first-app
cd my-first-app
composer require phpgt/webengine
```

From there you can create a file at `page/index.html` with whatever contents you like.

## Run the Project

From the project root, run:

```bash
gt run
```

This starts the local development server and, where needed, also runs the build watcher and cron watcher for the project. In a tiny starter app those extra pieces do very little, but once the application grows they become part of the normal development loop.

If you only want the PHP server, use:

```bash
gt serve
```

Without `gt`, the local server can still be started with PHP's local development server: `php -S 0.0.0.0:8080 vendor/phpgt/webengine/go.php -t www`.

## Viewing in the web browser

With some page content inside `page/index.html` and the server running on port 8080, visit http://localhost:8080/ and you should see your page.

That is the static-first approach in its simplest form: begin with plain HTML, check the page in a browser, and add PHP when the page needs dynamic behaviour. The page at `page/index.html` is visiable at http://localhost:8080/ (the filename "index" is assumed), and you can create any other page name such as `page/example.html` that will be visible at http://localhost:8080/example/

*****

Check out the [[gt command overview]], or move on to building our first page in [[Hello World tutorial]].


The `gt` command gathers the everyday WebEngine tasks behind one interface. Rather than remembering a list of package-specific commands, you can create, run, build, test, and manage a project from one place.

It is mainly a development convenience. A production deployment does not depend on `gt` itself. Underneath, the project is still a normal Composer-managed PHP application.

## Core commands

The commands you will use most often are:

- `gt create` to create a new project
- `gt run` to start the local development setup
- `gt serve` to run only the PHP development server
- `gt build` to copy or compile client-side assets
- `gt test` to run the project's test suite
- `gt cron` to run scheduled jobs locally

You do not need to memorise every flag immediately. The important thing early on is knowing which command belongs to which kind of task.

## Typical daily workflow

A fairly normal day with WebEngine might look like this:

1. Create a project with `gt create` if you are starting something new.
2. Start the app with `gt run`.
3. Edit the page view, page logic, or application classes.
4. Run tests with `gt test`.
5. If you are changing client-side assets, let `gt run` or `gt build --watch` keep them up to date.

Commands such as `gt create` are used occasionally, while `gt run` and `gt test` tend to become part of the normal loop.

See the full reference of [[gt commands]], or move on to the [[Hello World tutorial]].


Here we will build the smallest possible WebEngine application: Hello World.

That tiny program still teaches us something useful. It proves the development environment is working, shows where the first page lives, and demonstrates the static-first approach with almost no moving parts.

## Create the Project

Start by creating a project:

```bash
gt create first-webengine-app --empty
cd first-webengine-app
```

This creates a new directory and uses Composer to set up WebEngine's dependencies. At this stage, the most important part is the `page/` directory, because that is where the first view will live.

## Add the First Page

Create `page/index.html` and add the hello world HTML:

```html
<!doctype html>
<h1>Hello, World!</h1>
```

That file is the page view for the root URL. In other words, a request to `/` maps to `page/index.html`.

## Run and inspect

Now serve the application:

```bash
gt serve
```

Then open `http://localhost:8080` in your browser.

You should see the page exactly as written. It is worth using the browser's "view source" feature as well. At this point there is no hidden rendering step and no client-side framework in the middle. The response is simply the HTML page.

## What this teaches

This first step shows an important part of WebEngine's shape: a valid application can begin as a normal HTML file. There's no need to write any PHP just to make the framework happy.

That may seem like a small point, but it affects how the rest of the application grows. We can start with page structure and content first, then add routing, logic, input handling, and data only when those things are actually needed.

*****

Before we continue to the next tutorial, it's recommended to read about the [[Project layout]], or we can jump straight to the [[Hello You tutorial]].


WebEngine relies on an obvious project layout. That is one of the ways it keeps page routing and application structure easy to follow.

When a project grows, the directory structure should help answer simple questions such as where a page lives, where its logic lives, where a query belongs, and which files are public on the web.

## The main directories

The directories we will meet first are:

- `page/` for page views and their matching page logic files
- `class/` for application classes
- `query/` for SQL files
- `www/` for the public web root
- config files such as `config.ini`

The contents of all directories are authored directly by you, except the `www/` directory, where files are mainly generated or copied by WebEngine. There should be minimal files stored within the www directory - only static assets that need to exist directly in the public web root. Common examples include `manifest.json`, `robots.txt`, `favicon.ico`, `site.webmanifest`, etc.

### List of all directories in a large WebEngine project

- `api` - optional endpoint files for API-style responses, similar to how the `page` directory is routed, but for different content types.
- `asset` - source images, fonts, icons, and other static resources that will be copied into `www/`.
- `cache` - generated directory of temporary files, generated by your code to speed up slow actions such as making remote calls to third-party servers.
- `class` - application classes, organised by namespace and responsibility.
- `cron` - command-line scripts or scheduled tasks that run outside the normal request cycle.
- `data` - project-owned local data files, such as seed data, imported reference data, or generated application content that should not be public.
- `node_modules` - generated directory of front-end build dependencies installed by `npm` or a compatible package manager.
- `page` - page views, page logic, and special page-related directories such as `_component`, `_partial`, and `_error`.
- `query` - SQL query files and database migration files.
- `script` - source JavaScript, TypeScript or other EcmaScript files that are built or copied into `www/`.
- `style` - source CSS, Sass, or other stylesheet files that are built or copied into `www/`.
- `vendor` - generated PHP dependencies installed by `composer`.
- `www` - the public web root containing browser-ready files served directly by the web server.

## How requests map into the project

When a browser requests a URL such as `/about`, WebEngine looks in the `page/` directory for the matching view and logic files. A route such as `/about` usually maps to files such as:

- `page/about.html`
- `page/about.php`

That same idea continues for nested paths. A request to `/account/settings` maps to the corresponding location under `page/`.

Static assets such as images, built CSS, and built JavaScript are served from `www/`, not from `page/`. That keeps the authored application files separate from the public web root. However, it's recommended to store static files in their dedicated directories, such as `script` for JavaScript, `style` for CSS, and `asset` for images or other static files. WebEngine will automatically copy them to the `www` directory, performing any compilation steps required according to their file type. See [[Build system]] and [[Asset compilation]].

## Layout as an architectural tool

This directory layout reinforces separation of concerns. Views stay in one place, application classes stay in another, and raw SQL can live in its own directory instead of being mixed through page logic.

It also helps with discoverability. If you know the URL, you can usually find the page files quickly. If you know the class name, you can usually find the class from its namespace. The layout is not only about tidiness; it helps you reason about the application as it changes.

*****

Learn how to [[Run an application]], or read about the [[request-response lifecycle]].


## Local development flow

`gt serve` starts the PHP development server, but in real applications there's more to running than just running a server.

`gt run` is the commonly-used development command because it starts the local server and also takes care of the other background tasks a project may need, such as asset building and cron jobs. In a tiny project there may be no visible difference yet, but in a fuller application `gt run` is what we'll use to get the project running in a web browser.

Use `gt serve` when you only want to test the PHP page handling layer and do not need those supporting background processes. Use `gt build` separately when you want to compile or copy client-side assets without also starting the server.

## Background jobs

When `gt run` starts, the public files served by the browser still come from `www/`, while page requests that are not static files are passed through WebEngine's `go.php` entry point, to be routed to our application's source code.

That means two kinds of work are happening locally:

- ordinary static file serving from `www/` (served directly from [[web servers]]).
- dynamic page rendering through WebEngine.

On top of that, the build system may be watching your asset source files for [[asset compilation]], and the cron runner may be watching for scheduled tasks. Those jobs are not part of every project, but it is useful to understand early that "running the app" often means running more than one process.

## Background tasks using `crontab`

If your project needs scheduled tasks during development, add a `crontab` file in the project root. That file describes which commands should run and when they are due.

The important idea is that these jobs are part of the application, not part of the web request itself. Typical examples include:

- refreshing cached data
- sending queued emails
- importing data from another system
- cleaning up expired files or sessions

When you use `gt run`, the cron watcher can run alongside the web server and asset pipeline. When you want to work with scheduled tasks directly, use `gt cron`.

See [[Background cron tasks]] for the project-side setup, and [[gt commands#`gt cron`]] for the command reference.

*****

Next, let's learn about the [[request-response lifecycle]].


When working with any tool, it is important to understand _how_ the tool works. Here we will look under the bonnet at what makes WebEngine work so you can use the knowledge to make the best decisions when writing applications.

Within PHP.GT, everything is broken down into its own repository of single responsibility. The PHP.GT WebEngine brings all of these components together to produce a full application framework. As the name suggests, this framework utilises _web_ technologies and the purpose of this page of the documentation is to walk through what goes into the whole lifecycle of the application.

## Step 0: A request is made

The lifecycle starts its journey when a user enters a URI or clicks a link to be taken to a page within your application.

Before any code is executed, an HTTP request from the user's browser will be received by the web server. This can be any server, such as NGINX, Apache or the inbuilt server.

The job of the server is to listen for incoming requests and send back the correct response in the form of a static file (such as an image), a WebEngine page (handled by your code), or a `404 Not Found` message.

When a request to a page of your application is received by the server, the request/response lifecycle begins. The entry point of all WebEngine requests is the `go.php` file in the root of the WebEngine directory. This is sometimes referred to as the router script. If WebEngine is installed using Composer, the path to the router script will be `vendor/phpgt/webengine/go.php`.

See the [[web servers]] section for more information about configuring servers and using the inbuilt server.

### Step 1: Go!

> Follow along in code by [viewing the source][go.php].

The [`go.php` file ][go.php] firstly loads the Composer autoloader. This allows object oriented code to be loaded automatically and efficiently based on the namespaces of the classes used. [Read the introduction to Composer article at getcomposer.org][composer] for more information.

Next, the script checks to see if the incoming requested file exists in the public web root of your application. If a static file exists, the script immediately returns `false`. This is used by the inbuilt server as to not accidentally process static files. "Real" web servers such as NGINX and Apache should not get this far, as they should detect and serve static files themselves.

If there's a `setup.php` file in the project root, it will be loaded here. This allows us to inject any plain PHP to the start of the request before the Application has started at all, useful for tweaking the environment or setting up a custom error logger, for example.

Finally, now the Composer autoloader is in place, we can utilise the benefits of object oriented code by instantiating our first object - the Application object. We call the `start()` function of the `Application` object to jump into object oriented code. From here on, all executed code is done in a structured, predictable and understandable manner, thanks to Composer's autoloading namespaces.

### Step 2: The start of the `Application` Lifecycle

[The `Application` class][Application.php] initialises and calls the core elements of PHP.GT that make up WebEngine. The `start` function abstracts this as much as possible, giving you a high-level overview of what's going on.

Within the `start` function, all core objects are created:

- [`Config`][phpgt-config] - loaded first so the rest of the request can use project settings.
- `Redirect` - checks file-driven redirects before the main application lifecycle continues.
- `Timer` - measures the full request duration and logs slow requests.
- `OutputBuffer` - captures unexpected direct output so the response stays under framework control.
- [`RequestFactory`][request-factory] - builds the incoming [`Request`][request] object from PHP globals.
- [`Dispatcher`][dispatcher] - prepares routing, services, view handling, logic execution, and the final [`Response`][response].
- `Protection` - locks down direct access to superglobals and replaces them with explicit object-oriented access.

With the above objects created, the `Application` object passes them to areas of WebEngine and your code where required. Let's continue the journey...

### Step 3: Configuration

The responsibility of loading project configuration is maintained within the [PHP.GT/Config][phpgt-config] repository. In WebEngine, we call the `ConfigFactory`'s `createForProject` function which allows many `.ini` files to be loaded, overriding defaults where necessary. This is useful to allow for different configuration per environment, such as on a staging server versus the live server.

Learn more about configuration in the [[Configuration]] page.

### Step 4: Redirects, timing, and output buffering

Before the main request is handled, the `Application` checks whether the current path matches a redirect rule. If it does, the redirect is performed immediately and the rest of the lifecycle does not continue for that request.

If there is no redirect, WebEngine starts a timer and opens its debug output buffer. The timer is later used for request logging and slow-request notices. The output buffer captures any direct `echo` or debug output, so that the framework can still control the final HTTP response cleanly.

### Step 5: Protect globals and build the request

At the start of the application lifecycle, WebEngine protects the PHP superglobals. This prevents page code and third-party code from casually reaching into `$_GET`, `$_POST`, `$_FILES`, `$_COOKIE`, `$_SERVER`, and related globals.

The reason for this is code safety: if every function can read and write global state directly, it becomes hard to track where input came from, which code changed it, and whether unrelated code can interfere with the request.

Once those globals are protected, [`RequestFactory`][request-factory] builds a [`Request`][request] object from the original request data. That object becomes the main representation of the browser request for the rest of the lifecycle.

### Step 6: Create the dispatcher

With configuration loaded and the request object available, `Application` creates a [`Dispatcher`][dispatcher]. This object owns most of the framework work that follows:

- setting up the service container
- preparing the response object
- normalising the request path
- loading router and view information
- starting the session
- executing page logic
- streaming the final view into the response body

The dispatcher is also stored on the `Application` so that if an error occurs later, WebEngine can reuse the same request context when trying to render an error response.

### Step 7: Initialise routing and view state

Inside the dispatcher, several setup stages happen in order:

First, the application autoloader is attached for our own namespaced classes, and the logic stream handler is prepared for page logic loading. Next, request initialisation normalises the path and can prepare an immediate redirect, such as for trailing-slash behaviour.

If no redirect is prepared, router initialisation loads the application's router, decides which view model type is needed, and builds the `Assembly` objects that describe the view and logic files for the current route.

At this point WebEngine knows which page is being handled, which view file belongs to it, which logic file belongs to it, and whether the response is HTML, JSON, or effectively empty.

### Step 8: Start sessions and bind the view model

Once routing is known, the dispatcher starts the session using the configured session handler and places the session object into the service container.

Learn more about session usage in the [[Sessions]] page.

Then the view model is initialised. For HTML responses this includes preparing the document binder and related DOM binding helpers, as well as processing partials and components. This is where the framework gets the page ready for your logic to bind data into it cleanly.

That work makes more sense once you have read [[page views]], [[binding data to the DOM]], and [[DOM manipulation]].

### Step 9: Execute page logic

When the dispatcher generates the response, it first checks whether the route resolved to any actual page files. If neither a view nor a logic file exists, WebEngine raises a `404 Not Found`.

Otherwise, the dispatcher processes the response in a defined order. It resolves dynamic path values, processes partial content, verifies CSRF state where required, initialises the view model, and then executes logic hooks for components followed by the page itself.

The logic execution order is:

1. `go_before`
2. matching `do_*` handler if a `do` input value is present
3. `go`
4. `go_after`

That order preserves the original WebEngine concept that page logic coordinates the incoming request, while still giving us explicit hook points before and after the main page action has executed.

See [[page logic]], [[page logic conventions]], and [[file-based routing]] for the request-facing conventions behind these hooks.

### Step 10: Build the response body and headers

After logic has run, WebEngine applies response headers collected during the request, performs document cleanup, applies CSRF protection to the HTML where needed, and then streams the view model into the response body.

If our code did not set a status code explicitly, WebEngine finishes normal responses with `200 OK`. It also records the executed logic hooks in an `X-Logic-Execution` response header. That header contains the page logic functions that ran, in execution order, using a compact `path:function` format. It is useful when checking which shared and page-specific handlers actually participated in a request.

For more on that header and the way WebEngine surfaces development-time traces, see [[Development diagnostics]].

The resulting [`Response`][response] object is now a complete HTTP message containing headers, status, and body.

### Step 11: Finish and send the response

The last step happens back in the `Application` object. Its `finish` method sends the response headers, performs request logging where configured, writes the response body to the browser, and then stops the timer.

That is also where slow-request timing is logged and where debug output collected by the output buffer can be appended in development-oriented scenarios.

## Where application code runs

Our application code mainly enters the lifecycle once routing has discovered the relevant page files. The matching page logic file is where WebEngine looks for handlers such as `go_before`, `do_*`, `go`, and `go_after`.

The best companion pages here are [[page logic]], [[page logic conventions]], and [[service container]].

By the time those handlers run, the important request-related services are already available. That includes input handling, sessions, configuration, and the view model itself. Those services are supplied through the service container, so page logic can stay light and ask only for what it needs.

In practice that means page logic should mainly coordinate the request:

- read the relevant input
- call application classes
- bind data into the document
- redirect or set response state where needed

Anything heavier than that usually belongs in [[application classes]] rather than in the page entry point itself.

## How errors fit into the lifecycle

If something goes wrong while the request is being handled, WebEngine catches the throwable, logs it, and attempts to render the appropriate error response. In development that usually means more detail is available. In production the response should be simpler and safer.

The framework can also look for application error pages, so error output can match the rest of the site rather than falling back to plain text or a default PHP error screen. The details of that are covered later in [[Errors and logging]].

*****

Now we've covered the page lifecycle, let's move on to [[file-based routing]].

[go.php]: https://github.com/phpgt/WebEngine/blob/master/go.php
[Application.php]: https://github.com/phpgt/WebEngine/blob/master/src/Application.php
[composer]: https://getcomposer.org/doc/00-intro.md
[phpgt-config]: https://github.com/PhpGt/Config
[request-factory]: https://github.com/PhpGt/Http/blob/master/src/RequestFactory.php
[request]: https://github.com/PhpGt/Http/blob/master/src/Request.php
[dispatcher]: https://github.com/PhpGt/WebEngine/blob/master/src/Dispatch/Dispatcher.php
[response]: https://github.com/PhpGt/Http/blob/master/src/Response.php


In WebEngine, routes are file-based. That means the requested URI directly maps to project files, instead of having a central routing table. This keeps routing obvious and predictable. If we know the URI, we can usually guess where the view and logic files live. If we know the file path, we can usually guess the URL.

## How paths resolve

The root URL `/` maps to `page/index.html`. A nested URL such as `/about/team` maps to `page/about/team.html`.

Directory-style URLs are also supported. That means a path can resolve through an `index` file inside a directory. For example:

- `/` -> `page/index.html`
- `/blog` -> `page/blog.html` or `page/blog/index.html`
- `/blog/post` -> `page/blog/post.html`

Those two forms are alternatives, not companions. If a project contains both `page/contact.html` and `page/contact/index.html` for the same route, WebEngine treats that as an ambiguous path and throws an exception rather than guessing which file should win.

## HTML and PHP pairing

Each route can have an HTML view file, a PHP logic file, or both. In the normal case:

- `page/about.html` is the page view, describing the page's layout and structure
- `page/about.php` is the page logic, defining the page's behaviour and adding dynamic content

If only the HTML file exists, the page is static and will be served without change. If only the PHP file exists, there is no page view to render and the route is incomplete. WebEngine expects a view for a page response.

This pairing is one of the main shapes to get comfortable with. It lets the response be built from ordinary HTML first, with PHP added only when the page actually needs dynamic behaviour.

## Keep code obvious

This model makes code navigation fast because there are fewer places to look. There is no need to search through a routing table before we can find the page.

It also keeps more advanced features straightforward. Dynamic routes, shared headers and footers, components, and partials all build on top of the same idea that a path on the web should map cleanly to a path in the project.

There are tools for keeping page files tidy as they grow: [[Custom HTML components]] for splitting HTML tags into their own reusable files, and [[Page partials]] for defining reusable templates.

*****

Let's learn about HTML in [[page views]], then we'll cover PHP in [[page logic]].


A page view is the HTML that represents the response sent back to the browser. It stays as HTML on disk rather than being assembled from PHP string output.

That separation is important because it means the page can be designed, read, and reviewed as a document in its own right.

## Static HTML as the starting point

The simplest useful page view is just a normal HTML file. We can open it in an editor, write the structure we want, and serve it immediately.

That is helpful while prototyping because the first version of a page can be built and discussed as plain markup. Later, the same file can become production code by adding page logic, components, partials, and binding.

Default placeholder content can stay in the HTML too. Later, when data is bound into the document, those default values can be replaced. Until then, the file can still read well and make sense on its own.

For example:

```html
<h1>User profile</h1>

<p>Display name: <span data-bind:text="displayName">none given</span></p>
```

If there is no `displayName` bound to the HTML, the page displays the default message "none given", just as it would do without using a framework.

## How views are loaded

When a request matches a route, WebEngine loads the matching view file from `page/`. In many cases that is just one file, but a full response may also include:

- inherited layout through [[page partials]]
- shared framing through [[headers and footers]]
- reusable fragments through [[custom HTML components]]

Those features still result in one final HTML document, but they allow the source views to stay smaller and easier to maintain.

## Good practices for page views

Keep page views semantic and readable. Write the HTML so another developer can understand the page structure without needing to read the PHP first.

It also helps to design the page shape before adding logic. Once the structure is visible in HTML, it is much easier to decide which parts need binding, which parts need reusable components, and which parts should stay static.

## Connecting page views to page logic

There are three methods of connecting a view to its logic:

1) `data-bind` attributes in HTML - this allows automatic hydration of pages where the HTML defines the shape and PHP defines the data, [[binding data to the DOM]] automatically.
2) Form `do` buttons - if a button has the name `do`, its value is used to execute a PHP function when clicked. This is covered in [[page logic]].
3) Direct [[DOM manipulation]] of the page from PHP.

*****

When views need to be made dynamic, we'll use [[page logic]].


Page logic is the PHP entry point for a page request. Its job is to respond to the request, coordinate the application code that does the real work, and prepare the final page response.

That makes it a good place for orchestration, but not a good place for large business rules. Complex tasks and heavy lifting should be done in [[application classes]] instead.

## How logic pairs with a view

Like page views, page logic files are discovered from the URI. A request to `/about` can use:

- `page/about.html` for the page view
- `page/about.php` for the page logic

If there is no logic file, the page is simply static. That is completely valid and is often the right place to start.

## Logic hooks

### `go` functions

To execute PHP when a request is made, the `go` function is the standard entry point for a page. It gets executed automatically during a normal request, after WebEngine has prepared the request, response, service container, and view model.

In `go`, we usually read input, call application classes, and bind the results into the page.

An example page logic, that simply changes the title of the page, looks like this:

```php
use GT\Dom\HTMLDocument;

function go(HTMLDocument $document):void {
	$document->title = "Title changed from PHP!";
}
```

The parameters of `go` functions are dynamically injected at runtime. This means you can request any object as a go parameter, and WebEngine will provide you with a matching instance from its [[service container]]. 

Here's a more complex page logic that takes the user input, binds a value to the document, or redirects if the value is not set:

```php
use GT\DomTemplate\Binder;
use GT\Input\Input;
use GT\Http\Response;
use App\Invoice\InvoiceRepository;

function go(Binder $binder, Input $input, Response $response, InvoiceRepository $invoiceRepository):void {
	$invoiceCode = $input->getString("invoice");
	$invoice = $invoiceRepository->getById($invoiceCode)
	
	if(!$invoice) {
		$response->redirect("?no-invoice");
	}
	
	$binder->bindKeyValue("total", $invoice->calculateTotal());
}
```

Logic functions should not output anything directly. If an `echo` or var_dump is made from page logic, WebEngine captures that output and sends it to the browser's developer console.

### `do` functions

`do` functions are for named user actions. When a request includes a `do` value, WebEngine looks for a matching `do_*` function and runs it.

For example, if a form submits `do=save-profile`, WebEngine will look for:

```php
function do_save_profile():void {
	// ...
}
```

`do` functions behave in the same way as `go` functions, and share the same [[service container]], so the parameters can define the scope of what each function has access to.

### Order of execution

If present, the hooks run in this order:

1. `go_before`
2. matching `do_*`
3. `go`
4. `go_after`

When logic is assembled from multiple matching files, the ordering follows the router's assembly rules so the broader shared logic and the more specific page logic run in a predictable sequence. In practice, this means we can use shared logic without losing the obvious page-specific entry point.

To avoid any doubt, WebEngine emits an `X-Logic-Execution` header containing a list of all logic functions that were executed on the request, in order of execution. This header is not sent when in production mode.

## What to do in page logic

Page logic is a good place to:

- reading [[user input]]
- calling [[application classes]] or services
- [[binding data to the document]]
- redirect the browser
- set headers or response state

## What NOT to do in page logic

Avoid putting large business rules in the page file. Avoid raw SQL manipulation code. Avoid building HTML in strings. Avoid relying on `echo` for normal output.

Page logic works best when it's easy to scan, and should work like a newspaper: the developer should be able to read the headlines, and click through to the [[application classes]] when they need more detail. A good page file should make the request flow obvious at a glance.

*****

Now the pages can have dynamic content, let's learn about [[dynamic URLs]].


Static file mapping is enough for many pages, but real applications often need one page to handle many similar URIs. A blog article, product page, user profile, or category listing are all common examples.

> [!NOTE]
> You'll see the term "URI" used alongside "URL" and sometimes "URN" when reading web development documentation. There are nuanced differences, but in most everyday web development, these terms are used interchangeably.

## How dynamic routing works

WebEngine uses `@` markers in file and directory names to represent dynamic parts of the path.

For example:

- `page/blog/@slug.html`
- `page/shop/@category/@product.html`

If the browser requests `/blog/hello-world`, WebEngine can match that to `page/blog/@slug.html`. The same view and logic files can then be reused for every blog post.

`@@` is used for a deeper catch-all style of matching, where one dynamic part may represent more than one path segment. That is useful more rarely, but it allows broader matching when a single-segment `@name` route is not enough.

An example of catch-all dynamic matching could be `page/maps/address/@@address-parts.html`, that could provide a single page view for all URIs such as `/maps/england`, `/maps/england/east-midlands`, and `/maps/england/east-midlands/derby`.

The values captured from the path are made available through the `GT\Routing\Path\DynamicPath` object in page logic, so the application code can read values such as the current slug or category.

```php
use GT\Routing\Path\DynamicPath;

function go(DynamicPath $dynamicPath):void {
	$slug = $dynamicPath->get("slug");
	
	// ... load item from database using $slug
}
```

## Choosing good dynamic URIs

Good URIs are readable and stable. A path such as `/blog/hello-world` usually tells us more than `/post?id=42`, and it maps neatly to the file structure at the same time.

The URI is also part of the application's interface. Users bookmark it, share it, and rely on it when moving around the site. Keeping the path meaningful usually leads to clearer code as well. [Cool URIs don't change](https://www.w3.org/Provider/Style/URI)!

## Dynamic Pages and Page Logic

One dynamic page can serve many related requests. The matching page logic file can then use the captured path values to load the right data, handle 404s for missing records, and bind the correct content into the page.

That gives us reuse without giving up the file-based model. You can see this in action in the [[address book tutorial]].

*****

Let's move on to how page [[headers and footers]] can be added automatically, or jump ahead to [[page partials]].


Many applications have shared HTML at the top and bottom of most pages. Rather than repeating that markup in every view file, WebEngine can load special `_header.html` and `_footer.html` files automatically.

That keeps the shared framing consistent and reduces repeated HTML in the project.

## How header and footer files work

Headers and footers are discovered by special filenames. A file such as `page/_header.html` is applied before the page view, and `page/_footer.html` is applied after it.

Those files can also appear in nested directories. For example, `page/admin/_header.html` applies within the `/admin` section. That makes it possible to give one area of the application its own framing while still keeping the project-wide layout elsewhere.

When several levels are involved, WebEngine assembles them in a predictable order so outer headers appear before inner ones, and inner footers appear before outer ones on the way back out.

Keeping a consistent header and footer throughout the application also helps the architecture stay simple. The page views can focus on page content while the common framing is handled in one place.

## When to use them, when not to use them

Headers and footers are a good fit for:

- site-wide page chrome
- section navigation
- repeated metadata or framing content

They are less useful when the layout needs deeper composition rules. In that case [[page partials]] or [[custom HTML components]] may be a better fit.

There is also one hard rule to keep in mind: header and footer files should not be mixed with partial-based page inheritance in the same response. WebEngine treats those as two different layout techniques.

*****

HTML can be reused and kept tidy with [[custom HTML components]], and more advanced page layouts can be achieved with [[page partials]].


In WebEngine, custom HTML components let us write our own element names such as `<main-menu>` or `<user-card>` and define the underlying HTML in one reusable component file.

This is different from browser-defined Web Components. Here the component is expanded on the server while the page is being rendered, so the browser receives ordinary HTML in the final response.

Each component can also have its own PHP logic. When that logic runs, it receives a `Binder` that is scoped to the component's element, which keeps the binding work isolated to that component rather than the whole page.

## When to use components

Components are useful when a fragment of HTML appears in many places and has a clear boundary of its own. Navigation menus, cards, callouts, profile summaries, and other small UI building blocks are all common examples.

They also help keep page views smaller. Instead of one long file containing every repeated block, the larger page can reference named components and stay focused on the overall document structure.

If a component needs its own focused logic, that logic can stay beside the component rather than being duplicated across several page files.

## Component discovery

Component files live in the component directory, which by default is `page/_component`.

For a tag such as `<main-menu />`, WebEngine looks for the component view at `page/_component/main-menu.html`.

If component-specific logic is needed, the matching PHP file can live alongside it at `page/_component/main-menu.php`.

## Example main menu

The page HTML can look like this:

```html
<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>Example page with a main-menu component</title>
	</html>
	<body>
		<header>
			<a href="/"><h1>My website</h1></a>
			
			<main-menu />
		</header>
	
		<section>
			<!-- Page content goes here -->
		</section>
	</body>
</head>
```

The `main-menu` component may have complex structure, or advanced logic for showing which page is selected. This can be isolated in two files:

`page/_component/main-menu.html`:

```html
<nav>
	<ul>
		<li>
			<a href="/about/">About us</a>
		</li>
		<li>
			<a href="/products/">Products</a>
		</li>
		<li>
			<a href="/contact/">Contact</a>
		</li>
	</ul>
</nav>
```

`page/_component/main-menu.php`:

```php
use GT\Dom\Element;
use Gt\Http\Uri;

function go(Element $element, Uri $uri):void {
	$uriPath = $uri->getPath();
	
	// Loop over all links,
	// add "selected" to the containing LI
	// only if the link path matches the current URI.
	foreach($element->querySelectorAll("a") as $link) {
		if($uriPath !== "/" && str_starts_with($link->href, $uriPath)) {
			$link->parentElement->classList->add("selected");
		}
	}
}
```

This simplified example then allows CSS to be used to style the currently selected link differently.

## Good component boundaries

Components work best when they represent a repeated UI fragment with a clear purpose. A good component is isolated and should not know or care about where it fits in the larger document.

There are two objects available in the [[service container]] that apply specifically to components: `GT\Dom\Element` and `GT\DomTemplate\Binder`. In a component, the `Element` is a reference to the component's outer element, which allows our code to manipulate only children of the current element. The scoped `Binder` helps here too because [[binding data to the DOM]] is automatically scoped within the component's element, even if there are multiple elements of the same tag on the page - it can bind values without reaching unexpectedly into the rest of the document.

Reusable custom elements inside page views are provided by DomTemplate, which is documented in more detail at https://www.php.gt/docs/DomTemplate/HTML-Components/.

*****

HTML views can also be extended and kept tidy in [[page partials]], and the view can be made dynamic by [[binding data to the DOM]].


Partials are reusable HTML fragments that can be inserted into page views. They are a layout tool rather than a data-binding tool.

Unlike headers and footers, partials are not automatically applied to every page in a directory. And unlike custom HTML components, they are not intended to behave like named UI elements with their own focused element boundary. They are mainly for composing page structure from reusable pieces.

## Why use partials?

Partials help when repeated sections of markup would otherwise be copied between several pages. They also help keep large page views manageable, especially when several pages share a common skeleton but differ in content.

The practical benefit is that the outer page shape can live in one place while each page supplies only the content that makes it unique. That reduces duplication, makes layout changes less error-prone, and keeps individual page files shorter and easier to review.

This becomes especially useful once a section of the site needs its own layout rules. For example, a public marketing page, an authenticated account area, and an admin area may all share some common structure while still needing different wrappers. Partials let those relationships stay visible in HTML instead of being hidden inside PHP logic.

## Partial file structure

Partial files live in the configured partial directory, which by default is `page/_partial`.

A page view can reference or extend partial content from there, allowing one file to provide the main layout while another fills in the page-specific parts. WebEngine expands those partials before the normal page binding and logic work is complete.

This means the final document shape is assembled first, and then the page logic can bind data into that assembled document.

## A simple partial extension

Page HTML can extend a partial using special INI comment syntax:

```html
<!--
extends=base-page
-->

<h2>Welcome</h2>
<p>This page body will be injected into the template.</p>
```

Base template:

`_partial/base-page.html`

```html
<!doctype html>
<html>
<head>
	<title>My site</title>
</head>
<body>
	<header>
		<h1>My site</h1>
	</header>

	<main data-partial></main>
</body>
</html>
```

If we do this, the page's body content is moved into the template's `data-partial` element.

## Recursive partials

Partials can extend other partials.

That means we can have:

- a page extending a section layout
- that section layout extending a global site layout

DomTemplate expands that chain from the inside out until the final page is assembled.

## Template variables with `[vars]`

The opening comment can also contain a `[vars]` section.

```html
<!--
extends=base-page

[vars]
title=Orders
heading=Order history
-->
```

With these `vars` in place within the page's leading INI comment, any reference to them in `data-bind` elements will be bound before any page logic executes. This allows a page view to override some default HTML content in the partial it extends, such as the `<title>` content, for example.

## When to use partials

Partials are a good fit for:

- shared page sections when pages are more complex than simple `_header` and `_footer` expansion can manage
- layout fragments reused across one area of the application
- page skeletons that several views build upon

Use `_header` and `_footer` when the framing can be global or directory-wide, where the page chrome is consistent across all pages. Use custom components when the repeated fragment behaves more like a reusable UI element. Use ordinary binding when the structure is fixed and only the values change.

Partials help shape the document before data is bound into it. That is why this page is about layout composition, not data binding.

*****

The content within page views can be made dynamic by [[binding data to the DOM]].


Instead of building HTML strings in PHP and echoing them into the response, WebEngine pages bind data into an existing HTML document. That keeps the structure of the page in the view file and keeps the PHP concerned with data and behaviour rather than markup assembly.

## Basic binding concepts

The usual binding syntax is the `data-bind` attribute. It tells WebEngine which part of an element should receive a value.

For example:

```html
<h1 data-bind:text="title">Default title</h1>
<img data-bind:src="photoUrl" alt="" />
```

In page logic, we can then bind values such as `title` and `photoUrl` into the document:

```php
use GT\DomTemplate\Binder;

function go(Binder $binder):void {
	$binder->bindKeyValue("title", "Title from PHP");	
	$binder->bindKeyValue("photoUrl", "/asset/photo/dynamic.jpg");	
}
```

Common binding targets include:

- `text` for text content
- `html` for raw HTML content
- `value` for form values
- normal attributes such as `src`, `href`, `class`, and `alt`

This development pattern allows HTML to include default content, which will remain in the page if PHP doesn't bind a value to it.

## Binding different shapes of data

Binding can work with single values, associative arrays, ordinary objects, and mapped objects that describe how their data should appear in the page.

### Binding individual keys

When we only need to bind one or two values, `bindKeyValue` is usually the clearest option.

Page view:

```html
<h1>Hello, <span data-bind:text="name">guest</span></h1>
<a data-bind:href="profileUrl" href="/login">View profile</a>
```

Page logic:

```php
function go(Binder $binder):void {
	$binder->bindKeyValue("name", "Cody");
	$binder->bindKeyValue("profileUrl", "/user/cody");
}
```

Note that the HTML is perfectly valid _before_ binding: the heading reads **Hello, guest**, and the View profile link goes to the login screen, but once the page is bound, real data can be injected to add user-specific dynamic content.

`bindKeyValue` is useful when the page needs only a few explicit values and each bind should remain obvious at a glance.

### Binding associative arrays

When several values naturally belong together, `bindData` is usually more concise than repeated `bindKeyValue` calls.

Page view:

```html
<h1 data-bind:text="username">Guest</h1>
<p>Email: <span data-bind:text="email">guest@example.com</span></p>
<p>Status: <span data-bind:text="status">Offline</span></p>
```

Page logic:

```php
function go(Binder $binder):void {
	$binder->bindData([
		"username" => "Ada",
		"email" => "ada@example.com",
		"status" => "Reviewing pull requests",
	]);
}
```

`bindData` can take any bindable key-value data source. In practice that usually means an associative array, an object with public properties, or an object that maps its own data for binding.

### Binding objects

Associative arrays are fine for quick examples, but in real applications we often already have proper objects representing our data.

DomTemplate can bind those objects directly, which means we can keep the type safety and behaviour of our domain model instead of flattening everything into arrays first, and objects also come with additional benefits when binding.

PHP class:

```php
readonly class Customer {
	public function __construct(
		public string $id,
		public string $name,
		public DateTime $createdAt,
	) {}
	
	#[BindGetter]
	public function getAgeString():string {
		$now = new DateTime();
		$interval = $this->createdAt->diff($now);

		if ($interval->y > 0) {
			return $interval->y . " years";
		}

		if ($interval->m > 0) {
			return $interval->m . " months";
		}

		return $interval->d . " days";
	}
}
```

Page view:

```html
<h1 data-bind:text="name">Customer name</h1>
<p>Customer ID: <span data-bind:text="id">000</span></p>
<time data-bind:text="createdAt">2000-01-01</time> (<span data-bind:text="ageString">0 days ago</span>)
```

Page logic:

```php
$customer = new Customer(
	"abc123",
	"Cody",
	new DateTime("2016-07-06 15:04:00"),
);

$binder->bindData($customer);
```

Note how the object is constructed with specific values, but the object can represent calculated values such as `ageString` for displaying the age of the Customer.

Read more detail at https://www.php.gt/docs/DomTemplate/Binding-objects/

### Binding lists

For lists and repeated structures, DomTemplate can clone and bind repeated elements from iterable data. That is what makes table rows, card lists, and repeated content blocks practical without hand-building every node in PHP.

Page view:

```html
<ul>
	<li data-list="orders">
		<span data-bind:text="reference">REF-000</span>
		<strong data-bind:text="total">0.00</strong>
	</li>
</ul>
```

Page logic:

```php
function go(Binder $binder):void {
	$binder->bindData([
		"orders" => [
			["reference" => "REF-101", "total" => "19.99"],
			["reference" => "REF-102", "total" => "42.50"],
		],
	]);
}
```

The element marked with `data-list="orders"` is cloned once per item, and each cloned element is then bound with that item's data. The value of `orders` could also be the property of a more complex object, rather than an associative array as in the example above.

Read more detail at https://www.php.gt/docs/DomTemplate/Binding-lists/

## Page logic workflow

The most useful way to think about binding in page logic is as the last step of request orchestration:

1. page logic gathers data
2. application classes shape or load that data
3. the document or part of the document receives the bound values

In practice, the page view should already describe the structure of the response. The job of page logic is then to decide what values belong in that structure.

That separation keeps the HTML readable on its own and stops the PHP from turning into string-building code. It also makes the binding surface explicit: if the page needs a `customerName`, an `orderTotal`, or a list of `orders`, those requirements are visible directly in the markup.

When the page gets more complex, it also becomes easier to move the data-loading and business rules into [[application classes]] while leaving the final binding step in the page entry point.

## Common patterns

Some binding patterns show up repeatedly in real pages:

- detail pages where one object or record is bound into a fixed layout
- dashboards and account pages where several small sections each bind their own data
- tables and lists rendered from arrays, iterators, or result sets
- status badges, links, and images where only attributes change while the structure stays fixed
- forms that bind existing values back into inputs during editing

The common thread is that the document structure already exists in the HTML file. If the structure is stable and the changing part is the data, binding is usually the cleanest approach. If the structure itself must be rearranged heavily, [[DOM manipulation]] may be a better fit for that part of the page.

Binding is provided by DomTemplate, which is documented in more detail at https://www.php.gt/docs/DomTemplate/.

*****

Now we know how to get data out of PHP and on to the page, read [[user input]] for information on how to get data back from the browser to PHP, or see how to perform [[DOM manipulation]] manually.


WebEngine renders HTML by working with a real document model on the server. That means the page can be manipulated using familiar DOM ideas rather than only through string concatenation.

The DOM package itself is documented in more detail at https://www.php.gt/docs/Dom/.

## Direct DOM manipulation vs. binding

Direct DOM manipulation is useful when you need to change the structure of the document, move nodes around, or work with a one-off element relationship.

Example of direct DOM manipulation:

```php
use GT\Dom\HTMLDocument;
use Gt\Http\Uri;

function go(HTMLDocument $document, Uri $uri):void {
	// Mark the link's parent that matches the current URI in as "selected":
	foreach($document->querySelectorAll("main-menu a") as $link) {
		if($link->href === $uri->getPath()) {
			$link->parentElement->classList->add("selected");
		}
	}
}
```

Binding is usually cleaner when the structure is already present in HTML and you only need to fill in values. The two approaches work well together, but binding should usually be the default because it keeps the page view and the PHP more loosely coupled.

Example of binding:

```php
use GT\DomTemplate\Binder;
use GT\Database\Database;

function go(Binder $binder, Database $db):void {
	$row = $db->fetch("currentEntity");
	$binder->bindData($row);
}
```

In the above two examples, notice how when using the Binder, the PHP code doesn't necessarily need to know anything about the page structure, whereas when using the HTMLDocument directly, the PHP is more tightly coupled to the structure of the HTML.

## Typical DOM work

When using `HTMLDocument` in WebEngine, the most common operations fall into four groups:

- finding the elements we need
- changing text, attributes, or classes
- creating or moving nodes
- inspecting relationships such as parents, children, and nearest matches

The API is intentionally close to the browser DOM, so methods such as `querySelector()`, `querySelectorAll()`, `closest()`, `createElement()`, `appendChild()`, `before()`, `after()`, and `replaceWith()` work in familiar ways.

### Finding elements

Selector-based traversal is usually the starting point:

```php
use GT\Dom\HTMLDocument;

function go(HTMLDocument $document):void {
	$title = $document->querySelector("main h1");
	$buttons = $document->querySelectorAll("form[action] button");

	$title?->classList->add("is-ready");

	foreach($buttons as $button) {
		$button->disabled = false;
	}
}
```

`querySelector()` returns the first matching element or `null`. `querySelectorAll()` returns a `NodeList` of all matches. In PHP.GT/Dom, that list is static, so if you later add matching elements, the original list does not update itself.

Read more in the main DOM docs: https://www.php.gt/docs/Dom/Document-traversal/

### Changing text, attributes, and classes

Once we have the right element, the next step is usually to adjust content or element state.

```php
use GT\Dom\HTMLDocument;

function go(HTMLDocument $document):void {
	$document->querySelector(".customer-name")->innerText = "Cody";
	$document->querySelector(".customer-email")->textContent = "cody@example.com";

	$profileLink = $document->querySelector("a.profile-link");
	$profileLink->href = "/user/cody";
	$profileLink->setAttribute("data-user-id", "42");

	$status = $document->querySelector(".status");
	$status->classList->remove("is-offline");
	$status->classList->add("is-online");
}
```

`innerText` is usually the most natural choice for visible text in HTML. Properties such as `href`, `src`, `value`, `hidden`, `title`, and `tabIndex` can also be manipulated directly, and `classList` gives a clean interface for adding, removing, replacing, and toggling classes.

Read more in the main DOM docs: https://www.php.gt/docs/Dom/Working-with-HTML-specific-helpers/

### Creating and inserting elements

Direct DOM work becomes especially useful when the page structure itself has to change.

```php
use GT\Dom\HTMLDocument;

function go(HTMLDocument $document):void {
	$list = $document->createElement("ul");

	foreach(["Draft", "Review", "Published"] as $label) {
		$item = $document->createElement("li");
		$item->innerText = $label;
		$list->appendChild($item);
	}

	$panel = $document->querySelector("#status-panel");
	$panel?->appendChild($list);
}
```

The same approach works for adding banners, wrapping existing content, inserting separators, or replacing one structure with another. Because the page is a real document tree, those structural changes stay explicit and local.

### Navigating relationships

DOM work is not only about selectors from the root document. Often the useful move is relative navigation from an element we already have:

```php
use GT\Dom\HTMLDocument;

function go(HTMLDocument $document):void {
	$error = $document->querySelector(".field-error");
	$group = $error?->closest(".form-group");
	$group?->classList->add("has-error");

	$notice = $document->querySelector(".notice");
	$notice?->before($document->createElement("hr"));
}
```

Properties such as `parentElement`, `children`, `nextElementSibling`, and methods such as `closest()` make it possible to express document-local logic without repeatedly searching the whole page.

## Practical guidance

Prefer binding for routine content output where the HTML structure already exists and only the values change. Reach for direct DOM manipulation when:

- the page structure must be inserted, removed, or rearranged
- one element's state depends on another element's location or relationship
- repeated binding keys would be more awkward than just editing the relevant nodes directly
- the behaviour is naturally expressed as document operations rather than data mapping

If the PHP keeps reaching deep into many unrelated parts of the page, that is usually a sign the view structure should be improved, or that some of the work should move back into [[binding data to the DOM]], [[custom HTML components]], or [[page partials]].

For deeper DOM coverage, the best entry points in the main docs are:

- https://www.php.gt/docs/Dom/Home/
- https://www.php.gt/docs/Dom/Document-traversal/
- https://www.php.gt/docs/Dom/Working-with-HTML-specific-helpers/
- https://www.php.gt/docs/Dom/WebEngine-and-DomTemplate/

*****

See how [[binding data to the DOM]] can keep dynamic pages clean and maintainable, or move on to work with [[user input]].


WebEngine avoids direct use of `$_GET`, `$_POST`, and `$_FILES` because raw superglobals make it hard to see where request data is being read or changed.

Instead, request input is wrapped in the `Input` service. The underlying package is documented in more detail at https://www.php.gt/docs/Input/.

## Reading input

The `Input` class is available from the Service Container, so we can just request it as a `go` or `do` parameter when we need it.

```php
use GT\Input\Input;

function go(Input $input):void {
	$name = $input->getString("name") ?? "Anon";
}
```

Input can come from the query string, the request body, or uploaded files.

## Handling actions

WebEngine maps submitted actions to `do_*` functions. If a form sends `do=save-profile`, the matching page logic can handle it in `do_save_profile()`.

That helps keep page behaviour explicit. Rather than one large request handler branching depending on user input, each "do" action can have its own named function.

Example HTML:

```html
<form method="post">
	<label>
		<span>Your name</span>
		<input name="name" required />
	</label>
	<label>
		<span>Message</span>
		<textarea name="message" required></textarea>
	</label>
	
	<button name="do" value="send-message">Send!</button>
</form>
```

Example PHP:

```php
use GT\Input\Input;

function do_send_message(Input $input, Emailer $emailer):void {
	$emailer->send(
		$input->getString("name"),
		$input->getString("message"),
	);
}
```

## Validation and normalisation

Validation usually belongs close to the page behaviour at first, because that is where the request rules are easiest to see. As those rules grow, they can be moved into dedicated classes or reused through validation helpers.

Normalisation is the same idea. If the page needs to trim, cast, or reshape some user input before passing it into the rest of the application, do that deliberately and as early as possible.

For server-side validation driven from the HTML form itself, it is also worth looking at DomValidation: https://www.php.gt/docs/DomValidation/

******

Other concepts adjacent to user input are [[cookies]] and [[sessions]].


Cookies are small values stored by the browser and sent back with later requests. They are useful for lightweight browser-side state such as preferences, one-off identifiers, and the session cookie used by server-side sessions.

In WebEngine, cookie handling is wrapped rather than spread through direct calls to `$_COOKIE` and `setcookie()`. The dedicated cookie package is documented at https://www.php.gt/docs/Cookie/.

## Working with cookies in WebEngine

The cookie abstraction makes it clearer when cookies are being read, set, or removed. From application code, that means cookie use can be kept explicit rather than handled in global state.

At a high level, cookie work usually falls into three jobs:

- reading a value that came from the browser
- setting a value that should be sent back in the response
- deleting a cookie that is no longer needed

## Common uses

Good uses for cookies include:

- user preferences such as theme choice
- remembered UI state
- non-sensitive identifiers
- the session cookie that links a browser to server-side session storage (handled automatically)

> [!WARNING]
> Never store sensitive application data in a cookie - use [[sessions]] instead, so sensitive information never leaves the server.

## Security

When setting cookies, think about expiry, path, scope, and whether the cookie should only be sent over HTTPS. Those are ordinary HTTP concerns, but they have a direct effect on how safely the browser handles the value.

## Cookie banners

In some countries, privacy law has led to widespread use of cookie banners. It is worth remembering that the real issue is not the existence of cookies as a browser feature, but how tracking technology is used.

Adding a banner does not make a privacy-invasive design harmless. In fact, constant banner prompts often train users to click through without reading. A more useful approach is to avoid unnecessary tracking in the first place and make sure the technologies used by the site match the privacy policy you are asking users to trust.

*****

Cookies are the mechanism for remembering user [[sessions]].


Sessions let the server remember short-lived information about one visitor between requests. That is different from a cookie, which is stored in the browser, and different again from one-off form input, which only exists for the current request.

The dedicated session package is documented at https://www.php.gt/docs/Session/.

## How WebEngine uses sessions

WebEngine sets up the session during the request lifecycle and places it in the service container. That means page logic and application code can request the session object directly when needed, rather than reaching into the superglobal `$_SESSION`.

The session can be accessed like any other dependency within the [[service container]].

## Common patterns

Typical session uses include:

- authentication state
- flash messages after redirects
- multi-step workflows

These are all cases where the browser needs to move from one request to the next while the server still remembers a little context.

Example storing the user's name in the session:

```php
use GT\DomTemplate\Binder;
use GT\Session\Session;
use GT\Input\Input;

// Called on page request, if there's a name in the session, bind it to the page.
function go(Session $session, Binder $binder):void {
	if($name = $session->getString("name")) {
		$binder->bindKeyValue("name", $name);
	}
}

// Called when the user submits the form containing their name.
function do_set_name(Session $session, Input $input):void {
	$session->set("name", $input->getString("name"));
}
```

## Storage and configuration

Session behaviour is configured through the normal WebEngine config files. The default setup is suitable for local development, but other handlers can be used too, including Redis-backed storage where that makes sense for deployment.

The session docs cover storage handlers, flash messages, and session stores in more detail:

- https://www.php.gt/docs/Session/Storage-handlers/
- https://www.php.gt/docs/Session/Flash-messages/

*****

Now object-oriented methods are available for accessing cookies, sessions and user input, we can learn about [[protected globals]].


One of the easiest ways for a PHP application to become difficult to follow is for request data to be read straight from superglobals throughout the codebase.

WebEngine uses protected globals to make that problem obvious during development. The separate package is documented at https://www.php.gt/docs/ProtectedGlobal/.

## Protected global variables in WebEngine

During start-up, WebEngine protects request-related globals such as:

- `$_GET`
- `$_POST`
- `$_FILES`
- `$_COOKIE`
- `$_SERVER`

Instead of encouraging direct access to those arrays, WebEngine exposes object-oriented alternatives such as `Input`, `Request`, `Session`, `Cookie` and `ServerInfo`.

## Encapsulation

Encapsulation means a part of the code only receives the data and behaviour it actually needs. Instead of every function being able to inspect the whole request, dependencies are passed in deliberately.

That improves testability because a class can be exercised with a small set of known inputs. It also improves readability because the function signature always shows what the code depends on.

## When global state is still necessary

Not all global state disappears. Environment variables still exist. PHP runtime behaviour still exists. Some third-party libraries may still assume raw superglobals are available.

When that happens, the answer is usually to whitelist only what is needed or to reconstruct the required input in one explicit place rather than letting it leak through the application.

*****

In the next section we will learn how to build [[API responses]].


WebEngine can serve structured responses as well as HTML pages. That means one application can provide normal pages for the browser and API endpoints for background requests or other consumers.

## HTML pages vs API endpoints

The important difference is not that the application has changed, but that the response type has changed. HTML routes build a document for the browser. API routes build structured data, usually JSON.

WebEngine keeps those routes within the same overall routing model, so the project does not need a completely different way of thinking about requests just because one endpoint returns data instead of a page.

Compare API logic to page logic:

```php
use GT\Json\Schema\JSONDocument;

function go(JSONDocument $document):void {
	$document->set("name.first", "Ada");
	$document->set("name.last", "Lovelace");
}
```

Instead of HTML, API views can be built up completely dynamically from PHP (using the JSONDocument), or it can be based on a `.jsonschema` file to provide defaults and inbuilt schema validation:

```json
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"oneOf": [
		{
			"$ref": "#/$defs/request"
		},
		{
			"$ref": "#/$defs/response"
		}
	],
	"$defs": {
		"request": {
		},
		"response": {
			"type": "object",
			"required": [
				"name"
			],
			"properties": {
				"name": {
					"type": "object",
					"required": [
						"first",
						"last"
					],
					
					"properties": {
						"first": {
							"type": "string"	
						},
						"last": {
							"type": "string"
						}						
					}
				}
			}
		}
	}
}
```

Unlike with [[page views]], API views don't require a view model - the JSON is optional, allowing an API response to be completely built dynamically in PHP. The JSON is there for when it helps with scalability and maintainability.

## What API logic looks like

API logic feels very similar to page logic. It still receives the request, can still use the same service container, and can still call the same application classes.

The main difference is the view model. HTML responses work with an `HTMLDocument`. API responses usually work with a `JSONDocument`, which is part of the JSON package documented at https://www.php.gt/docs/Json/Home/.

For many page interactions, there is no need to build a separate API endpoint at all. A server-rendered HTML application can still achieve a more fluid browser experience without switching every background interaction to a JSON API. That topic comes later in [[fluid user experience]].

*****

Next up, let's learn about how WebEngine handles [[configuration]].


Configuration shapes the application's behaviour without changing the source code. Database credentials, logging behaviour, session setup, routing defaults, and deployment-specific values are all examples of configuration rather than application logic.

The configuration package is documented in more detail at https://www.php.gt/docs/Config/.

## How WebEngine loads config

WebEngine starts with its own default config and then layers the project's own config files on top. Environment-specific overrides can then refine those values again.

At a high level the load order is:

1. WebEngine defaults (`vendor/phpgt/webengine/config.default.ini`)
2. project `config.ini`
3. environment-specific config files such as development or production overrides, such as `config.dev.ini` or `config.production.ini`
4. environment variables

That gives us a predictable starting point while still letting each environment change only the values it actually needs to change.

See the [[configuration reference]] page for a full list of every default value in a WebEngine application.

## Important configuration areas

The most important config areas early on are usually:

- application settings such as namespace and directories
- routing behaviour
- session settings
- database connection settings
- logging
- security-related values

As the project grows, these settings make it possible to change deployment details without changing page logic.

## Accessing config in application code

Configuration reaches page logic and services through the normal [[service container]]. That means a page or class can receive the full config object or, better still, the specific config section it actually needs.

```php
use GT\Config\Config;

function go(Config $config, ExampleRepository $exampleRepository, PaymentProvider $payment):void {
	// Pass specific config values to an object:
	$exampleRepository->connect(
		$config->getString("database.host"),
		$config->getInt("database.port"),
	);
	
	// Pass a whole section of config to an object:
	$paymentProvider->setup($config->getSection("paymentApi"));
}
```

Passing focused configuration into application classes usually keeps those classes easier to understand. It also makes it clearer which parts of the system are responsible for secrets, credentials, and other environment-specific values.

*****

In the next section we will connect to [[databases]].


Most WebEngine applications eventually move from static content to persistent state. A to-do list needs somewhere to store items. An address book needs records that survive page refreshes. User accounts need data that belongs to one person and is still there tomorrow.

That is where the database layer becomes part of the normal application path. The lower-level database package is documented in full at https://www.php.gt/docs/Database/.

## Connecting to a database

WebEngine reads database settings from configuration and constructs the database service for you. That means page logic and application classes can request the database dependency without having to build the connection manually first.

The main settings live in the `[database]` section of `config.ini`, where you choose the driver and connection details. SQLite, MySQL, and other supported drivers all use the same basic approach: WebEngine reads the config, creates the database service, and makes it available through the service container.

## Organising SQL and queries

SQL is easier to maintain when it lives outside page logic. Rather than scattering query strings through PHP files, WebEngine projects usually keep them in the `query/` directory.

The database package calls these organised sets of queries "query collections". A named query can then be called from PHP by its path-like name rather than by embedding the SQL directly into the page handler.

For example:

```text
query/user/getById.sql
```

Can be called like this:

```php
use Gt\Database\Database;

function go(Database $database):void {
	$row = $database->fetch("user/getById", 123);
}
```

The `getById` query can be called from PHP without the page needing to know the full SQL string. That keeps the PHP focused on the application's request state, while the SQL remains focused on the data manipulation.

The dedicated docs for query collections are here:

- https://www.php.gt/docs/Database/Query-collections/
- https://www.php.gt/docs/Database/Examples/

### Query Collections

To further encapsulate the database access for highly maintainable code, the individual directories that contain the queries are called _Query Collections_, and can be passed to [[application classes]] in isolation, forcing an application class to only have access to one Query Collection. This makes the [[Repository-Entity pattern]] very powerful. For example:

```php
function go(Database $database):void {
	$userRepository = new UserRepository($database->queryCollection("user"));
	$userRepository->checkCredentials(...);
}
```

In the above example, the `UserRepository` class is being constructed with access to only the `user` QueryCollection. The Query Collection behaves just as if it's a full database collection, but queries from other collections are not accessible. Imagine a service class for `Shipping` and a service class for `Payment` - the `Shipping` class shouldn't have access to all the queries across the whole database like the `query/payment` queries, so it's safer to pass the Shipping service only the `query/shipping` query collection. 

## Using database code from the app

Page logic should normally call an application class or service rather than mixing raw query work everywhere. That way the page handler can stay focused on the request and the response, while the application class can own the data-loading rules and result shaping.

That also gives us a clearer place to decide whether the page should receive:

- raw rows
- a small data object
- a domain entity
- a list already prepared for binding

For more information on making database behaviour strongly typed and reusable, see the [[Repository-Entity pattern]].

## Using the SQL Builder

As a project grows, some queries may be easier to express as PHP classes rather than plain SQL files. PHP.GT/SqlBuilder exists for that job and is documented at https://www.php.gt/docs/SqlBuilder/.

Query classes can extend other query classes, which is useful when several related queries share common clauses or conditions. That said, SQL files are still often the clearest starting point. Use the builder when the query genuinely benefits from composition, not simply because it is available.

Example:

`query/Product.php`

```php
namespace App\Query;

use GT\SqlBuilder\SelectBuilder;

class User {
	// The baseline get query for all other user getBy*:
	private function get():SelectBuilder {
		return new SelectBuilder()
			->select("id", "name", "email")
			->from("user");		
	}
	
	// getById extends the baseline get with just the modifications it needs:
	public function getById():SelectBuilder {
		return $this->get()
			->where("id = ?")
			->limit(1);
	}
}
```

Then call it in page logic or an application class like this:

```php
use GT\Database\Database;

function go(Database $database):void {
	$row = $database->fetch("user/getById", 123);
}
```

The default namespace for PHP query classes is `App\Query`, so a file such as `query/Product.php` can be resolved automatically. Query methods may return a SQL string, a `Stringable` object, or a `phpgt/sqlbuilder` builder.

*****

See how everything is loaded on demand in the [[service container]].


The service container is the part of WebEngine that constructs and shares dependencies for the current request. Instead of manually building every object in page logic, we can ask for the service we need and let the container provide it.

The standalone service container package is documented in more detail at https://www.php.gt/docs/ServiceContainer/.

Lazy loading is an important part of this. A service does not need to be constructed until something actually asks for it. That keeps the request lighter, especially when many pages only use a small subset of the available services.

## Default Service Loader

WebEngine's default service loader provides the services that most pages are likely to need, including:

- config
- request and response state
- input and URI data
- database-related services
- binding-related services for the HTML document

This is how a page logic function can simply ask for something like `Input`, `Session`, or `Database` and expect it to be there already.

## Project-specific service loader

The default service loader covers the framework's normal wiring, but an application can also provide its own service loader class. That is where project-specific services can be registered, to make them available across all page logic functions.

The container keeps a single instance of each service for the request. If two different parts of the code ask for the same dependency, they receive the same shared object rather than two instances of the same class.

The default location for the project's service loader is `class/ServiceLoader.php`, but can be moved elsewhere in the [[configuration]]. An example class:

```php
namespace App;

use GT\WebEngine\Service\DefaultServiceLoader;
use GT\Database\Database;
use GT\Session\Session;

class ServiceLoader extends DefaultServiceLoader {
	// The return type of the function will be used by the loader to pick
	// which function provides each type of object.
	public function loadUserRepository():UserRepository {
		// Any dependencies can be loaded from the container:
		$database = $this->container->get(Database::class);
		$session = $this->container->get(Session::class);
		
		// Then the new object can be constructed and returned accordingly:
		return new UserRepository(
			$database->queryCollection("user"),
			$session->getStore("user", true),
		);
	}
}
```

## Good uses for the container

Good uses include:

- object instances that are linked to the URI
- shared infrastructure services
- helpers built from configuration
- repositories, factories, and other application-level services

These are exactly the kinds of things that page logic should not have to construct repeatedly by hand.

### Object instances linked to a URI

A common technique for using the Service Container is providing a pre-constructed object of [[application classes]] that's linked to the current URI or state. For example, in a shop website that encodes the shop item's slug in the URI, rather than constructing the `Product` class manually in the page logic, it could request the `Product` as a `go` function parameter, allowing the service loader to construct the product from the application's known state:

Example URI: `/shop/computers/lenovo/thinkpad-x1`

Example page logic:

`page/shop/@category/@brand/@productSlug.php`:

```php
// The Product type is nullable, meaning that the current URI might not match a Product in the database.
function go(Binder $binder, ?Product $product):void {
	if(!$product) {
		// Throw 404 if there's no matching product from the Service Loader.
		throw new HttpNotFound();
	}
	
	// If the product is found, it can be bound to the page.
	$binder->bindData($product);
}
```

Example service loader:

```php
use App\Shop\Product;

class ServiceLoader extends DefaultServiceLoader {
	// The return type is nullable, meaning there might not always be a matching object.
	function loadProductFromUri():?Product {
		$dynamicPath = $this->container->get(DynamicPath::class);
		$productRepository = $this->container->get(ProductRepository::class);
		
		return $productRepository->getBySlug($dynamicPath->get("productSlug"));
	}
}
```

The code example above shows how a commonly-used object can be pre-constructed from the service loader, according to application state, to prevent repetative code throughout the page logic functions. 

## Pitfalls

The container should not become a vague global registry for everything. If arbitrary state is hidden in the container and fetched from anywhere, we lose the clarity that dependency injection is meant to give us.

Prefer services with clear responsibilities and explicit type-hinted dependencies.

*****

Now we know how to load services in our page logic, learn how and where to build [[application classes]].


Page logic handles one request. Application classes handle the application's behaviour in a reusable way.

That distinction is worth keeping clear early. If a page needs to load a user, validate some input, save a record, or calculate a result, the page file should usually pass that work into an application class rather than own the whole process itself.

Rule of thumb: Page logic should do as little as possible, deferring work to application classes as soon as possible.

## Organising classes of an application

WebEngine is designed to hand control over to your own application code as early as possible. The framework deals with the request, routing, page setup, and dependency wiring, then your page logic should pass the real work into ordinary PHP classes wherever possible.

That design is deliberate. It means the important behaviour of the project can live in classes that are not tightly bound to one page, one URL, or even one framework. Those classes can be tested in isolation, reused across different pages, and refactored with the normal benefits of object-oriented code.

In a standard project, those classes are autoloaded by Composer from the application's main namespace and PSR-4 root. By default that means the `App\` namespace maps to the `class/` directory, though both are configurable.

An application class can take many forms. It might be:

- a small data transfer object with almost no behaviour
- a service class that performs one business action
- a repository that loads and builds richer objects from the database
- a value object that gives a small concept a clear type and API

The important part is not the label - what's important is that the page hands off responsibility quickly, so the application's behaviour lives in classes with focused responsibilities.

Even the simplest systems benefit from this. For example, a small greeter class can keep the page entry point almost trivial:

`class/GreetingService.php`

```php
namespace App;

class GreetingService {
	public function forName(string $name):string {
		return "Hello, $name";
	}
}
```

Assuming the `GreetingService` is constructed in the [[service container]], then the page logic only has to orchestrate:

```php
use GT\DomTemplate\Binder;
use GT\Input\Input;
use App\GreetingService;

function go(Binder $binder, Input $input, GreetingService $greetingService):void {
	$name = $input->getString("name") ?: "guest";
	$binder->bindKeyValue("greeting", $greetingService->forName($name));
}
```

That is the basic WebEngine shape: the page understands the web request, the application class understands the behaviour, and the view receives the final data.

## Common types of classes

Common classes in a WebEngine application include:

- services that coordinate useful work
- use-case classes that perform one application action
- domain entities that represent application data with behaviour
- repositories or data access helpers
- value objects for small typed concepts

Not every project needs all of these, but they are common shapes that help the codebase grow cleanly.

## How Page Logic should use them

Page logic should stay thin. Let the page handler read the request, call the right class, and bind the final output data into the document.

That keeps the boundary clear. The page knows about the web request. The application class knows about the business rule. The view knows about presentation.

## Keeping code framework-agnostic

As far as practical, application classes should not be tightly coupled to WebEngine. They should not need to know about the page lifecycle just to do their job.

That makes them easier to test and easier to reuse. It also keeps the framework at the edge of the application rather than at the centre of every class.

*****

Next we'll learn about the client-side [[build system]].


WebEngine deals with the server-side part of the application, but most real projects also have client-side files that need preparing before the browser can use them.

That is the job of the build system. The lower-level build package is documented in full at https://www.php.gt/docs/Build/.

The `www/` directory is the public web root, so anything that should be served directly by the web server needs to end up there. Source files often live elsewhere, which is why copying and compiling are part of the normal workflow.

## What should go in the `www` directory?

As few files as possible should be stored within `www` as part of the project. The majority of the client side or static files should come from elsewhere, such as the `asset` or `style` directories.

Only files such as `manifest.json`, `robots.txt`, `favicon.ico` should be stored directly within `www`. Everything else should be automatically copied/compiled there by the build system.

## Sensible defaults, extensible to your needs

WebEngine ships with a default build configuration so a new project can usually start with sensible asset handling immediately.

The framework default file is `vendor/phpgt/webengine/build.default.ini`, and it contains tasks for:

- bundling `script/**/*.es6` into `www/script.js` with `esbuild`
- copying plain `script/**/*.js` files into `www/script/`
- compiling `style/**/*.scss` into `www/style.css` with `sass`
- copying plain `style/**/*.css` files into `www/style/`
- syncing everything under `asset/` into `www/asset/`

The default file looks like this:

```ini
[script/**/*.es6]
require=node_modules/.bin/esbuild
execute=./node_modules/.bin/esbuild script/script.es6 --bundle --sourcemap --outfile=www/script.js --loader:.es6=js --target=chrome105,firefox105,edge105,safari15

[script/**/*.js]
require=vendor/bin/sync
execute=vendor/bin/sync --pattern "**/*.js" script www/script

[style/**/*.scss]
require=node_modules/.bin/sass
execute=./node_modules/.bin/sass ./style/style.scss www/style.css --source-map --embed-sources --embed-source-map

[style/**/*.css]
require=vendor/bin/sync
execute=vendor/bin/sync --pattern "**/*.css" style www/style

[asset/**/*]
require=vendor/bin/sync
execute=vendor/bin/sync asset/ www/asset --delete --symlink
```

When we run `gt build` in a WebEngine project, `gt` passes that file to the lower-level Build package as a default configuration. If the project does not have its own `build.ini`, those framework defaults are used.

If the project does need different behaviour, create a `build.ini` in the project root. That project file becomes the active configuration and takes precedence over the WebEngine default. In other words, this is an override, merging the application's sections over the defaults.

For example, if our application wants a different Sass entry point and output path, the project's `build.ini` could contain:

```ini
[style/**/*.scss]
name=Compile application Sass
require=node_modules/.bin/sass
execute=./node_modules/.bin/sass ./style/app.scss ./www/app.css --source-map
```

At that point the project is choosing its own build behaviour for the whole file, so it is normal to copy across any of the default sections we still want to keep and then edit the ones that differ.

## Bring your own compilers

WebEngine does not bundle front-end compilers or package managers itself. Tools such as `esbuild`, `sass`, and any other browser-side dependencies should live in the project's own `package.json` and be installed with the Node ecosystem tool you prefer.

In practice that usually means `npm`, but any compatible workflow such as `pnpm` or `yarn` is fine as long as the commands referenced by `build.ini` are available where the build tasks expect them.

That separation is intentional. WebEngine defines how build tasks are run, but the application still owns which client-side tools it depends on and which versions are installed.

When a new project is created with `gt create`, the scaffold can install the default Node-side tools automatically with `npm install` if npm is available on the system. After that point, the project maintains those dependencies in the normal way through its own `package.json`.

## What the build system handles

The build system is concerned with:

- client-side assets
- stylesheets and preprocessors
- JavaScript compilation or transformation
- static asset copying

It does not try to replace every client-side tool. Instead, it provides a consistent way to run those tools from the project.

## Recommended structure for scripts and stylesheets

The framework defaults assume a conventional source layout:

- `asset/` for images, fonts, and other static resources
- `script/` for JavaScript and ES module source files
- `style/` for CSS and Sass source files

If a project is using the WebEngine defaults unchanged, the main entry points for compiled client-side code are:

- `script/script.es6` for bundled JavaScript
- `style/style.scss` for compiled Sass

Those entry files are expected to manage their own imports or includes. In other words, the build task points at one main script and one main stylesheet, and those files pull in the rest of the front-end code as needed.

The default outputs are:

- `www/script.js` from `script/script.es6`
- `www/style.css` from `style/style.scss`

For simpler projects, plain `.js` and `.css` files can also live directly under `script/` and `style/`. The default build config copies those files into `www/script/` and `www/style/` without bundling or preprocessing, which is useful for one-off files or projects that do not need a heavier toolchain.

That gives a sensible split:

- use `script/script.es6` and `style/style.scss` when the front-end code benefits from bundling or preprocessing
- use plain `.js` and `.css` files when a file can stay simple and standalone

## Transparent building

`gt run` and `gt build` work together. During local development, `gt run` can keep the build watcher running in the background so asset preparation feels transparent.

When you want to run the build process on its own, `gt build` is the direct command. One-off builds are useful in CI or deployment. Watch mode is useful while editing source files locally.

*****

The build system makes more sense once a page starts reacting to user input, so the next tutorial is [[Hello You]].


The [[Hello World tutorial]] is useful for orientation, but it doesn't show much of the real-world WebEngine workflow. This tutorial turns that first static page into a personalised response so we can see the full round trip from browser to PHP and back again.

## What we'll build

In this tutorial we will add:

- a form
- page logic
- simple input handling
- basic DOM binding

By the end, the page will greet the user by the name they submit.

## Build steps

Start by adding a form to the page view. The HTML can stay simple:

```html
<!doctype html>
<h1>Hello, <span data-bind:text="name">you</span>!</h1>

<form>
	<label>
		<span>Your name:</span>
		<input name="name" required />
	</label>
	
	<button name="do" value="greet">Greet!</button>
</form>
```

This HTML has an `h1` for outputting the greeting. Notice that the default value can be written directly into the HTML, so before the user has told us their name, we can still output the default "Hello, you!" message. Also notice the `data-bind:text` attribute. This means that PHP will be able to change the text content of the element by passing it a matching `name` value.

In the form, there's a label for the name input, and a button to perform the greeting. The button has a `name` attribute with the value `do`, which triggers a significant feature of WebEngine: _do buttons_ can trigger the execution of _do functions_ - see below. 

Alongside the `index.html`, create an `index.php` with the do function:

```php
use GT\Input\Input;
use GT\DomTemplate\Binder;

function do_greet(Input $input, Binder $binder):void {
	$name = $input->getString("name");
	$document->bindKeyValue("name", $name);
}
```

When the request contains a key of `do`, a matching function will be executed. In this case, the button's value is `greet`, so the `do_greet` function will execute, if it exists. The `Input` and `Binder` classes are all we need. In the example above, the name is extracted from the user input and provided directly to the binder. It's done as two steps to help explain what's happening, but the PHP could also be written like this:

```php
function do_greet(Input $input, Binder $binder):void {
	$document->bindData($input);
}
```

The Binder has different methods for binding data to the document - with `bindData` it's possible to pass any structured key-value-pair. Because there's a `name` key within the user input, the Input object can be used directly. Either way of binding is fine - both are shown here for teaching purposes.

The page now has a complete request loop:

1. the browser submits the form
2. page logic's do function is read
3. the page logic reads the input
3. the document binds the value
4. the browser receives a personalised page

## Taking it further

From here it is natural to ask how styling, richer behaviour, or animations could be added. That is the point where the build system, components, and later the fluid user experience tools begin to come in.

*****

For a more complete application, move on to the ubiquitous [[todo list tutorial]].


Almost every language or framework ends up with a to-do list tutorial somewhere. The reason is simple: it exercises just enough of the stack to be useful without becoming overwhelming.

Here, the to-do list introduces form handling, state, repeated output, and a little application structure.

## What we'll build

This version keeps persistence simple by storing the list in a local database using SQLite. That lets us focus on the WebEngine workflow without the complexities of adding a remote data source, but while being representative of a real world application.

The tutorial introduces:

- form handling
- database-backed state
- list rendering
- a small model represented by [[application classes]]

## Build stages

The order of the tutorial is:

1. add a form to create items
2. handle the button clicks
3. represent the list and items with application classes
4. persist the data with SQL
5. render the list back into the page

This is usually the point where the value of thin page logic becomes very clear, because the page needs to coordinate several actions while still staying readable.

### Step 1 - add a form to create items

In the `index.html`, let's mark up the layout of a repeating list of to-do items:

```html
<!doctype html>

<html lang="en">
<head>
	<meta charset="utf-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<title>To do list</title>
</head>
<body>

<h1>To do list</h1>
<p>What do you want to do?</p>

<ul>
	<li data-bind:class="status">
		<form method="post">
			<input type="hidden" name="id" data-bind:value="id" />
			
			<label>
				<input type="checkbox" name="completed" data-bind:checked="?completed" />
			</label>
			
			<label>
				<input name="title" required data-bind:value="title" autocomplete="off" />
			</label>
			
			<button name="do" value="save">Save</button>
			<button name="do" value="delete">Delete</button>
		</form>
	</li>
</ul>

</body>
</html>
```

Taking a look at this page in the browser looks fairly underwhelming, and of course there's no interactivity yet, but take note of all the elements and their attributes. It should be clear where data will be bound to the page when we hook it up to PHP. Let's go over some of the points in the HTML: 

The `<li>` element has the following attrubute: `data-bind:class="status"`. This means the element's `class` attribute will be set to the `status` of the item being bound. This is covered in [[Binding data to the DOM]].

The hidden input has its `value` attribute bound to the `id` of the item being bound, and the checkbox gets the `checked` attribute set to the item's `completed` property. The last thing being bound is the `title` input - the `value` attribute will be bound to the `title` of the item.

At the bottom of the form are two buttons, both with name attributes set to `do`. We'll go over those in more detail later.

### Step 1A - make it look good!

This isn't a CSS tutorial, so we'll just paste in the CSS to the `style/style.css` file. Feel free to read through the CSS and its comments, but we'll not cover the ins and outs of CSS here.

<details>
<summary>CSS file contents</summary>

```css
/** Here is where all the default palette variables are defined **/
:root {
	--pal-base: #3f51b5;
	--pal-base-strong: #2f3f9f;
	--pal-base-soft: #e7eafd;
	--pal-page-bg1: #eef2ff;
	--pal-page-bg2: #f7f9fc;

	--pal-surface: rgba(255, 255, 255, 0.82);
	--pal-surface-strong: #ffffff;
	--pal-border: rgba(63, 81, 181, 0.14);
	--pal-shadow: 0 18px 40px rgba(48, 63, 159, 0.14);
	--pal-shadow-soft: 0 8px 18px rgba(31, 41, 55, 0.08);

	--pal-text: color-mix(in srgb, black, var(--pal-base));
	--pal-text-muted: #667085;

	--pal-danger: #c62828;
	--pal-danger-soft: #fdecec;

	--radius-panel: 1.5rem;
	--radius-row: 1rem;
}

/** html and body set the basics, along with a gradient background on the page */
html {
	font-size: 20px;
	height: 100%;
}

body {
	height: 100%;
	margin: 0;
	font-family: sans-serif;
	color: var(--pal-text);
	background-image:
		radial-gradient(circle at top left, rgba(63, 81, 181, 0.18), transparent 28rem),
		radial-gradient(circle at bottom right, rgba(79, 195, 247, 0.16), transparent 24rem),
		linear-gradient(160deg, var(--pal-page-bg1), var(--pal-page-bg2) 45%, #ffffff);
	background-position: bottom;
}

h1, p {
	text-align: center;
}

h1 {
	margin: 0;
	margin-top: 2rem;
	font-size: clamp(2.4rem, 5vw, 3.6rem);
	font-weight: bold;
	color: var(--pal-text);
}

p {
	margin: 0.75rem auto 2rem;
	max-width: 24rem;
	font-size: 0.92rem;
	line-height: 1.6;
	color: var(--pal-text-muted);
}

button {
	/*
	All buttons should take on a consistent look and feel, but below each
	button has its own style applied.
	 */
	min-width: 4rem;
	padding: 0;
	margin-left: 0;
	border: 0;
	border-radius: 999px;
	font: inherit;
	font-size: 0.78rem;
	font-weight: 700;
	letter-spacing: 0.03em;
	cursor: pointer;
	align-items: center;
	justify-content: center;
	transition:
		transform 160ms ease,
		box-shadow 160ms ease,
		background-color 160ms ease,
		color 160ms ease;

	&:hover {
		transform: translateY(-1px);
	}

	&:active {
		transform: translateY(0);
	}

	&:focus-visible {
		outline: none;
		box-shadow: 0 0 0 4px rgba(63, 81, 181, 0.18);
	}

	/*
	The individual buttons can be identified by their value attributes.
	 */
	&[value=save] {
		background: linear-gradient(135deg, var(--pal-base), var(--pal-base-strong));
		color: white;
		box-shadow: 0 10px 22px rgba(63, 81, 181, 0.28);

		&:hover {
			box-shadow: 0 14px 28px rgba(63, 81, 181, 0.32);
		}
	}

	&[value=delete] {
		background-color: transparent;
		color: var(--pal-danger);

		&:hover {
			background-color: var(--pal-danger-soft);
		}
	}
}

/*
The ul represents the entire list. Note that the list includes the "new" to do
item at the bottom of the page, which is styled slightly differently.
 */
ul {
	max-width: 32rem;
	margin: 0 0.5rem;
	padding: 0.5rem;
	list-style-type: none;
	border: 1px solid rgba(255, 255, 255, 0.7);
	border-radius: var(--radius-panel);
	background-color: var(--pal-surface);
	backdrop-filter: blur(18px);
	box-shadow: var(--pal-shadow);

	li {
		border-radius: var(--radius-row);
		transition:
			transform 160ms ease,
			background-color 160ms ease,
			box-shadow 160ms ease;

		&:hover {
			background-color: rgba(63, 81, 181, 0.05);
		}

		button[value=save] {
			display: none;
		}

		button[value=delete] {
			display: none;
		}

		label {
			&:first-of-type {
				display: flex;
				justify-content: center;
				width: 2rem;
			}
		}

		/*
		Here's the definition for the "new" item, at the bottom of the list.
		We don't want to display the checkbox or the delete button (because there's no
		item to check or delete yet!)
		 */
		&.new {
			input[type=checkbox] {
				display: none;
			}

			input[name=title] {
				border: 1px solid rgba(63, 81, 181, 0.24);
				background-color: color-mix(in srgb, var(--pal-base), white 95%);
				box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.9);
			}

			button[value=save] {
				display: inline-flex;
			}

			button[value=delete] {
				display: none;
			}

			form:focus-within {
				button[value=delete] {
					display: none;
				}
			}
		}

		/*
		The final alteration is when a to do item is marked as completed, we should
		draw it in a different colour and strike out the text.
		 */
		&.completed {
			background-color: rgba(148, 163, 184, 0.08);

			input[name=title] {
				text-decoration: line-through;
				color: color-mix(in srgb, var(--pal-text-muted), white 10%);
			}
		}


	}
}

/*
Here we're breaking out of the nesting to define some form styling that's
applied to each item in the list.
 */
form {
	display: flex;
	justify-content: stretch;
	align-items: stretch;
	gap: 0.5rem;
	padding: 0.5rem;
	accent-color: var(--pal-base);
	border-radius: var(--radius-row);
	transition:
		background-color 160ms ease,
		box-shadow 160ms ease,
		transform 160ms ease;

	&:has(input[name=title]:focus,button:focus) {
		background-color: rgba(255, 255, 255, 0.78);
		box-shadow: var(--pal-shadow-soft);
		transform: translateY(-1px);

		button[value=delete] {
			display: inline-flex;
		}
	}

	label:nth-of-type(1) {
		display: flex;
		align-items: center;
		justify-content: center;
		padding-left: 0.25rem;
	}

	label:nth-of-type(2) {
		flex-grow: 1;
	}

	input[type=checkbox] {
		width: 1.2rem;
		height: 1.2rem;
		cursor: pointer;
	}

	input[name=title] {
		box-sizing: border-box;
		width: 100%;
		padding: 0.85rem 1rem;
		font: inherit;
		font-size: 0.92rem;
		line-height: 1.3;
		color: var(--pal-text);
		border: 1px solid transparent;
		border-radius: 0.9rem;
		background-color: transparent;
		transition:
			border-color 160ms ease,
			background-color 160ms ease,
			box-shadow 160ms ease;

		&::placeholder {
			color: #94a3b8;
		}

		&:hover {
			background-color: rgba(255, 255, 255, 0.7);
		}

		&:focus {
			outline: none;
			border-color: rgba(63, 81, 181, 0.45);
			background-color: var(--pal-surface-strong);
			box-shadow:
				0 0 0 4px rgba(63, 81, 181, 0.12),
				0 6px 18px rgba(63, 81, 181, 0.12);
		}
	}
}

/*
The styling is complete at this point, but so far everything's been designed
to display on a small screen - here we can add some extra styles for when larger
screens are available. This is referred to as mobile first design.
A media query only applies the styles within once a certain width is reached.
 */
@media(min-width: 42rem) {
	html {
		font-size: 24px;
	}
	h1 {
		margin-top: 4rem;
	}
	ul {
		margin: 0 auto;
		padding: 1rem;
	}
	form {
		gap: 1rem;
		padding: 1rem;
	}
	button {
		min-width: 5rem;
	}
}
```

</details>

Once the CSS file is in place, we can import it by adding the following line to our `<head>` element, straight after the `<title>`:

```html
<link rel="stylesheet" href="/style/style.css" />
```

And one last thing to do to add to the client-side responsiveness is automatically click the save button whenever a change is made to a to-do item. This prevents the user from tabbing out and forgetting to save.

Change the opening `<form>` tag to the following:

```html
<form method="post" onchange="this.querySelector('[value=save]').click()">
```

### Step 2: handle the button clicks

Inside `index.php`, we can add a function that's fired when the save button is pressed called `do_save`. Because the button in the HTML has a `name` attribute of `do`, and a `value` attribute of `save`, this function is invoked automatically by WebEngine whenever the user clicks the corresponding button.

```php
function do_save():void {
}
```

So, what needs to go inside the function?

Well, first we need to request the class dependencies from the [[service container]]. This is done by including the class names as parameters. We'll use our own class called `TodoList` to represent the list, the `Input` class to get the [[user input]] from the browser, and the `Response` class to reload the page.

Import these classes like this:

```php
use App\Todo\TodoList;
use GT\Input\Input;
use GT\Http\Response;

function do_save(TodoList $todoList, Input $input, Response $response):void {
}
```

Keep in mind that we haven't created the `TodoList` class yet, so refreshing the page now will cause an error.

The contents of the do function can be kept short and simple: if there's an ID supplied in the input, we shall update the existing record. If there's not an ID, we shall create a new record. After we're done, reload the page:

```php
function do_save(TodoList $todoList, Input $input, Response $response):void {
	if($id = $input->getString("id")) {
// If there's an ID, we shall update the existing record.
		$todoList->update(
			$id,
			$input->getString("title"),
			$input->getBool("completed")
		);
	}
	else {
// If there's not an ID, we shall create a new record.
		$todoList->create(
			$input->getString("title"),
		);
	}

	$response->reload();
}
```

The above code should be immediately readable by any developer, and the intentions of the code should be clear.

We can add the handler for the delete button too:

```php
function do_delete(TodoList $todoList, Input $input, Response $response):void {
	$todoList->delete($input->getString("id"));
	$response->reload();
}
```

### Step 3: represent the list and items with application classes

We're going to create two classes: `TodoList` and `TodoItem`. Their titles should explain what their responsibilities are.

Let's create the simpler of the two first, `TodoItem`. It will be a simple data-transfer-object, with public properties for `id`, `title` and `completed`, and a single function for getting its `status`. Create it at `class/Todo/TodoItem.php`:

```php
<?php
namespace App\Todo;

use GT\DomTemplate\BindGetter;

class TodoItem {
	public function __construct(
		public readonly string $id,
		public readonly string $title,
		public readonly bool $completed,
	) {}

	#[BindGetter]
	public function getStatus():string {
		if($this->id === "") {
			return "new";
		}
		if($this->completed) {
			return "completed";
		}

		return "";
	}
}
```

The three properties will automatically bind to the document because they're public, and the `getStatus` function has been attributed as a `BindGetter`, meaning the document can bind the `status` key and it'll call this function to get the status. This probably isn't necessary here, but it's worth showing as part of the complete tutorial.

Next, we'll implement the `TodoList` class. It'll remain as simple as possible, but will need to have a function for every operation we can perform on the list: `getAll` will return a list of `TodoItem` objects, `update` will update the title and completed status of an item, `create` will create a new item, and `delete` will delete an item.

All of these functions will defer the work to an SQL file within the query directory, and to let the code work with the `TodoItem` class from above, we'll have another function called `rowToToDoItem` that converts a database row to our `TodoItem` class. This is a common technique in the [[Repository-Entity pattern]].

`class/Todo/TodoList.php`:

```php
<?php
namespace App\Todo;

use Gt\Database\Database;
use Gt\Database\Result\Row;
use Gt\Ulid\Ulid;

class TodoList {
	public function __construct(
		private readonly Database $db,
	) {
	}

	/** @return array<TodoItem> */
	public function getAll():array {
		$todoItemArray = [];

		foreach($this->db->fetchAll("todo/retrieve") as $row) {
			array_push($todoItemArray, $this->rowToTodoItem($row));
		}

		return $todoItemArray;
	}

	public function update(string $id, string $title, ?bool $completed):void {
		$this->db->update("todo/update", $title, $completed ?? false, $id);
	}

	public function create(string $title):void {
		$id = new Ulid();
		$this->db->insert("todo/create", $title, $id);
	}

	public function delete(string $id):void {
		$this->db->delete("todo/delete", $id);
	}

	private function rowToToDoItem(?Row $row = null):?TodoItem {
		if(!$row) {
			return null;
		}

		return new TodoItem(
			$row->getString("id"),
			$row->getString("title"),
			$row->getBool("completed"),
		);
	}
}
```

The class is constructed with reference to the `Database` - but where are we constructing the class from? That's done by our [[Service container]], to make the `TodoList` class available anywhere in our page logic.

Create the `ServiceLoader` class at `class/ServiceLoader.php`:

```php
<?php
namespace App;

use App\Todo\TodoList;
use Gt\Database\Database;
use GT\WebEngine\Service\DefaultServiceLoader;

class ServiceLoader extends DefaultServiceLoader {
	public function loadTodoList():TodoList {
		return new TodoList(
			$this->container->get(Database::class)
		);
	}
}
```

That's all the application class coding done, but to see our application working, we need to render the list to the page.

### Step 4: persist the data with SQL

We're going to use an SQL database to persist the data. For simplicity, we'll use SQLite which stores the database as a single file in the project's root directory.

There will be only one table required: `todo`, and the table will have three fields: `id`, `title` and `completed` - just like our `TodoItem` class.

To create the table, we create a numbered file in the `query/_migration` directory. The point of a migration is so large projects can have all their database changes tracked over time. Even though we're just adding one, we'll do it anyway as it's a good habit to form.

`query/_migration/0001-todo.sql`:

```sql
create table todo
(
    id text constraint todo_pk primary key,
    title text not null,
    completed integer default 0 not null
);
```

Then run `gt migrate` in the terminal to set the database up. This command only has to be run once after a migration file has been added.

There are four database queries to write: `create`, `retrieve`, `update`, `delete`. The names are intentional - this is a simple [CRUD application](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete).

`query/todo/create.sql`:

```sql
insert into todo (title, id)
values (?, ?)
```

`query/todo/retrieve.sql`:

```sql
select
	id,
	title,
	completed
from
	todo
```

`query/todo/update.sql`:

```sql
update todo
set
	title = ?,
	completed = ?

where
	id = ?
```

`query/todo/delete.sql`:

```sql
delete from todo
where id = ?
```

### Step 5: render the list back into the page

With the above code in place, we have a database-driven to-do list... it just doesn't do anything yet! But there's only a few tweaks to the code needed now to complete everything.

Refresh the page now in the browser, and you'll see an empty to do list with no functionality. Let's change that.

The first thing we need is to mark the `<li>` element in the HTML with the `data-list` attribute. Adding this attribute tells PHP to extract the element from the page, so in our last bit of code we can provide the `Binder` with the `TodoList`, and for each item in the list, the `<li>` element will be cloned - automatically having all the bind attributes bound for us.

The changed line of HTML looks like this:

```html
<li data-list data-bind:class="status">
```

Now refreshing the page does something different: removes the item from the `<ul>` element, so the list is completely empty. That shows that the list binder is working - there should be no elements in the list - because we haven't told it to bind the list yet.

The final piece to complete this project is to output the list when the page renders. This is done in the `go` function of the `index.php`.

As before, we'll use the parameters of the `go` function to request the `TodoList`, the `Binder` and the `HTMLDocument` from the service loader. The `TodoList` already has all the functionality we need - the `getAll` function returns a list of `TodoItem` objects from the database. We'll call `getAll` and then push one extra item into the list, representing the "new" to do item at the bottom of the page.

Finally, we'll bind the list of items, and use the HTMLDocument to set the `autofocus` attribute of the "new" item, so the cursor is automatically always flashing in the new item's input.

Here's the go function:

```php
function go(TodoList $todoList, Binder $binder, HTMLDocument $document):void {
	$todoListItems = $todoList->getAll();
	array_push($todoListItems, new TodoItem("", "", false));
	$binder->bindList($todoListItems);
	$document->querySelector("li.new input[name='title']")->autofocus = true;
}
```

## Taking it further

Once the database-backed version works, it is worth asking what changes are required if the list is to be shared between multiple users. We'll cover these questions in the [[address book tutorial]] next.

If you want to approach the same tutorial with tests first, there's also a [[todo list TDD tutorial]].

*****

We'll build on the code introduced in the todo list to build a full multi-user database-driven application in the [[address book tutorial]]. There's also an extension of this tutorial that adds testing from the start in [[todo list TDD tutorial]].


The address book tutorial is where the project starts to feel more like a production application. It uses a real database, spans multiple pages, and benefits from a clearer application architecture.

## What we'll build

The application will include:

- a multi-page structure
- shared layout
- database-driven pages
- better layering between page logic and application classes
- stronger testing and deployment concerns

It also adds a lightweight idea of user ownership so different people can keep their own address books.

## Build steps

A sensible order is:

1. build the index page in HTML first
2. add the page for a single record
3. add create and edit flows
4. move data access and behaviour into application classes
5. connect the database
6. associate records with a simple username identity

By this stage the project starts to use most of the ideas in the earlier chapters together.

## Taking it further

Once the core address book works, natural next steps include stricter validation, stronger security, a better authentication system, and fuller test coverage.

If the simple username identifier becomes too limiting, it can later be replaced by a proper authentication mechanism rather than being baked into every part of the app from the start.

*****

When starting a new application with `gt create`, we can start with any of these tutorials or pick from other [[blueprints]].


Blueprints are starter projects for new WebEngine applications. They save setup time by giving us a project that already has some structure, layout, or example functionality in place.

## Blueprint directory

The list of official blueprints are available at https://www.php.gt/blueprints/ or in the terminal with the `gt` command.

Type `gt create` in a terminal, and after choosing a name for your new project, it will list out the official blueprints to start from. Choosing a blueprint by selecting its number will clone the blueprint project and set up any config for your instance of the project.

It's possible to specify the blueprint in a single command:

```bash
gt create my-app --blueprint blog
```

*****

Let's check out the [[application architecture]] page to build readable and maintainable projects.


The most minimal PHP.GT WebEngine application consists of the following source files:

```
.                     
├── page          
|   └── index.html
└── composer.json    
```

<details>
<summary>For context, here's an example large application's source files</summary>

```
.
├── data
├── api
│   └── v1
│       ├── example-endpoint.json
│       ├── example-endpoint.php
│       ├── user-auth.json
│       └── user-auth.php
├── asset
│   ├── logo.svg
│   └── pattern.png
├── class
│   ├── Input
│   │   ├── Captcha.php
│   │   ├── Search.php
│   │   └── Validation.php
│   ├── Model
│   │   ├── Category.php
│   │   ├── Item.php
│   │   ├── OutOfStockException.php
│   │   └── SpecialOffer.php
│   ├── Payment
│   │   ├── AbstractPayment.php
│   │   ├── CreditDebitPayment.php
│   │   └── PayPalPayment.php
│   ├── UI
│       ├── Error.php
│       ├── Formatter.php
│       └── Message.php
├── page
│   ├── _component
│   │   ├── cart-popup.html
│   │   ├── category-item.html
│   │   ├── checkout-listing.html
│   │   ├── out-of-stock.html
│   │   ├── payment-form.html
│   │   └── shop-item.html
│   ├── checkout
│   │   ├── index.html
│   │   ├── index.php
│   │   ├── payment.html
│   │   └── payment.php
│   ├── shop
│   │   ├── category
│   │   │   ├── _common.php
│   │   │   └── @category.html
│   │   ├── categories.html
│   │   ├── categories.php
│   │   ├── index.html
│   │   ├── index.php
│   │   ├── item.html
│   │   └── item.php
│   ├── _common.php
│   ├── _footer.html
│   ├── _header.html
│   ├── about.html
│   ├── contact.html
│   ├── contact.php
│   ├── index.html
│   ├── index.php
│   └── terms.html
├── query
│   ├── _migration
│   │   ├── 001-create-table-shop-item.sql
│   │   ├── 002-create-table-shop-category.sql
│   │   ├── 003-alter-table-shop-item--add-field-currency.sql
│   │   ├── 004-create-table-purchase.sql
│   │   └── 005-create-table-payment.sql
│   └── shop
│       ├── category
│       │   └── getAll.sql
│       └── item
│           ├── completePurchase.sql
│           ├── getById.sql
│           ├── getInCategory.sql
│           └── startPurchase.sql
├── script
│   ├── Async
│   │   ├── Updater.es6
│   │   └── UrlHistory.es6
│   ├── Input
│   │   ├── Dirty.es6
│   │   ├── Message.es6
│   │   └── Validate.es6
│   └── script.es6
├── style
│   ├── animation
│   │   ├── flash.scss
│   │   └── popup.scss
│   ├── base
│   │   ├── form.scss
│   │   ├── normalise.scss
│   │   ├── typography.scss
│   │   └── variables.scss
│   ├── component
│   │   ├── cart-popup.scss
│   │   ├── category-item.scss
│   │   ├── checkout-listing.scss
│   │   ├── out-of-stock.scss
│   │   ├── payment-form.scss
│   │   └── shop-item.scss
│   ├── page
│   │   └── checkout.scss
│   └── script.scss
├── build.ini
├── composer.json
├── config.ini
└── redirects.csv
```

</details>

## Model View Controller (MVC)

When describing software architecture of any framework, the topic of [MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) will always come up. MVC is a broad architectural pattern that describes three areas of responsibility that any software application should be split into:

1. Model: a model can be described as how the application stores data, and in what form. For example, a class that represents a record in a database can be classified as a "model" object. This would be the "Entity" in the [[Repository-Entity pattern]].
2. View: The view represents the output of an application. On the web, a view is is webpage, or the components that build up that page. In WebEngine, the view is represented by the [[page view]].
3. Controller: A controller is the logic commands that react to user input, bind models to the views, and generally execute the whole business logic of the application. In WebEngine, the controller is represented by the [[page logic]], and passes control to [[application classes]] as soon as possible.


File layout and execution flow affect maintainability from the very start of a project. In practice, architecture is not an academic concern here. It is simply the question of whether the next developer can find the right file, understand the request flow, and change the application without breaking unrelated things.

## Software Architecture Pyramid

Inspired heavily from [Robert Martin's "Clean Architecture"](https://www.safaribooksonline.com/library/view/clean-architecture-a/9780134494272/), The Software Architecture Pyramid is a client-server software architecture pattern in which layers of the application have strong boundaries with one-directional dependency trees.

The main aim of the Software Architecture Pyramid is to address the challenges faced by the MVC or multi-tier architecture patterns, such as tight coupling of dependencies and separations of concern between the different areas of an application.

This architecture pattern is designed so that business logic is not bound to the framework it runs upon. Layers of the pyramid should not be aware of the layers below. The outcome of this pattern is that all logic is abstracted away from a web request's execution path, instead inverting the path of control to the tip of the pyramid down.

![Software Architecture Pyramid. From bottom to top: Foundation, Base, Framework, Logic, Entity, Unit, View](https://camo.githubusercontent.com/1cc04b85c223821889a03cb72bf9ef097606c1413a2e1e8999efa1273bd60de3/68747470733a2f2f7777772e7068702e67742f61737365742f696d672f646f63732f707972616d69642e706e673f)

From the top to the bottom:

- View layer: The views of the application should not know about any of the code beneath. They should be written so that they could be easily plugged into any software framework - the less proprietary technologies the better.
- Unit layer: The topmost layer of logical code is the business logic and use cases of the application. It should be pluggable into another framework without any modification. Larger projects can store their units in separate repositories.
- Entity layer: holds objects that are core to the domain that you're programming for, such as code for Customer, Order, Vehicle, etc.
- Logic layer - creates and dispatches the correct entities and units of the application in the correct order according to the incoming request.
- Framework layer - holds the code that builds up the framework, binding your application together.
- Base layer - defines the drivers of the software stack, such as extensions of PHP (PDO, XML, etc.).
- Foundation layer - includes the low level tools that are required to run the whole stack, such as PHP, Linux, Nginx, etc.

Using the metaphor of a pyramid in software design promotes clean dependency trees. Each layer has to be lighter than the one beneath it, as a top-heavy pyramid is going to be trouble. Each unit at the tip of the pyramid has one job and hardly any dependencies to achieve it.

This style of dependency injection greatly improves the testability, maintainability and readability, producing robust code that isn't fragile to change.

### Layer boundaries

The business logic of an application can be seen as the policies and actions the business would perform even if there was not an automated software system in place. A perfect software design would keep these classes in their own code repository and the project would depend on them using Composer. This makes versioning of logic much simpler, allows for better isolated unit testing, and errors would typically be caught earlier. However, this may be overkill for small projects. Keep in mind that the business logic should be coded in a style that allows it to be extracted into its own repository should the need arise, but be mindful of unnecessary early overcomplication.

It's too easy to cheat the layers of an application's architecture if development is started from the base up. To enhance each layer's quality, build from the tip down as far as is feasible. Designing the static HTML page views first allows functionality to progressively enhance a static website towards a full dynamic application, and also allows an applications graphic and user interface design to be built in a reactive manner, rather than as a passing thought at the end of a project.

## WebEngine example

In a WebEngine application, the pyramid can be read top-down like this:

- [[Testing WebEngine applications]] because the best time to prove behaviour is while the system is still small enough to reason about clearly
- [[Page Views]] because the shape of the response should usually exist before the implementation grows around it
- [[Page Logic]] because each request still needs an entry point
- [[Application classes]] because business behaviour should move out of the page file as soon as it becomes reusable or non-trivial
- domain entities and value objects where the application's own concepts live
- [[Databases]] and other infrastructure adapters where persistence and external systems are handled
- framework glue such as routing, configuration, and the service container

## Thin page logic

Page logic should orchestrate rather than own business rules. A good page file usually reads like a short story of the request: get the input, call the right service, bind the result, maybe redirect.

That keeps pages easy to understand because the request-specific flow is visible without dragging all the application behaviour into one file.

## Keeping boundaries clean

Try to keep each layer from leaking into the others. Views should not need to know how the database works. Page logic should not need to know the SQL. Application classes should not need to know which page called them.

This does not need to be perfect from day one, but it is a useful direction to keep moving in. Application code that can survive framework changes is usually also application code that is easier to test and easier to explain.

## Hypermedia

Hypermedia, in this context, simply means HTML over HTTP. The browser requests a URL, the server returns a document, and links and forms move the user through the system.

Writing for hypermedia first does not mean refusing JavaScript. It means making the URL, the document, and the request flow the primary design. That tends to lead to better architectural decisions because each page state has a clear entry point and a clear response.

Once that foundation is in place, the application can still gain a [[fluid user experience]] without giving up the simplicity of ordinary page requests.

*****

Part of good application design is following a [[coding styleguide]].


Coding style choices directly affect how easy a project is to navigate. The styleguide of a project should be seen as a guide, not a rulebook. The purpose of having a styleguide is not to enforce strict rules, but to enhance consistency throughout a project.

You do not have to follow it exactly, but it is worth reading because the framework is designed with those ideas in mind:

- https://github.com/PhpGt/StyleGuide

Whatever conventions you choose, consistency matters more than novelty.

## Naming conventions in WebEngine

### Path mapping

Page files should map clearly to URLs. // TODO: Expand what this means.

That is one of the reasons WebEngine uses file-based routing so heavily: the path itself becomes part of the documentation.

// TODO: Explain the preference of how page files and URIs should be named (lower-case hyphenated files in the page directory, for URIs).

## Classes

Application classes should map clearly to namespaces. 

## Database files

Query files should be named similarly to URIs. // TODO: Is this even true?

## Page logic style

Keep page logic small and readable. Use explicit action names for `do_*` handlers. Keep the request flow easy to scan.

If a page file starts to feel like the centre of the whole application, that is usually a sign that behaviour should move into application classes.

## Application class style

Application classes work best when their responsibilities are cohesive and their dependencies are clear. Prefer small classes that own one kind of behaviour over broad "everything" classes that know too much.

Framework-light classes are also easier to test and easier to move if the project changes direction later. // TODO: Expand what this means.

## HTML and template style

Write semantic HTML and use binding attributes deliberately. The page view should still make sense to a reader who has not yet opened the matching PHP file.

*****

Running, testing, and deploying applications requires a [[PHP environment setup]].


WebEngine expects a modern PHP environment with the usual extensions for DOM, JSON, and HTTP-related work. Using `gt` or Composer will ensure the dependencies are installed correctly. Local development and production do not need to be identical, but they do need to be close enough that behaviour stays predictable.

## Local development setup

To develop WebEngine applications locally, we want the following to be installed in our environment:

- PHP version 8.4+
- Composer
- the required PHP extensions: curl, dom, libxml, fileinfo, json, mbstring, pdo, pcntl
- the `gt` tooling

Once those are installed, verify them before starting a project:

```bash
php -v
composer --version
gt
```

From there, a project can be run with `gt run`, with `gt serve`, by using the PHP development server directly, or by setting up a local web server if you prefer to mirror production more closely.

## Environment pitfalls

The most common early problems are:

- missing extensions
- the wrong PHP version
- permission issues
- clashing local services on the same port

It is usually worth checking the PHP binary your shell is actually using, especially on machines with several PHP versions installed.

*****

For production applications, [[web servers]] are a requirement.


The web server has two jobs in a WebEngine project:

- serve real static files from `www/`
- pass dynamic page requests into WebEngine

Getting that split right is one of the most important parts of a deployment.

## Local server vs. production server

For local development, PHP's built-in server is often enough, and `gt serve` or `gt run` handles the setup for you.

For production, use a real web server such as Nginx or Apache. Those are designed to serve static files efficiently, route PHP requests properly, and scale far beyond what the built-in server can do.

## Key setup concepts

The main concepts are:

- document root should point at `www/`
- dynamic requests need a fallback route into WebEngine's `go.php`
- static assets should be served directly where possible
- PHP execution needs to be configured correctly for your chosen server

The exact syntax depends on the server, but the model stays the same.

## Scaling

PHP's development server is for development only. It is not designed to scale in production.

By contrast, a normal server-rendered, hypermedia-first WebEngine application can take full advantage of ordinary web server scaling strategies. Vertical scaling means giving one server more resources. Horizontal scaling means spreading requests across more than one server. Which matters depends on the application, but neither strategy works well unless the basic document root and request routing are set up correctly first.

*****

For database-driven applications it's important to get the [[database setup]] correct and secure.


When WebEngine projects need work to happen outside the normal request cycle, use background cron tasks.

A browser request should render a page, return an API response, or accept user input. It should not wait while the application refreshes a remote cache, sends a digest email, imports a feed, or cleans old generated files. Those jobs belong in the project, but they should run on their own schedule.

WebEngine uses the [PHP.GT/Cron](https://www.php.gt/cron) component for this. The schedule lives in a project-level `crontab` file, and the task entry points usually live in the project's `cron/` directory.

## Project layout

Here's an example project with two background cron tasks:

```text
.
├── class/
│   └── ServiceLoader.php
├── cron/
├───├── cleanup/
│   │   └── cache.php 
│   └── refresh-news.php
├── page/
├── www/
└── crontab
```

The `crontab` file decides when jobs are due. The `cron/` directory contains the project code that runs when those jobs fire.

## The `crontab` file

Create a file named `crontab` in the project root. It follows the standard unix crontab format. Example:

```text
# Refresh remote content every 15 minutes.
*/15 * * * * refresh-news?source=php

# Clear generated cache files every night.
30 2 * * * cleanup/cache

# Run a normal shell command at the top of every hour.
0 * * * * bash bin/report-status.sh
```

The first five fields use familiar crontab syntax:

```text
* * * * * command
| | | | |
| | | | +-- day of week
| | | +---- month
| | +------ day of month
| +-------- hour
+---------- minute
```

The command after the schedule is interpreted relative to the project. It can be a `cron/` script, a `go()` cron script with query-string input, a static PHP method, or a shell command.

PHP.GT/Cron also provides a few helper extensions that are not part of every Unix cron implementation. For sub-minute jobs, add an `s` suffix to the first field, such as `*/10s * * * * refresh-news`, to run every 10 seconds. It also supports special `@` schedule names such as `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`, and `@annually`. These helpers are convenient for WebEngine projects, but keep in mind that they are interpreted by PHP.GT/Cron rather than by the system `crontab` command.

## Cron `go()` scripts

The most WebEngine-friendly style is a PHP file in `cron/` that defines a `go()` function. It feels similar to page logic: declare the services you need as parameters and let the container provide them.

`crontab`:

```text
*/15 * * * * refresh-news?source=php
```

`cron/refresh-news.php`:

```php
<?php
use GT\Input\Input;
use App\NewsImporter;

function go(Input $input, NewsImporter $newsImporter):void {
	$source = $input->getString("source");
	$newsImporter->refresh($source);
}
```

The `?source=php` part is parsed as query-string input and is available through `Input`. Other parameters are resolved through the same service-loading conventions used by WebEngine page logic.

This makes `go()` scripts a good fit for application tasks that need repositories, API clients, configuration, logging, or other project services.

## Nested tasks

Cron scripts can be organised into subdirectories:

```text
30 2 * * * cleanup/cache
```

This can point at:

```text
cron/cleanup/cache.php
```

Nested paths are for `go()` cron scripts. In this example, `cron/cleanup/cache.php` should define `function go(...)`.

## Ordinary PHP scripts

For simple jobs that do not need service injection, create a standalone script:

`crontab`:

```text
0 * * * * build-index --quiet
```

`cron/build-index.php`:

```php
<?php
[$script, $mode] = $argv + [null, null];

// Build generated files, warm a cache, or call application code here.
```

The runner resolves `build-index` to `cron/build-index.php` and passes any trailing arguments through to the script. Ordinary script aliases are direct children of `cron/`; use a `go()` script when you want nested paths such as `cleanup/cache`.

## Static methods and shell commands

The command can also call a static PHP method, loaded using the project's autoloader:

```text
0 9 * * MON-FRI App\Task\Digest::send("team@example.com")
```

Or it can run a shell command exactly as written:

```text
30 2 * * * php bin/nightly-maintenance.php
```

Use a `go()` script for application-integrated work, a normal `cron/` script for standalone PHP scripts, and a shell command when the job naturally belongs to another executable.

## Local development

When running the application locally, `gt run` starts the WebEngine development server and can run the cron watcher alongside it.

```bash
gt run
```

If a project has cron tasks but you only want the web server and other development processes, start without cron:

```bash
gt run --no-cron
```

If you only want the scheduler, run:

```bash
gt cron
```

With no flags, `gt cron` reads `./crontab`, runs jobs that are due now, prints the current time, prints the next scheduled job, and exits.

Example output:

```text
Current time: 16:49:52 (15:49:52 UTC)
Just ran 0 jobs
Next job at: 17:00:00 (16:00:00 UTC) [build-index]
```

Use watch mode to keep the scheduler running:

```bash
gt cron --watch
```

Useful local checks:

```bash
gt cron --validate
gt cron --now
gt cron --now --watch
```

`--validate` checks the `crontab` file without running jobs. `--now` runs every task once before normal scheduling begins, which is useful when testing new task code.

## Production use

`gt run` is for local development. In production, the web server handles requests and the cron runner should be managed as a separate long-running process.

Use the process manager provided by your hosting environment, such as systemd, Supervisor, a container process, or a platform-specific worker service. The important part is that the process starts from the project root and runs the scheduler in watch mode:

```bash
gt cron --watch
```

The process manager should restart it after deploys, reboots, or crashes. Keep only one active scheduler process per environment unless a task is explicitly designed to run concurrently.

*****

Move back to [[Run an application]], or continue to the [[request-response lifecycle]].


SQLite is a very good starting database for many projects, and it can cope with more real traffic than people often expect. For one application on one server, it is often entirely enough.

Sometimes a dedicated database server makes more sense. Common examples include several application servers sharing one data store, heavier write concurrency, or operational requirements such as managed backups and external reporting tools.

Choose the database based on the application's needs, the deployment shape, and the team's familiarity.

## Connection setup

Database connection details live in the `[database]` section of config. The key settings are the driver, schema, host, port, username, and password.

Those values are often different between local development and production, which is exactly what the configuration layering is for.

## Initialising schema and data

At the start of a project, you need a repeatable way to create the schema. In WebEngine that usually means migrations rather than ad hoc SQL run by hand on whichever machine you happen to be using at the time.

Keep the schema history explicit and repeatable so a new environment can be brought up cleanly.

## Local vs, production concerns

Local development usually cares about convenience. Production cares about credentials, backups, permissions, connection stability, and sometimes managed database infrastructure.

Those are not separate concerns forever. It is worth thinking about them while the project is still small, even if the local database is only SQLite for now.

*****

Let's move on to [[client-side compilation]].


Client-side compilation is the practical side of the build system. Source CSS, JavaScript, and static resources need to become files the browser can actually request from the web root.

Even assets that are not "compiled" still often need copying into `www/`.

## What gets compiled or copied

Typical examples are:

- Sass or other stylesheet preprocessors
- JavaScript source files
- images and other static resources

The exact toolchain is up to the project. WebEngine does not force one front-end stack.

## Development workflow

WebEngine does not dictate a build tool, though a common default setup uses npm-installed tools such as `sass` and `esbuild`.

During development, watch mode is useful because the build output updates whenever source files change. One-off builds are useful when checking the pipeline or preparing a release.

The important rule is that the finished assets end up in the public web root so the browser can fetch them.

## Production workflow

In production, builds should be deterministic and repeatable. That usually means running the same build process in CI or deployment rather than relying on manual local steps.

It is also normal to disable source maps and other development-only output in production builds.

*****

Next, let's learn about [[testing WebEngine applications]].


WebEngine's separation of concerns helps testing because different kinds of behaviour can be tested at the right level.

An application class can be unit tested without rendering a whole page. A page flow can be tested through the browser without pretending the framework internals are your responsibility to retest.

## What and when to test

In a perfect world, test-driven development would shape the work from the start. In real projects, that is not always how things begin. Even so, the broad split still helps:

- application classes in isolation are a good fit for PHPUnit
- page-level behaviour is a good fit for Behat

The earlier a useful test exists, the safer later refactoring becomes.

## Practical test strategy

Keep unit tests focused on application functionality. Try to test business rules where they actually live, rather than only through the page layer.

Use behavioural tests for page-level integration so the browser-facing flow is covered too. Avoid over-testing framework or language internals that are not part of your own application's behaviour.

## Test-driven development

TDD is a discipline rather than a switch you turn on once. Done well, it changes the shape of development because no application behaviour appears without a test proving it.

That creates confidence in user-critical flows, data handling, business rules, and the rendering of important pages. If you want to see that style applied to the to-do list example, continue with the [[todo list TDD tutorial]].

*****

When you're ready to deploy to production, have a [[production checklist]] to hand.


## Before release

Before a release, confirm that production config values are correct, error handling behaves as expected, build output is present, and the database schema is ready.

These checks are simple, but skipping them is one of the easiest ways to turn a straightforward deployment into a confusing one.

## Security and stability checks

Check that sessions and cookies are configured safely, debug output is disabled, secrets are stored in the right place, and logging is set appropriately for production.

That usually means enough logging to diagnose problems, but not so much that sensitive values leak into logs or responses.

## Operational checks

Confirm the web server is configured correctly, backups are in place where needed, and the deployment process is repeatable rather than manual guesswork.

If the application is expected to be monitored, make sure that work is done before the release rather than after the first incident.

## After release

Run a short smoke test of the key user flows, check logs, and keep an eye on slow requests or broken assets. The goal is not to test everything again by hand, but to make sure the release actually behaves like the thing you intended to deploy.

*****

The next page will cover WebEngine application [[security]].


WebEngine helps with a number of sensible defaults, but no framework removes the need for secure engineering. Security is an ongoing part of the work, not a one-time setting.

## Areas to cover

The main areas to keep in view are:

- CSRF protection
- session and cookie safety
- input validation
- output handling
- secrets and configuration
- server configuration

These are not separate from ordinary application work. They are part of it.

## WebEngine-specific safety features

WebEngine already gives us some useful pieces:

- protected globals to reduce accidental request-data leakage
- structured input handling instead of raw superglobals
- a request lifecycle that keeps the entry points predictable
- built-in support for secure patterns such as CSRF protection

If you want the CSRF component details, those are documented at https://www.php.gt/docs/Csrf/Home/.

## Common mistakes to avoid

Common mistakes include leaving debug features enabled in production, trusting raw user input, binding HTML when plain text would be safer, and mixing sensitive logic into page views.

It is also worth treating server configuration as part of application security. A perfectly written page is not much help if the wrong files are publicly reachable.

*****

In the reference chapter, we will cover the [[gt commands]].


This page is the command reference for the `gt` CLI. For the conceptual overview, see [[gt command overview]].

## Command reference structure

Each command below is listed with a short summary and the most common use case. The detailed help output from the command line remains the best source for the exact flags available in your installed version.

## Core commands

### `gt create`

Creates a new WebEngine project.

Typical use:

```bash
gt create my-app
```

Optional arguments:

- `--namespace` or `-n` - The application's root namespace
- `--blueprint` or `-b` - A template project to build on
- `--empty` or `-e` - To force using the empty blueprint, with the default App namespace.

### `gt run`

Starts the local development environment, including the server and any supporting watchers the project needs.

```bash
gt run
```

Optional arguments:

- `--port` or `-p` (default 8080)
- `--bind` or `-b` (default 0.0.0.0 for all addresses)
- `--debug` or `-d`
- `--no-build` to disable the build watcher
- `--no-cron` to disable the cron tasks

### `gt serve`

Starts only the local PHP development server.

```bash
gt serve
```

- `--port` or `-p` (default 8080)
- `--bind` or `-b` (default 0.0.0.0 for all addresses)
- `--debug` or `-d`

### `gt build`

Runs the build system once, or in watch mode if supported by the project's setup.

```bash
gt build
```

Optional arguments:

- `--watch` or `-w` to continue the build runner after first build
- `--config` or `-c` defaults to `./build.ini`
- `--default` or `-d` path to a default build.ini
- `--mode` or `-m` to define production or development mode

### `gt test`

Runs the project's test suite.

```bash
gt test
```

### `gt cron`

Runs the scheduled task watcher locally.

```bash
gt cron
```

Optional arguments:

- `--watch` or `-w` to continue running cron commands as they become due. Without this flag, cron will only run the commands that are due at the point of executing the command
- `--validate` to check the syntax of the crontab file without running anything
- `--now` or `-n` to run all tasks once now. Useful when using `--watch` for when developing locally
- `--file` to read a crontab file other than `./crontab`

### `gt deploy`

Work in progress.

*****

Check out the [[configuration reference]] page next.


This page is a lookup reference for the config keys used by WebEngine. For the conceptual overview of how config is loaded and used, see [[Configuration]].

## Reference structure

The easiest way to document WebEngine config is by section. Each section groups related keys, and each key should be understood in terms of:

- what it controls
- its default value
- when you might want to override it

## Main sections

The main sections are:

- `app`
- `router`
- `view`
- `logger`
- `session`
- `database`
- `security`

For the underlying config package, see https://www.php.gt/docs/Config/Home/.

### Config section: `app`

- `namespace` - default `App` - the namespace prefix to use when loading classes within your project. This might be your company's name, for example. 
- `production` - default `false` - set to true when deployed to a production server.
- `class_dir` - default `class` - the directory name to use as the PSR-4 root for your [[application classes]]. 
- `service_loader` - default `ServiceLoader` - the class name of your application's service loader, for extending the [[service container]].
- `slow_delta` default `0.25` - the number of seconds a request takes to trigger a "slow" notice.
- `very_slow_delta` - default `0.50` - the number of seconds a request takes to trigger a "very slow" warning.
- `render_buffer_size` - default `1024` - number of bytes to flush in chunks to the browser.

See [[protected globals]].

- `globals_whitelist_env` - default unset - which `$_ENV` variables to leave available globally.
- `globals_whitelist_server`  - default unset - which `$_SERVER` variables to leave available globally.
- `globals_whitelist_get` default `xdebug` - which `$_GET` variables to leave available globally.
- `globals_whitelist_post` - default unset - which `$_POST` variables to leave available globally.
- `globals_whitelist_files` - default unset - which `$_FILES` variables to leave available globally.
- `globals_whitelist_cookies` - default unset - which `$_COOKIE` variables to leave available globally.
- `force_trailing_slash` default `true` - true to end requests with a slash, false to end requests without a slash, e.g. `www.example.com/test/` vs `www.example.com/test`.

See [[Errors and logging#Custom error pages]].

- `error_page_dir` - default `page/_error` - the directory name to use to contain error pages.

### Config section: `router`

See [[Routing reference]].

- `router_file` - default `router.php` - the application router file to load before falling back to the framework router.
- `router_class` - default `AppRouter` - the router class name expected within `router_file`.
- `redirect_response_code` - default `307` - the HTTP status code used for framework-generated redirects such as trailing-slash normalisation.
- `default_content_type` - default `text/html` - the content type used when the router does not set one explicitly.

### Config section: `view`

- `component_directory` - default `page/_component` - the directory containing [[custom HTML components]].
- `partial_directory` - default `page/_partial` - the directory containing [[page partials]].

### Config section: `logger`

- `log_all_requests` - default `true` - log standard requests at the configured logger level.
- `log_static_requests` - default `false` - include requests for static files in the request log.
- `log_404_to_error_log` - default `false` - when true, 404 responses are additionally written to the error log.
- `log_redirects` - default `false` - include redirect responses in the log output.
- `debug_to_javascript` - default `true` - when buffering debug output, expose it to the browser-side JavaScript debug stream.
- `stderr_level` - default `ERROR` - the minimum log level routed to `stderr` when using split stdout/stderr logging.
- `type` - default `stdout` - the logger output target. The default writes to standard output.
- `level` - default `debug` - the minimum log level for the main logger output.
- `path` - default empty - the file path to log to when using a file-based logger target.
- `timestamp_format` - default `Y-m-d H:i:s` - PHP date format used when rendering log timestamps.
- `log_format` - default `{TIMESTAMP}\t{USER}\t{LEVEL}\t{MESSAGE}\t{CONTEXT}` - the template used to format each log line.
- `separator` - default `\t` - the separator token used by the logger formatter.
- `newline` - default `\n` - the line ending appended to each log entry.

### Config section: `session`

See [[sessions]].

- `handler` - default `Gt\Session\FileHandler` - the session handler class to use.
- `path` - default `phpgt/session` - storage path passed to the session handler.
- `name` - default `GT` - the session name sent in the cookie or URL-based session identifier.
- `use_cookies` - default `true` - when true, PHP session IDs are stored in cookies.

### Config section: `database`

See [[databases]].

- `driver` - default `sqlite` - the database driver name.
- `host` - default `localhost` - the database host name, mainly relevant for networked database drivers.
- `schema` - default `:memory:` - the schema or database name. For SQLite, the default is an in-memory database.
- `port` - default `0` - the database port. A zero value leaves port selection to the driver defaults.
- `username` - default `app_user` - the database username.
- `password` - default `app_pass` - the database password.
- `query_directory` - default `query` - the directory containing SQL query files.
- `migration_path` - default `_migration` - the directory containing migration files.
- `migration_table` - default `_migration` - the table name used to track applied migrations.
- `query_path` - default `query` - the path used when resolving query files.

### Config section: `security`

See [[security]].

- `default_headers` - default unset - optional semicolon-separated security headers to append to responses.
- `csrf_header` - default `X-CSRF` - the header name used to transmit CSRF tokens for refreshing client-side.
- `csrf_ignore_path` - default empty - a comma-separated list of request paths or path patterns excluded from CSRF checks.
- `csrf_max_tokens` - default `100` - the maximum number of CSRF tokens retained before older ones are discarded.
- `csrf_token_length` - default `32` - the generated CSRF token length in bytes.
- `csrf_token_sharing` - default `per-page` - whether tokens are generated once per-page or once per-form.

## Practical notes

Some keys mainly affect development, such as debug or logging behaviour. Others are only required for production, such as database credentials, session settings, and security-related values.

When in doubt, keep project-level defaults small and override only what the environment genuinely needs to change.

> [!IMPORTANT]
> Never store your secret credentials such as API keys or database passwords in version control. Your project's `config.ini` should only have development-related credentials or empty values stored - secret values should only ever be stored within `config.production.ini`, placed their manually or via your project's deployment process.

*****

Move on to the [[routing reference]] page.


WebEngine routing is built on the `phpgt/routing` package, but most applications do not need to work with that package directly. The framework creates the request, loads the router, matches files from the project, builds the view and logic assemblies, and then lets the dispatcher execute the response.

This page is a reference for how that routing behaviour fits together inside a WebEngine application.

## The default routing model

If an application does not provide its own router, WebEngine uses the framework router. That router has two routes:

1. Page routes, which match browser-facing HTML requests against files in `page/`
2. API routes, which match structured response requests against files in `api/`

The route is selected from the incoming request method, path, and `Accept` header. A normal browser request is usually handled by the page route because it accepts `text/html` and `application/xhtml+xml`. API requests are handled by the API route when the client asks for `application/json` or `application/xml`.

Once the route has been chosen, WebEngine looks for matching files on disk. It does not expect us to maintain a central list of every page in the application. The path still maps to the project structure, as covered in [[file-based routing]].

## Routing an Assembly of logic and view files

Routing does not render the response by itself. Its job is to decide which files belong to the request. This is done by building a file Assembly.

WebEngine records those files in two ordered lists:

- the logic assembly, containing PHP files that may define `go` and `do_*` functions
- the view assembly, containing the view files that make up the response body, either HTML or JSON

For example, a request to `/shop/music` may produce a view assembly like this:

```text
page/_header.html
page/shop/_header.html
page/shop/@category.html
page/shop/_footer.html
page/_footer.html
```

and a logic assembly like this:

```text
page/_common.php
page/shop/_common.php
page/shop/@category.php
```

The dispatcher later executes the logic assembly and streams the view assembly into the response: routing answers "what belongs to this request?", while dispatching answers "how do we run it?".

## File matching rules

WebEngine's default router uses the Routing package's path matcher to scan the relevant directory and compare each file with the requested URI.

The important matching rules are:

- direct files can match directly, such as `/about` to `page/about.html` and `page/about.php`
- directory index files can match clean URIs, such as `/blog` to `page/blog/index.html`
- dynamic names use `@`, such as `/blog/hello-world` to `page/blog/@slug.html`
- catch-all dynamic names use `@@`, for deeper path captures
- `_common`, `_header`, and `_footer` are special shared files that can be included because of where they sit in the directory tree

Static files take priority over dynamic placeholders. If both `page/request/secrets.html` and `page/request/@request-id.html` exist, the URI `/request/secrets` will resolve to the concrete `secrets.html` file rather than being swallowed by the dynamic route.

Headers and footers are also sorted deliberately. Outer headers are applied before inner headers, and inner footers are applied before outer footers, so nested sections can wrap their own content without breaking the site-wide frame.

## Dynamic paths

When a route uses `@` placeholders, the captured values are available in page logic through `GT\Routing\Path\DynamicPath`.

```php
use GT\Routing\Path\DynamicPath;

function go(DynamicPath $path):void {
	$slug = $path->get("slug");
	// ... your code
}
```

For `page/blog/@slug.html` and a request to `/blog/hello-world`, `get("slug")` returns `hello-world`.

Calling `get()` without a name returns the deepest matched dynamic value. For catch-all routes using `@@`, `getExtra()` exposes the remaining path segments.

Keep dynamic routes specific enough to stay readable. A path such as `/product/chair/wooden-dining-chair` is usually easier to understand and maintain than a route that captures a whole area of the site in one broad `@@` placeholder.

## Content negotiation

The router can choose between more than one handler for the same URI by looking at the request's `Accept` header. This is how WebEngine can support an HTML page and an API representation without treating them as completely separate applications.

In the default router:

- the page route accepts `text/html` and `application/xhtml+xml`
- the API route accepts `application/xml` and `application/json`

If several router callbacks could match, the Routing package compares the accepted media types and their quality values, then chooses the best match. If a client sends `Accept: */*`, the first compatible match is used.

In practice, most WebEngine applications can keep this simple. Use normal page routes for browser pages, use API routes when the response is genuinely structured data, and only reach for custom content negotiation when one URI intentionally serves more than one representation.

## Logic stream wrapper

Page logic files often define the same function names. It is normal for several files in the same request to define `go()`, because each file belongs to a different part of the route.

WebEngine can load those files safely because the Routing package provides a logic stream wrapper. When a classless PHP logic file is loaded, the wrapper gives it a generated namespace based on its path. That means `page/_common.php` and `page/account/settings.php` can both define `go()` without colliding in PHP's global namespace.

For application code, the main rule is simple: page logic files should declare functions and classes, not produce output as a side effect. Let the logic hooks set response state, call services, and bind data into the view model.

## Redirects

Redirects are handled before the main page lifecycle begins. This means old or moved URLs can be resolved before WebEngine starts building a page response.

WebEngine looks for a single redirect file in the project root:

- `redirect.ini`
- `redirect.csv`
- `redirect.tsv`

Only one of those files should exist. If more than one redirect file is present, WebEngine treats that as ambiguous.

CSV and TSV files use the old path, the new path, and an optional status code:

```csv
/about-us,/about,301
/products/old-chair,/products/wooden-dining-chair,308
```

INI files group redirects by status code:

```ini
[301]
/about-us = /about

[308]
/products/old-chair = /products/wooden-dining-chair
```

Redirect rules are path-based. Use them for site migrations, renamed pages, and deliberately moved resources. For request-specific decisions, such as redirecting after a form submission, set the redirect from page logic instead.

## Custom routers

Most applications should start with the default router. A custom router is useful when the application needs to change the routing shape itself, for example:

- separate route groups with different view models
- custom content negotiation rules
- routing to files outside the standard `page/` and `api/` directories
- specialist routes that should not follow the normal file-based mapping

The router file and class are configured with `router.router_file` and `router.router_class`. By default, WebEngine looks for `router.php` containing `AppRouter`.

A custom router extends `GT\Routing\BaseRouter` and uses route attributes:

```php
use GT\Http\Request;
use GT\Routing\BaseRouter;
use GT\Routing\Method\Any;
use GT\Routing\Path\PathMatcher;
use GT\WebEngine\View\HTMLView;

class AppRouter extends BaseRouter {
	#[Any(name: "page-route", accept: "text/html,application/xhtml+xml")]
	public function page(Request $request):void {
		$matcher = new PathMatcher("page");
		$this->setViewClass(HTMLView::class);

		// Add matching files to the logic and view assemblies here.
	}
}
```

In a custom router, keep the same boundary in mind: the router should select files and view type, not run page behaviour directly. The dispatcher and page logic should still own execution.

## X-Redirect and X-Logic-Execution headers

Routing usually stays easy to reason about when each URI relates to an obvious file in the project. If a request becomes difficult to trace, use this list to debug:

- Check the `X-Redirect` header - if the page was redirected, this will show exactly which line of code performed the redirect.
- Check the `X-Logic-Execution` header, showing the order of the `go` and `do` functions that have been executed as part of the page response.
- Check if a static file and dynamic placeholder both match the same URI.
- Check if `page/example.html` and `page/example/index.html` are competing for the same route.
- Check shared `_common` files in any directory above the current deepest directory.

If the route still feels surprising, prefer simplifying the path structure over adding more routing rules. WebEngine works best when the URL, view file, and logic file are easy to connect in our heads.

*****

Read about [[page logic conventions]] next, or see [[development diagnostics]] when you need to inspect a request.


This page captures the naming and structural rules that make page logic predictable.

## Naming conventions

Page logic filenames should map clearly to page view filenames. Function names should reflect their role:

- `go` for the normal page handler
- `go_before` and `go_after` for the surrounding hooks
- `do_*` for named actions

Action names should stay explicit and readable. The function name is part of the request flow, so it should be easy to connect it back to the form or button that triggered it.

## Structural conventions

Keep page logic thin. Separate orchestration from business rules. Bind output late in the request flow once the data has been loaded and shaped.

If a page needs more local structure, the logic can optionally be wrapped in its own class, but the same underlying rules still apply: clear entry points, small handlers, and minimal hidden behaviour.

## Hypermedia

Hypermedia here simply means HTML over HTTP. When the page uses explicit actions, deliberate redirects, and clear URL-based state, the behavioural flow stays much easier to trace.

That is also why richer browser behaviour can be added later through [[fluid user experience]] without changing the core request logic into something unrecognisable.

*****

Move on to the [[view and binding reference]] page next.


This page is a compact lookup guide for view and binding features.

## View topics

The main view topics are:

- page views
- headers and footers
- components
- partials and templates

See also:

- [[Page views]]
- [[Headers and footers]]
- [[Custom HTML components]]
- [[Page partials]]

## Binding topics

The main binding topics are:

- `data-bind` syntax
- text, HTML, value, and attribute binding
- list and nested list binding
- object and array binding patterns

For the underlying binding system, see:

- https://www.php.gt/docs/DomTemplate/Home/
- https://www.php.gt/docs/DomTemplate/Binding-basics/
- https://www.php.gt/docs/DomTemplate/Binding-lists/

*****

Next, move on to [[Errors and logging]].


WebEngine leaves a few useful traces behind during development so you can inspect what happened during a request without turning the whole application into a debugging exercise.

## Response headers

One of the most useful diagnostics is the `X-Logic-Execution` response header.

When page logic runs, WebEngine records the functions that executed and writes them into that header in order. The values use a compact `path:function` format, for example:

- `page/index:go`
- `page/account/settings:go_before`
- `page/account/settings:do_save_profile`

This is especially useful when shared logic, component logic, and page-specific logic are all involved in the same response. Instead of guessing which hooks actually ran, you can inspect the response headers in your browser's network tools and see the exact order.

Redirect handling can also expose development-oriented header information, which helps trace where a redirect rule came from.

## Buffered debug output

If page logic or supporting code writes direct output with `echo`, `var_dump`, or similar calls, WebEngine captures that output instead of letting it corrupt the page response.

In development, that captured output can be surfaced through browser-side debugging support rather than becoming part of the page body. That makes accidental debug output easier to notice while still keeping the response shape intact.

This is useful while investigating a problem, but it should not become the normal way application pages communicate data. For normal behaviour, page logic should still bind data into the view model or set response state explicitly.

## Practical use

When a request does not behave as expected, a good first pass is:

- inspect the response status
- inspect response headers such as `X-Logic-Execution`
- check whether a redirect happened
- look for captured debug output
- then move on to application logs if needed

That usually gives enough signal to tell whether the problem is in routing, page logic, redirect rules, or lower-level application code.

*****

Continue with the [[request-response lifecycle]], or read about [[Errors and logging]].


When a request fails, WebEngine tries to turn that failure into a useful HTTP response rather than leaving PHP to dump raw output at the browser.

## Error types

Common error types include:

- missing pages
- application exceptions
- validation and user-facing failures
- configuration problems

Not all of these should be shown to the user in the same way, which is why WebEngine distinguishes them while handling the request.

## Error rendering

WebEngine first tries to render an application-specific error page. If that fails too, it falls back to a simpler built-in error response.

Development and production should behave differently here. Development needs detail. Production needs safety and clarity.

### Custom error pages

Custom error pages live in the directory configured by `app.error_page_dir`, which defaults to `page/_error`.

Create one HTML file per HTTP status code you want to handle, for example:

- `page/_error/404.html`
- `page/_error/500.html`
- `page/_error/403.html`

When an exception resolves to one of those status codes, WebEngine will try to render the matching page. If no matching template exists, it falls back to the built-in error response.

In development mode, fallback 404 responses include a hint showing the missing error page path. In production mode, that extra detail is suppressed.

See [[Configuration reference#Config section: app]] for the `error_page_dir` setting.

## Logging and diagnosis

Errors are logged as part of the request lifecycle. When diagnosing a problem, usually start by checking:

- the request path
- the matching page files
- recent configuration changes
- the application logs

Avoid leaking sensitive stack details to the browser in production responses.

### Using the logger

The main logger settings live under the `logger` config section.

- `logger.level` controls the minimum level for the main log stream.
- `logger.stderr_level` controls when messages are duplicated to `stderr`.
- `logger.log_all_requests` enables request logging for normal responses.
- `logger.log_redirects` enables logging for redirect responses.
- `logger.log_404_to_error_log` writes 404 responses to the error log.
- `logger.debug_to_javascript` controls whether buffered debug output is exposed to browser-side JavaScript tooling.

To log a message in application code, import `GT\Logger\Log` and call the method matching the level you want:

```php
use GT\Logger\Log;

Log::debug("Starting import");
Log::info("User signed in");
Log::notice("Request took longer than expected");
Log::warning("Configured fallback was used");
Log::error("Payment provider request failed");
```

You can also attach context data to the log entry:

```php
use GT\Logger\Log;

Log::info("Order created", [
	"orderId" => 4821,
	"userId" => 19,
]);

Log::error("Database query failed", [
	"query" => "select * from invoice where id = ?",
	"invoiceId" => 4821,
]);
```

In practice:

- use `debug` for development detail
- use `info` for normal application events
- use `notice` for unusual but expected situations
- use `warning` when something degraded but the request can continue
- use `error` when part of the request failed
- use higher levels such as `critical`, `alert`, or `emergency` only for severe operational failures

By default, WebEngine logs to standard output and sends higher-severity messages to standard error. That default fits container and process-manager environments well, because log collection is usually already wired to those streams.

For application failures, 5xx exceptions are logged automatically. Client-side failures are treated more quietly: 404s are only logged when `logger.log_404_to_error_log` is enabled, and other handled client errors are not treated as server errors.

For the full list of logger defaults, see [[Configuration reference#Config section: logger]].

*****

The final reference page is [[project structure reference]].


This page is a quick reference for where things live in a WebEngine project.

## Project root directories and files

The most common directories and files are:

- `page/`
- `class/`
- `query/`
- `www/`
- config files in the project root

## What lives where

`page/` contains page views and page logic. `class/` contains application classes. `query/` contains SQL queries and migrations. `www/` contains public files that the web server can serve directly.

Config files stay in the project root because they describe the application as a whole rather than one page.

## Naming and placement rules

Keep index files for directory-level pages, keep HTML and PHP page pairs aligned, and keep shared layout and component directories in their expected special paths.

The more obvious the placement is, the easier it becomes to follow a request through the project.

*****

Move on to the Further Reading chapter with [[Distinct Logic Authority]].


Each operational state of an application should have one clear entry point. In web applications, the URL is the natural place for that to begin.

That idea becomes much easier to follow in hypermedia applications, where HTML over HTTP is still the main model and each page state is represented by an actual requestable location.

## Traceability

Distinct logic authority improves traceability because it is immediately obvious where the request begins. If a button does not work, we can usually:

1. identify the page URL
2. find the page logic
3. find the matching action or `go` handler
4. inspect redirects or response headers if the flow changes

That avoids duplicated behaviour being spread across several hidden entry points.

## Relationship to WebEngine

WebEngine reinforces this idea through file-based routing and thin page logic. A URL maps to a clear page file, and actions map to clear `do_*` functions.

The framework also leaves useful traces in response headers during development, such as where redirects came from and which logic hooks executed, which makes the request path easier to inspect.

*****

Next, read [[SPA vs MPA]].


Web development has evolved significantly over the decades, leading to the rise of different architectural paradigms. One of the most popular architectures that emerged in the 2000s is the Single Page Application (SPA).

## What is a SPA?

The concept of an SPA is that it's a single page that downloads all of the application code in its first request - generally within an `index.html` - and then heavily relies on JavaScript to hook events to all links and forms, so the browser never actually navigates away from the original page. Instead, the browser re-draws areas of the page only when they need to be updated. This creates a smooth, fast, and modern application, and has become a staple development methodology of many front-end frameworks like React, Angular, Vue, and Svelte. But there are many downsides: firstly all of the benefits of the web as a platform are removed when the platform is reimplemented within a single page. It's fine when there are only links being clicked and forms being submitted, but there's a lot of hidden complexity that is solved for free by the web as a platform: how do you handle keyboard navigation, resizing browser windows, or visually impaired users reading the page with screen reader software?

SPAs contradict the core principals of WebEngine: the web is the best platform, so we should take advantage of its many capabilities. It's possible to gain all the benefits that come with an SPA without having to change the way the web was designed to work through a development process called **progressive enhancement**.

## Modern MPA development

A WebEngine application is built as a Multi Page Application (MPA), where each page has its own individual HTML and PHP file - but by using progressive enhancement, MPAs can have gain a [[fluid user experience]] without introducing the complexities and downsides of SPAs.

This way, the web application can be built using simpler technology, it works for everyone, but provides a richer experience for those with available technology.

MPAs can take advantage of 30 years of tried-and-tested technology, with no need to fix nuances that were solved in the web platform decades ago.

### Progressive enhancement

Progressive enhancement is a web development approach that prioritises making a website or application accessible to everyone, regardless of their device, browser or user capabilities. It starts with a basic, functional version of the site using simple, reliable technologies like HTML, PHP and CSS. This ensures that all users can access the core content and functionality as it was developed, without adding lots of extra fragile layers to the application.

Then, when the application is working nicely, a small layer of client-side logic can be added to enhance the way links load, or forms submit, for example. This can be coded manually using JavaScript, or read the [[fluid user experience]] to see how this is automatically handled in WebEngine applications.

### Distinct logic authority

MPAs maintain a clear separation of concerns with a single, predictable entry point for each page. This enhances code readability and maintainability, making it easier for developers to understand and manage the application logic.

In WebEngine applications, this is further enforced by using go and do functions to indicate the entry point of the application logic.

Read more about the [[distinct logic authority]] concept and how it's applied through WebEngine.

*****

Read about how a [[fluid user experience]] library is shipped by default in WebEngine.


Writing applications for hypermedia (plain HTML over HTTP) brings a lot of benefits. URLs stay meaningful, page states stay easy to trace, and the browser and server can work together to provide unrivaled efficiency. The trade-off is that, left completely alone, these applications can sometimes feel clunky or old fashioned because every interaction is a full page load. But with a hypermedia, server-rendered application, it only takes a very small layer of client-side code to remove most of that roughness and make a hypermedia application feel fluid, while still keeping the underlying application simple and readable.

WebEngine can provide a fluid user experience without changing the basic shape of a web application. The page is still HTML, and the browser still requests URLs like normal. Forms still submit to the server, and links still point to real pages.

This is done by adding `data-flux` attributes within the HTML, and the Flux client-side micro framework will perform progressive enhancements to automate the client-side experience.

Full Flux documentation: https://www.php.gt/docs/Flux/

The main idea is simple: the server keeps returning complete HTML documents, and Flux swaps the matching parts of the current page with the matching parts from the new document.

## Updating parts of a page dynamically

The usual starting point is an ordinary form that already works without any JavaScript:

```html
<form method="post">
	<output data-flux="update">0</output>
	
	<button name="do" value="increment" data-flux>Increment</button>
	<button name="do" value="decrement" data-flux>Decrement</button>
</form>
```

With no Flux, the form submits normally and the whole page reloads. With Flux loaded in the browser:

1. clicking the button prevents the normal submit
2. the form is submitted in the background
3. the server returns the normal full HTML page
4. Flux finds the matching `data-flux` update target in the returned document
5. only that part of the current page is replaced

That means we do not need to build a separate JSON API or a separate fragment-rendering system just to make one part of the page feel quicker.

The most useful update directives are:

- `data-flux="update"` to replace the whole element
- `data-flux="update-inner"` to keep the element but replace its contents
- `data-flux="update-link"` to update an element only during Flux link navigation
- `data-flux="update-link-inner"` to keep the outer element but replace only its contents during Flux link navigation
- `data-flux="update-attributes"` to refresh just the element's attributes

### Updating a whole element

Use `update` when the element itself may change:

```html
<form method="post" data-flux="update">
	<output>0</output>
	<button name="do" value="increment" data-flux="submit">Increment</button>
</form>
```

This is useful when the element's attributes or outer structure may change between responses.

### Updating only the contents

Use `update-inner` when the wrapper should stay in place:

```html
<section class="todo-list" data-flux="update-inner">
	<ul>
		<li>Write docs</li>
	</ul>
</section>
```

This is common when the outer element has layout or styling responsibilities and only the inner content changes.

### Updating more than one target at once

Flux is not limited to one updated element. If the returned document contains several matching Flux targets, all of them can be refreshed from the same server response.

That is useful for pages such as:

- a pair of counters with a separate total
- a basket page with individual line items and an order summary
- a dashboard where one action changes several small widgets

The practical guide for this part of Flux is:

- https://www.php.gt/docs/Flux/Coordinating-multiple-updates/

### Link navigation

Flux can also enhance normal links:

```html
<main data-flux="update-link">
	<nav>
		<a href="/reports" data-flux>Reports</a>
		<a href="/settings" data-flux>Settings</a>
	</nav>
</main>
```

When a Flux link is clicked, Flux fetches the destination document in the background, updates the matching target, and updates the browser history.

This keeps navigation fluid while still treating each page as a real page with its own URL and its own server-rendered HTML.

See:

- https://www.php.gt/docs/Flux/Link-navigation/

### Live updates

Sometimes the page needs to keep itself up to date without any user action. Flux supports that with live regions:

```html
<time data-flux="live" data-flux-rate="5">12:00:00</time>
```

This tells Flux to poll the current page every five seconds and replace the matching `<time>` element with the version from the newly returned document.

`data-flux="live-inner"` works in the same way, but keeps the outer element and replaces only its contents.

Live regions are useful for:

- clocks
- status badges
- queue counts
- notifications
- small dashboards

See:

- https://www.php.gt/docs/Flux/Live-updates/

### Autosave and attribute updates

Flux also supports background submission when a form changes:

```html
<form method="post" data-flux="update-inner">
	<input name="title" />
	<button name="do" value="save" data-flux="autosave">Save</button>
</form>
```

Here the button is hidden by Flux and used as the trigger for automatic saving whenever the form changes.

Attribute-only refreshes are useful when the content does not need changing, but the state does:

```html
<button data-flux="update-attributes" disabled aria-busy="true">Save</button>
```

This works well for:

- `disabled`
- `class`
- `aria-*`
- `data-*`

See:

- https://www.php.gt/docs/Flux/Autosave-and-background-submits/

### Rate limiting

Flux can rate-limit buttons, links, and live regions with `data-flux-rate`:

```html
<button data-flux="submit" data-flux-rate="1">Save</button>
```

This allows one request per second from that control. For live regions, the same attribute defines the polling interval.

That helps prevent accidental double-clicks or repeated rapid requests from a control. It does not replace server-side validation or idempotency checks.

See:

- https://www.php.gt/docs/Flux/Rate-limiting/

### JavaScript hooks and debugging

Flux also cooperates with your own JavaScript. When it replaces elements, it reinitialises new Flux elements and reattaches event listeners that were added through `addEventListener`.

That matters because without it, a DOM replacement would normally discard those listeners.

If you are debugging Flux itself or trying to understand a page's behaviour in detail, Flux also exposes a debug mode. The details are covered here:

- https://www.php.gt/docs/Flux/JavaScript-hooks-and-debugging/

## Multi-pass rendering

Multi-pass rendering is the idea of giving the browser something useful first, then doing slower enhancement work afterwards.

For example, a page might:

1. return a fully usable first response immediately
2. let the browser render that page
3. make a later request for slower-changing or heavier dynamic areas
4. let Flux replace those areas once the second response arrives

This can improve perceived performance because the user sees something meaningful sooner, even though some work is still happening in the background.

The important part is that multi-pass rendering still fits the same WebEngine model:

- pages are still real URLs
- the server still returns HTML
- the browser is still updating from server-rendered documents

It is not a separate application architecture. It is just another way to stage the work.

## Flux docs

This page is only the WebEngine-side overview. For the step-by-step Flux guide, continue with the Flux docs directly:

- https://www.php.gt/docs/Flux/Home/
- https://www.php.gt/docs/Flux/Your-first-Flux-form/
- https://www.php.gt/docs/Flux/Updating-part-of-the-page/
- https://www.php.gt/docs/Flux/Coordinating-multiple-updates/
- https://www.php.gt/docs/Flux/Link-navigation/
- https://www.php.gt/docs/Flux/Live-updates/
- https://www.php.gt/docs/Flux/Autosave-and-background-submits/
- https://www.php.gt/docs/Flux/Rate-limiting/
- https://www.php.gt/docs/Flux/List-of-flux-attributes/

*****

Learn how to track [[speed and benchmarks]] in your applications.


## What "fast" should mean

Fast should mean responsive to the user, not simply impressive in a benchmark chart.

Framework benchmark contests are often misleading because they optimise for artificial workloads rather than for the actual behaviour a user experiences in a real application.

## Where performance is necessary

The places that usually deserve attention are:

- slow queries
- heavy rendering
- oversized assets
- too many network round trips

These are all practical bottlenecks that a user can feel.

## Practical performance guidance

Measure user-facing operations first. Optimise after you have found a real bottleneck. Simplicity, clear architecture, and avoiding unnecessary work are often the biggest performance wins.

WebEngine's static-first pages, thin page logic, and server-rendered HTML all help because they reduce the amount of work that needs to happen before a useful response can be shown.

*****

Finally, let's move to the [[repository-entity pattern]] page to complete the further reading chapter.