Skip to content

Global helper functions

Global Helper Functions

To optimize developer experience and eliminate redundant boilerplate, global helper functions have finally been integrated. These helpers offer immediate and consistent access to core framework components and services. All previously available methods remain fully supported to ensure seamless backward compatibility. The functions below throw a RuntimeException at boot when a function of the same name already exists (except __(), which yields to an existing one).


zubzet()

Returns the main instance of the ZubZet framework, or throws a NotInstantiatedException before it exists.

Syntax: zubzet()


model()

Provides direct access to a specific model instance.

Syntax: model($modelName, $dir = null)

  • $modelName: The name of the model to be instantiated.
  • $dir: Optional directory to load the model from instead of the usual lookup.

Note: In controller actions, $reqObj->getModel($modelName) remains a supported alternative.

Example:

model("Test")->onTest();

request()

Accesses the instance of the current request, or throws a NotInstantiatedException when there is none. It works on a snapshot of the superglobals taken at boot, so later writes to $_GET, $_POST, $_COOKIE or $_SESSION are invisible to it.

Syntax: request()

Example:

request()->getPost("POST_PARAMETER");

response()

Accesses the instance of the current response, the same one that controller constructors, middleware and actions receive.

Syntax: response()

Example:

response()->sendEMail($to, $subject, $document);

config()

Retrieves a configuration value by its key.

Syntax: config(?string $key = null, bool $useDefault = true, mixed $default = null)

  • $key: The configuration identifier. If it is empty, the complete settings array is returned, credentials included.
  • $useDefault: Whether to return a fallback value if the key is not found. Defaults to true; with false, a missing key throws an InvalidArgumentException.
  • $default: The value to return if $useDefault is true and the key is missing. Defaults to null.

Note: $useDefault is the second positional argument, so config("key", 5) does not set a default of 5. Pass the fallback by name: config("key", default: 5).

Note: Previously accessible via $req->getBooterSettings(...) inside controller actions; this approach remains fully supported.

Example:

config("dbusername");

configNumeric()

Retrieves a configuration value that has to be a number.

Syntax: configNumeric(string $key, int $default)

  • $key: The configuration identifier.
  • $default: The value to return if the key is missing.

Note: Non-numeric values are rejected with an InvalidArgumentException instead of being cast. A typo or a value like off would otherwise silently become 0 and disable whatever the setting controls.

Example:

configNumeric("db_max_retries", 3);

configSwitch()

Retrieves a configuration value that switches something on or off, as a boolean.

Syntax: configSwitch(string $key, bool $default)

  • $key: The configuration identifier.
  • $default: The value to return if the key is missing.

On is true, on, yes and 1. Off is false, off, no, 0 and an empty value. The case does not matter, and neither does where the value comes from: an unquoted true in the settings file arrives as 1, a quoted one and an environment variable as the text true, and all of them switch the setting on.

Note: Use it instead of config() for every setting that is a switch. To PHP the text false is truthy, so if(config("feature")) is on for CONFIG_FEATURE=false. Any other value is rejected with an InvalidArgumentException instead of being read as off, so a typo like ture cannot silently disable whatever the setting controls.

Example:

if(configSwitch("newsletter_enabled", false)) {
    // ...
}

user()

Returns the request user, built once per request when the framework is constructed, from the bearer token or the z_login_token cookie. It is also available as $req->getRequestingUser(), $req->booter->user, $opt["user"] in views and as the global alias User, which is not the record class Authentication\Permission\User (import that one with use).

Syntax: user()

Note: This streamlines the previous method of calling $req->getRequestingUser() within controller actions. Check user()->isLoggedIn (true only when token, session and an active z_user row all resolve) to detect anonymous visitors. userId is the account the session acts as (null when anonymous), orgId the user's organization id (null when anonymous or without one), getSessionToken() the current session token (null when anonymous), execUserId the real user behind a login as session (equal to userId for a normal login) and fields the complete z_user row including password, salt, password_scheme and custom columns (empty when anonymous).

Example:

user()->userId;

db()

Provides the database instance for a specified connection, or throws a NotInstantiatedException before it exists.

Syntax: db(string $connection = "default", bool $allowUnsetConnection = false)

  • $connection: The name of the database connection (defaults to "default", any other name throws an InvalidArgumentException).
  • $allowUnsetConnection: Return null instead of throwing while the connection does not exist yet (early in boot).

