Documentation

Response extends RequestResponseHandler
in package
Uses CanRenderView, DefaultLayout

The Response class provides functions used by controllers to respond to requests

Table of Contents

$booter  : ZubZet
$output  : State
$globalDefaultLayoutStack  : array<string|int, mixed>
$instanceDefaultLayoutStack  : array<string|int, mixed>
__construct()  : mixed
cookieSecure()  : bool
Whether the framework's own cookies carry the `Secure` attribute: derived from the configured `host`, so an HTTPS deployment needs no setting and a plain-HTTP one is not locked out.
doCED()  : mixed
Executes a "Create Edit Delete". Per posted row (Z): create inserts, edit updates WHERE id = dbId, delete only sets active = 0; the table needs id and active columns and table/column names are not escaped.
error()  : mixed
Generates a generic error: sends `{"result":"error","message":...}` plus the payload as JSON via generateRest() and exits the script
formErrors()  : mixed
Sends an error array generated by validateForm() from Request. Exit
generateRest()  : void
Echoes the payload as pretty-printed JSON with an added `meta` block. The Content-Type is `application/json` for a client that asks for JSON and `text/plain` for any other, see restContentType()
generateRestError()  : mixed
Generates a Rest error object: logs a REST_ERROR warning, echoes `{"error":{"code","message"}}` as pretty-printed JSON with the Content-Type of generateRest() (no HTTP status is sent) and exits
getBooterSettings()  : mixed
Gets a booter setting
getCookieDomainScope()  : string
getModel()  : Model
Returns a model, one shared instance per request; falls back to the framework models when not found
getZRoot()  : string
Returns the framework root directory
getZViews()  : string
Returns the project's own views directory (config z_views, relative path with trailing slash), not the framework's IncludedComponents views
insertDatabase()  : int|string|null
Inserts a set into the database with data from a form. File fields are uploaded first and array values are stored as JSON.
insertOrUpdateDatabase()  : string|int
Inserts a set into the database with data from a form. Updates if the set already exists
json()  : void
Sends a JSON response.
loginAs()  : mixed
Logs the current user in as someone else, sets the z_login_token cookie and logs the event, without any permission check
logout()  : mixed
Logs the user out: invalidates the DB session and deletes the login cookie (when sudoed, logs in as the exec user instead), then redirects to the root and exits
popDefaultLayout()  : string
popGlobalDefaultLayout()  : string
pushDefaultLayout()  : void
pushGlobalDefaultLayout()  : void
render()  : mixed
Shows a document to the user by echoing it (nothing is returned); a view that fails to render with a BladeException, e.g. a missing one, renders the 500 view instead
reroute()  : mixed
Reroutes to another action by re-dispatching internally, without an HTTP redirect
rerouteUrl()  : mixed
Reroutes at the user's client by sending a Location header and exiting
sendEmail()  : mixed
Sends an email to an address
sendEmailToUser()  : bool
Sends an email to a user
setCookie()  : mixed
Sets a cookie just like the standard PHP function. (Pass-through) The arguments are read via func_get_args() and forwarded unchanged; the result of setcookie() is discarded.
setDefaultLayout()  : void
setFrameworkCookie()  : void
setGlobalDefaultLayout()  : void
success()  : mixed
Sends a success message to the client. Exit
unsetCookie()  : mixed
Removes a cookie at the client and from the current request's input
updateDatabase()  : mixed
Updates a database row with data from a user-filled form
upload()  : Upload
Creates an upload object that handles the rest of the upload.
resolveDefaultLayout()  : string
deleteOldLoginCookieDomainScope()  : void
Deletes the login token for the domain specified in `login_scope_allow_subdomains_delete_domainscope_name`.
getNewRest()  : Rest
Gets a new Rest object
legacyOptExpansion()  : array<string|int, mixed>
restContentType()  : string
The Content-Type of a REST reply. PHP's default text/html would let markup inside a value run in a browser that opens the endpoint, so it is never that.
sendRestContentType()  : void
uploadFromForm()  : mixed

Properties

$globalDefaultLayoutStack

private static array<string|int, mixed> $globalDefaultLayoutStack = []

$instanceDefaultLayoutStack

private array<string|int, mixed> $instanceDefaultLayoutStack = []

Methods

__construct()

