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
$booter
public
ZubZet
$booter
The framework object
$output
public
State
$output
$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
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
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
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
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