Note: Database access is no longer restricted to using $this->z_db within models; db(), zubzet()->z_db and $this->z_db are the same shared connection.

Example:

db()->exec("SELECT * FROM z_user");

logger()

Returns a Monolog logger instance for the given channel, or throws a NotInstantiatedException before the framework instance exists.

Syntax: logger(string $name = null)

  • $name: The channel name. Defaults to "app" if omitted.

Loggers are created on first use and cached for subsequent calls with the same name. See Logging for full configuration details.

Example:

logger()->info("Something happened");
logger("payments")->warning("Timeout", ["orderId" => $id]);

view()

Renders a view template directly.

Syntax: view(string $document, array $opt = [], array|string $options = [])

  • $document: The path to the view file.
  • $opt: Data array passed to the view.
  • $options: Additional rendering options, or a layout name as a string.

Note: This serves as a streamlined alternative to rendering via the response object using $resObj->render(...).

Example:

view("adminpanel/dashboard");

encryptSecret()

Encrypts a secret with the encryption_key setting, for example before storing it in the database. See Secrets.

Syntax: encryptSecret(string $plaintext): string

  • $plaintext: The value to encrypt.

Example:

$stored = encryptSecret($secretKey);

decryptSecret()

Decrypts a value created by encryptSecret(). Throws a ZubZet\Framework\Security\Secrets\DecryptionException when the key is wrong or the value is malformed or was modified. See Secrets.

Syntax: decryptSecret(string $encrypted): string

  • $encrypted: A value returned by encryptSecret().

Example:

$secretKey = decryptSecret($stored);

__()

Translates a message id into the active locale. See Translations for the catalogues and how the locale is picked.

Syntax: __(string $id, array $parameters = [], ?string $domain = null, ?string $locale = null): string

  • $id: The message id. An id no catalogue defines is returned unchanged.
  • $parameters: Placeholder values, keyed the way the catalogue spells the placeholder.
  • $domain: The catalogue domain, messages when omitted.
  • $locale: A locale override, the active locale when omitted.

The framework only declares it when no global __() exists yet, so an application or library that brings its own keeps it.

Example:

echo __("dashboard.welcome", ["{name}" => $name]);

deprecated()

Raises a deprecation notice for a code path that still works but should no longer be used. The notice goes through PHP's error handling like a deprecation of PHP itself: with showErrors = 2 it is promoted to an exception, with showErrors = 1 it is logged as a DEPRECATION event and displayed, and with showErrors = 0 it is silent, like every other PHP notice.

Syntax: deprecated(string $version, string $message): void

  • $version: The version the deprecation starts with, e.g. "1.3.0".
  • $message: What is deprecated and what to use instead.

The framework only declares it when no global deprecated() exists yet, so an application or library that brings its own keeps it.

Example:

public function legacyLookup(string $key) {
    deprecated("1.3.0", "legacyLookup() is replaced by lookup(), which also handles prefixed keys");
    return $this->lookup($key);
}

e()

Escapes a string for safe HTML output. It strips tags (everything between < and >, so 1<2 and 3>2 becomes 12) and then escapes the remaining special characters through the render engine, so its output matches what {{ }} produces in a view.

Syntax: e(?string $value): ?string

  • $value: The string to escape. null is passed through unchanged, so optional values can be escaped without an extra check.

Use it whenever a value ends up in HTML outside of a template echo, for example in attributes built in PHP.

shortenStr($str, $maxlength = 10) returns a string that fits unchanged; a longer one is cut to $maxlength characters including the appended ..., word by word and inside the word that no longer fits; getCaller($depth = 1) only works for 0 and 1; var_swap(&$x, &$y) swaps two variables. makeSlug() drops every character outside A-Za-z0-9-_ and space without transliterating, so Größe becomes gre; emptyToNull(&$value) also nulls 0, '0', false, [] and the string null. The global constants TIMESPAN_DAY_n hold n days in seconds (TIMESPAN_DAY_1 is 86400) for n = 1, 2, 3, 7, 10, 14, 20, 21, 30, 60, 90, 180, 182 and 365; the FILE_SIZE_* constants are listed in File Uploads.

Example:

<a title="<?= e($opt["title"]) ?>">