public __construct() : mixed
Return values
mixed —

cookieSecure()

Whether the framework's own cookies carry the `Secure` attribute: derived from the configured `host`, so an HTTPS deployment needs no setting and a plain-HTTP one is not locked out.

public cookieSecure() : bool
Return values
bool —

doCED()

Executes a "Create Edit Delete". Per posted row (Z): create inserts, edit updates WHERE id = dbId, delete only sets active = 0; the table needs id and active columns and table/column names are not escaped.

public doCED(string $table, Result $validationResult[, array<string|int, mixed> $fix = [] ]) : mixed
Parameters
$table : string

The name of the affected table in the database

$validationResult : Result

The result of a validated CED

$fix : array<string|int, mixed> = []

Fixed values. For example, fix user ID not set by the client

Return values
mixed —

error()

Generates a generic error: sends `{"result":"error","message":...}` plus the payload as JSON via generateRest() and exits the script

public error([string $message = "" ][, array<string|int, mixed> $payload = [] ]) : mixed
Parameters
$message : string = ""

An error message

$payload : array<string|int, mixed> = []

An optional payload that will be added to the result

Return values
mixed —

formErrors()

Sends an error array generated by validateForm() from Request. Exit

public formErrors(array<string|int, array<string|int, mixed>> $errors) : mixed
Parameters
$errors : array<string|int, array<string|int, mixed>>

The error array, a list of ["name" => ..., "type" => ...] entries. Further error arrays can be passed as extra arguments and are merged; non-array arguments are ignored.

Return values
mixed —

generateRest()

Echoes the payload as pretty-printed JSON with an added `meta` block. The Content-Type is `application/json` for a client that asks for JSON and `text/plain` for any other, see restContentType()

public generateRest(array<string|int, mixed> $payload[, bool $die = true ]) : void
Parameters
$payload : array<string|int, mixed>

Data payload

$die : bool = true

Whether to exit after echoing, true by default

Return values
void —

generateRestError()

Generates a Rest error object: logs a REST_ERROR warning, echoes `{"error":{"code","message"}}` as pretty-printed JSON with the Content-Type of generateRest() (no HTTP status is sent) and exits

public generateRestError(string $code, string $message) : mixed
Parameters
$code : string

Code

$message : string

Error message

Return values
mixed —

getBooterSettings()

Gets a booter setting

public getBooterSettings([string|null $key = null ][, bool $useDefault = true ][, mixed $default = null ]) : mixed
Parameters
$key : string|null = null

Key of the setting, null or empty returns all settings

$useDefault : bool = true

Return $default instead of throwing when the key does not exist

$default : mixed = null

Value returned for a missing key when $useDefault is true

Tags
throws
InvalidArgumentException

If the key does not exist and $useDefault is false

Return values
mixed —

Value of the key

getCookieDomainScope()

public getCookieDomainScope() : string
Return values
string —

getModel()

Returns a model, one shared instance per request; falls back to the framework models when not found

public getModel(string $model[, string|null $dir = null ]) : Model
Parameters
$model : string

Name of the model, sub-folders dot separated (e.g. "admin.User")

$dir : string|null = null

Set this when the model is stored in a specific directory, needs a trailing slash

Tags
throws
Exception

When the model does not exist

Return values
Model —

The model

getZRoot()

Returns the framework root directory

public getZRoot() : string
Return values
string —

getZViews()

Returns the project's own views directory (config z_views, relative path with trailing slash), not the framework's IncludedComponents views

public getZViews() : string
Return values
string —

insertDatabase()

Inserts a set into the database with data from a form. File fields are uploaded first and array values are stored as JSON.

public insertDatabase(string $table, Result $validationResult[, array<string|int, mixed> $fixed = [] ]) : int|string|null
Parameters
$table : string

Table name in the database

$validationResult : Result

Result of the validation

$fixed : array<string|int, mixed> = []

Some values to add to the database that were not in the FormResult

Return values
int|string|null —

Id of the inserted set

insertOrUpdateDatabase()

Inserts a set into the database with data from a form. Updates if the set already exists

public insertOrUpdateDatabase(string $table, string $pkField, string $pkType, string|int $pkValue, Result $validationResult[, array<string|int, mixed> $fixed = [] ]) : string|int
Parameters
$table : string

