Status

Reference for the Status module: post-redirect-get status messages and form validation. A handler validates posted data against per-field rules, redirects with a success or error message and an optional data payload, and a following page reads and renders the outcome. Messages carry a session-bound hash so they cannot be forged.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Status - validate posted data and redirect with a signed success or error message.
StatusUi - render the current status message, once per page.

Status

Static functions for the post-redirect-get pattern. Validate runs a map of field validators over posted data and, on any error, redirects to an error url with the per-field messages; on success the handler calls Success. Each redirect carries a status_hash tying the message to the session, checked by ValidateHash before anything is trusted. The Validate* factory functions each return a validator callable.

Functions

Error GetParameters GetValidationError GetValidationPreviousValue Hash Success Validate ValidateBoolean ValidateEmail ValidateFile ValidateFileRead ValidateFloat ValidateHash ValidateInteger ValidateObject ValidatePassword ValidatePhoneNumber ValidateString ValidateWithFiles

Error

Status::Error(string $url, string $message, array $data = null): void

Redirect to a url with an error message and optional data payload, then exit. Appends a session-bound hash so the message cannot be forged.

Name	Type	Description
`$url`	`string`	The url to redirect to.
`$message`	`string`	The error message to carry.
`$data`	`array`	An optional data payload, encoded into the url as JSON.

Returns void Sends a redirect header and exits.

GetParameters

Status::GetParameters()

Parse the current request query string into a name to value map, url-decoding each part.

Returns A map of query parameter name to value.

GetValidationError

Status::GetValidationError(string $name)

The per-field error message for a field, when the current request is a validated error redirect; null otherwise.

Name	Type	Description
`$name`	`string`	The field name to read the error for.

Returns The error message, or null.

GetValidationPreviousValue

Status::GetValidationPreviousValue(string $name)

The previously submitted value for a field, taken from the status data payload when the hash is valid; null otherwise.

Name	Type	Description
`$name`	`string`	The field name to read the previous value for.

Returns The previous value, or null.

Hash

Status::Hash(string $message, string $type, string $data): string

Compute the SHA-256 hash binding a message, type and data payload to the current session and the site secret.

Name	Type	Description
`$message`	`string`	The status message.
`$type`	`string`	The status type, such as success or error.
`$data`	`string`	The encoded data payload, or an empty string.

Returns string The hex-encoded hash.

Success

Status::Success(string|null $optionalUrl, string $message, array $data = null): void

Redirect with a success message and optional data payload, then exit. Uses the current route when no url is given, and appends a session-bound hash.

Name	Type	Description
`$optionalUrl`	`string\|null`	The url to redirect to, or null for the current route.
`$message`	`string`	The success message to carry.
`$data`	`array`	An optional data payload, encoded into the url as JSON.

Returns void Sends a redirect header and exits.

Validate

Status::Validate(array $postData, string|null $optionalErrorUrl, array $validation)

Run each field validator over the posted data. On any error, redirect to the error url with the per-field messages; otherwise return the validated values in order.

Name	Type	Description
`$postData`	`array`	The posted field values, keyed by field name.
`$optionalErrorUrl`	`string\|null`	The url to redirect to on error, or null for the current route.
`$validation`	`array`	A map of field name to a validator callable.

Returns The list of validated values, in field order.

ValidateBoolean

Status::ValidateBoolean()

Build a validator that accepts 0 or 1 and returns the value as a boolean.

Returns A validator callable.

ValidateEmail

Status::ValidateEmail()

Build a validator that checks the value is a valid email address.

Returns A validator callable.

ValidateFile

Status::ValidateFile(array $allowedMimeTypes = [])

Build a validator that checks a file was uploaded without error, and optionally that its MIME type is allowed.

Name	Type	Description
`$allowedMimeTypes`	`array`	Allowed MIME types, or empty to allow any.

Returns A validator callable.

ValidateFileRead

Status::ValidateFileRead(array $allowedMimeTypes = [])

Build a validator that checks an upload, reads its contents and returns an object with the contents, MIME type and file extension.

Name	Type	Description
`$allowedMimeTypes`	`array`	Allowed MIME types, or empty to allow any.

Returns A validator callable.

ValidateFloat

Status::ValidateFloat(float $min = null, int $max = null)

Build a validator that parses the value as a float and checks it against optional bounds.

Name	Type	Description
`$min`	`float`	The minimum allowed value, or null for no minimum.
`$max`	`int`	The maximum allowed value, or null for no maximum.

Returns A validator callable.

ValidateHash

Status::ValidateHash(): bool

Check that the status hash in the current request matches the message, type and data, tying it to this session.

Returns bool True when the hash is valid.

ValidateInteger

Status::ValidateInteger(int $min = null, int $max = null)

Build a validator that parses the value as an integer and checks it against optional bounds.

Name	Type	Description
`$min`	`int`	The minimum allowed value, or null for no minimum.
`$max`	`int`	The maximum allowed value, or null for no maximum.

Returns A validator callable.

ValidateObject

Status::ValidateObject(string $objectName)

Build a validator that parses the value with the named class's FromJson function, returning the resulting object.

Name	Type	Description
`$objectName`	`string`	The class whose FromJson function parses the value.

Returns A validator callable.

ValidatePassword

Status::ValidatePassword(int $minLength = 0, int $maxLength = null)

Build a validator that checks the length of a password and marks the value private, so it is not echoed back on error.

Name	Type	Description
`$minLength`	`int`	The minimum allowed length.
`$maxLength`	`int`	The maximum allowed length, or null for no maximum.

Returns A validator callable.

ValidatePhoneNumber

Status::ValidatePhoneNumber()

Build a validator that checks the value is a valid phone number.

Returns A validator callable.

ValidateString

Status::ValidateString(int $minLength = 0, int $maxLength = null)

Build a validator that checks the length of a string against optional bounds.

Name	Type	Description
`$minLength`	`int`	The minimum allowed length.
`$maxLength`	`int`	The maximum allowed length, or null for no maximum.

Returns A validator callable.

ValidateWithFiles

Status::ValidateWithFiles(array $postData, array $filesData, string $errorUrl, array $validation)

Like Validate, but reads each field from the uploaded files when present, otherwise from the posted data.

Name	Type	Description
`$postData`	`array`	The posted field values, keyed by field name.
`$filesData`	`array`	The uploaded files, keyed by field name.
`$errorUrl`	`string`	The url to redirect to on error.
`$validation`	`array`	A map of field name to a validator callable.

Returns The list of validated values, in field order.

StatusUi

Renders the current status message. Reads the request parameters, verifies the hash, and emits a status element styled by type, or a generic message when the hash does not validate. Renders at most once per page.

Properties

Property	Type	Description
`StatusUi::$alreadyAdded`	`bool`	Whether the message has already been rendered this page; starts false.

Functions

Message

StatusUi::Message()

Render the current status message once, choosing success, error or info styling by type, or a generic message when the hash is invalid.

Returns Nothing; writes the status markup to the output.