Table name in the database

$pkField : string

Name of the primary key field in the database

$pkType : string

Type of the primary key field ("s"/"i"...)

$pkValue : string|int

Value of the primary key in the row to change

$validationResult : Result

Result of the validation

$fixed : array<string|int, mixed> = []

Fixed values to add, which are not coming from the form

Return values
string|int —

The given $pkValue after an update, the new insert id after an insert

json()

Sends a JSON response.

public json(mixed $data, int $encodingOptions) : void

Sets Content-Type: application/json and emits $data JSON-encoded without exiting (unlike generateRest()), so any later output is appended to the JSON.

Parameters
$data : mixed

The value to encode as JSON.

$encodingOptions : int

Bitmask of json_encode() options (e.g. JSON_PRETTY_PRINT).

Tags
throws
JsonException

If encoding fails. Note that JSON_THROW_ON_ERROR is automatically added to $encodingOptions.

Return values
void —

loginAs()

Logs the current user in as someone else, sets the z_login_token cookie and logs the event, without any permission check

public loginAs(int $userId[, int|null $user_exec = null ][, string|null $name = null ][, string|null $reason = null ][, bool $recordTwoFactor = false ]) : mixed
Parameters
$userId : int

ID of the user to sudo into

$user_exec : int|null = null

ID of the executing user, null makes it a normal login as $userId

$name : string|null = null

An optional name for the session

$reason : string|null = null

Why the session was created, e.g. why an admin impersonates

$recordTwoFactor : bool = false
Return values
mixed —

logout()

Logs the user out: invalidates the DB session and deletes the login cookie (when sudoed, logs in as the exec user instead), then redirects to the root and exits

public logout() : mixed
Return values
mixed —

popDefaultLayout()

public popDefaultLayout() : string
Return values
string —

popGlobalDefaultLayout()

public static popGlobalDefaultLayout() : string
Return values
string —

pushDefaultLayout()

public pushDefaultLayout(string $layout) : void
Parameters
$layout : string
Return values
void —

pushGlobalDefaultLayout()

public static pushGlobalDefaultLayout(string $layout) : void
Parameters
$layout : string
Return values
void —

render()

Shows a document to the user by echoing it (nothing is returned); a view that fails to render with a BladeException, e.g. a missing one, renders the 500 view instead

public render(string $document[, array<string|int, mixed> $opt = [] ][, string|array<string|int, mixed> $options = [] ]) : mixed
Parameters
$document : string

Path to the view

$opt : array<string|int, mixed> = []

Associative array with values to replace in the view; response, request, user, root, host, absRoot and title are added to it as $opt in the view

$options : string|array<string|int, mixed> = []

Rendering options, e.g., or a string for layout

Return values
mixed —

reroute()

Reroutes to another action by re-dispatching internally, without an HTTP redirect

public reroute([array<string|int, string> $path = [] ][, bool $alias = false ][, bool $final = false ]) : mixed
Parameters
$path : array<string|int, string> = []

Path to where to reroute to

$alias : bool = false

True if $path is overlaid onto the current URL parts (index by index) before dispatching

$final : bool = false

Executes and exits if set to true

Return values
mixed —

rerouteUrl()

Reroutes at the user's client by sending a Location header and exiting

public rerouteUrl([string $url = "" ][, string $root = null ]) : mixed
Parameters
$url : string = ""

The URL to reroute to, appended directly to $root

$root : string = null

The root URL, defaults to the app's rootFolder

Return values
mixed —

sendEmail()

Sends an email to an address

public sendEmail(string $to, string $subject, string $document[, string $lang = "en" ][, array<string|int, mixed> $options = [] ][, string $layout = "email" ][, array<string|int, string> $attachments = [] ][, string|null $senderName = null ]) : mixed
Parameters
$to : string

Mail address

$subject : string

Subject of the mail

$document : string

View

$lang : string = "en"

Language identifier ("EN", "DE_Formal"...)

$options : array<string|int, mixed> = []

Options to use in the view

$layout : string = "email"

Layout name: ".php" is stripped, "_layout" is appended, and "layout/" is prefixed unless that path exists in the app views ("mail" -> layout/mail_layout). The default "email" needs an app layout/email_layout; the framework only ships mail_layout

$attachments : array<string|int, string> = []

Contents of each attachment, not their path. Array keys can be used to set the filename i.e. $filename => $content

$senderName : string|null = null

Display name of the sender, defaults to the pageName

Return values
mixed —

sendEmailToUser()

Sends an email to a user

public sendEmailToUser(int $userId, string|array<string|int, mixed> $subject, string $document[, array<string|int, mixed> $options = [] ][, string $layout = "mail" ]) : bool
Parameters
$userId : int

ID of the target user

$subject : string|array<string|int, mixed>

Subject of the mail, or an array keyed by language code

$document : string

View of the mail

$options : array<string|int, mixed> = []

Options for use in the view

$layout : string = "mail"

Layout to use

Tags
throws
Exception

If the user is not found or has no email address

Return values
bool —

True if the mail was sent, false if sending failed

setCookie()

Sets a cookie just like the standard PHP function. (Pass-through) The arguments are read via func_get_args() and forwarded unchanged; the result of setcookie() is discarded.

public setCookie() : mixed

See: https://www.php.net/manual/en/function.setcookie.php

Return values
mixed —

setDefaultLayout()

public setDefaultLayout(string $layout) : void
Parameters
$layout : string
Return values
void —

setFrameworkCookie()

public setFrameworkCookie(string $name, string $value, int $lifetime) : void
Parameters
$name : string
$value : string
$lifetime : int
Return values
void —

setGlobalDefaultLayout()

public static setGlobalDefaultLayout(string $layout) : void
Parameters
$layout : string
Return values
void —

success()

Sends a success message to the client. Exit

public success([array<string|int, mixed> $payload = [] ]) : mixed
Parameters
$payload : array<string|int, mixed> = []

An optional payload that will be added to the result

Return values
mixed —

unsetCookie()

Removes a cookie at the client and from the current request's input

public unsetCookie(string $name[, string $path = "/" ][, string $domainScope = "" ]) : mixed
Parameters
$name : string

Name of the cookie

$path : string = "/"

Path on the server, must match the one used when setting the cookie

$domainScope : string = ""

The domain scope of the cookie, must match the one used when setting the cookie

Return values
mixed —

updateDatabase()

Updates a database row with data from a user-filled form

public updateDatabase(string $table, string $pkField, string $pkType, string $pkValue, Result $validationResult[, array<string|int, mixed> $fixed = [] ]) : mixed
Parameters
$table : string

Table name in the database

$pkField : string

Name of the primary key field in the database

$pkType : string

Type of the primary key field ("s"/"i"...)

$pkValue : string

Value of the primary key in the row to change

$validationResult : Result

Result of the validation

$fixed : array<string|int, mixed> = []

Extra column => value pairs to write, bound as strings. File fields are uploaded first and array values are stored as JSON.

Return values
mixed —

upload()

Creates an upload object that handles the rest of the upload.

public upload() : Upload
Return values
Upload —

A new instance of the Upload class

resolveDefaultLayout()

protected resolveDefaultLayout() : string
Return values
string —

deleteOldLoginCookieDomainScope()

Deletes the login token for the domain specified in `login_scope_allow_subdomains_delete_domainscope_name`.

private deleteOldLoginCookieDomainScope() : void

Helpful when login_scope_allow_subdomains is altered after users already logged in.

Return values
void —

getNewRest()

Gets a new Rest object

private getNewRest(array<string|int, mixed> $payload) : Rest
Parameters
$payload : array<string|int, mixed>

Data payload

Return values
Rest —

legacyOptExpansion()

private static legacyOptExpansion(array<string|int, mixed> $opt) : array<string|int, mixed>
Parameters
$opt : array<string|int, mixed>
Return values
array<string|int, mixed> —

restContentType()

The Content-Type of a REST reply. PHP's default text/html would let markup inside a value run in a browser that opens the endpoint, so it is never that.

private restContentType() : string

A client that names application/json in its Accept header gets it. Any other client gets text/plain: jQuery parses a reply sent as application/json itself, and code that calls JSON.parse() on the answer of a plain $.post() would then be handed an object.

Return values
string —

sendRestContentType()

private sendRestContentType() : void
Return values
void —

uploadFromForm()

private uploadFromForm(Result $validationResult) : mixed
Parameters
$validationResult : Result
Return values
mixed —

Search results