PHP Luminova: Global Utility Helper Functions

Global helper functions are procedural functions that provide commonly used functionality across different parts of your application. They are typically defined at the global scope, making them easily accessible from anywhere within the codebase.

Code Reusability

By encapsulating commonly used operations into helper functions, developers can avoid repetitive code and promote code reuse.

Productivity

Helper functions can significantly improve development efficiency by providing pre-built solutions to common problems. Instead of reinventing the wheel each time a similar task needs to be performed.

Abstraction of Complexity

Helper functions abstract away the complexity of certain operations, making the code-base more readable and maintainable. By encapsulating logics within well-named functions, developers can focus on the high-level functionality of their code without getting bogged down in implementation details.

Functions

app

Get application container class shared instance or new instance if not shared.

function app(): \App\Application

Return Value:

\Luminova\Core\CoreApplication<\App\Application> - Return application shared instance.

See Also

Core Application - See the documentation for base application methods and usages.

Note: Avoid re-initializing application class if possible, always use the app function or grab the shared instance of your application by Application::getInstance()

request

Retrieve a shared or new instance of HTTP request object.

function request(bool $shared = true): HttpRequestInterface

Parameters:

Return Value:

\Luminova\Interface\HttpRequestInterface - Returns an incoming HTTP request object.

See Also

HTTP Request - See the documentation for http request methods and usages.

session

Return session data if key is present, otherwise return the session class instance.

function session(?string $key = null, bool $shared = true, ?\Luminova\Interface\SessionManagerInterface $manager = null): mixed

Parameters:

Return Value:

\Luminova\Sessions\Session|mixed - The session data if key is provided, otherwise the session class instance.

See Also

Session Manager - See the documentation for session methods.

cookie

Create and return a cookie instance.

function cookie(string $name, string $value = '', array $options = [], bool $shared = false): \Luminova\Cookies\Cookie

Parameters:

Return Value:

Cookie - Return new cookie instance.

See Also

Client Cookie Manager - See the documentation for client-side cookie methods.

factory

To initialize a class available in factory and returns a shared instance of the class.Optionally you can pass NULL to context parameter in other to return factory instance instead.

function factory(string|null $context = null, bool $shared = true, mixed ...$arguments): ?object

Parameters:

Return Value:

class-object<\T>|Factory|null - Return instance of factory class, instance of class called, otherwise null.

Throws:

• \Luminova\Exceptions\AppException - Throws an exception if factory context does not exist or error occurs.

Available Factory Context Names

• 'task' - Returns instance of \Luminova\Time\Task
• 'session' - Returns instance of \Luminova\Sessions\Session
• 'cookie' - Returns instance of \Luminova\Cookies\Cookie
• 'functions' - Returns instance of \Luminova\Base\CoreFunction
• 'modules' - Returns instance of \Luminova\Library\Modules
• 'language' - Returns instance of \Luminova\Languages\Translator
• 'logger' - Returns instance of \Luminova\Logger\Logger
• 'fileManager' - Returns instance of \Luminova\Storages\FileManager
• 'validate' - Returns instance of \Luminova\Security\Validation
• 'response' - Returns instance of \Luminova\Template\Response
• 'services' - Returns instance of \App\Config\Services
• 'request' - Returns instance of \Luminova\Http\Request
• 'notification' - Returns instance of \Luminova\Notifications\Firebase\Notification
• 'caller' - Returns instance of \Luminova\Application\Caller
• 'escaper' - Returns instance of \Luminova\Functions\Escape

Example

This example shows how to initialize session class instance with a new constructor argument using factory.

<?php 
$session = factory('session', false, new SessionManager());

See Also

Application Factory - See the documentation for factory methods and usages.

service

Service on the other hand focus more on your business logic, It allows you to returns a shared instance of a class registered in your service bootstrap method. To return an instance of service pass null as the service parameter.

function service(class-string<\T>|string|null $service = null, bool $shared = true, bool $serialize = false, mixed ...$arguments): ?object

Parameters:

Return Value:

class-object<\T>|Services|null - Return service class instance or instance of called class.

Throws:

• \Luminova\Exceptions\AppException - Throws an exception if service does not exist or error occurs.

  See Also

Application Service - See the documentation for service methods and usages.

remove_service

Delete a service or clear all services.

function remove_service(class-string<\T>|string|null  $service = null): bool

If NULL is passed all cached and serialized services will be cleared.

Parameters:

Return Value:

bool - Return true if the service was removed or cleared, false otherwise.

layout

PHP Template layout helper class, to extend, inherit and import layout sections while using default template engine.

function layout(string $file): \Luminova\Template\Layout

Parameters:

Return Value:

\Luminova\Template\Layout - Returns the layout class instance.

Throws:

• \Luminova\Exceptions\RuntimeException -Throws if layout file is not found.

See Also

Template Layout - See the documentation for default PHP template layout methods and usages.

All layouts must be stored in resources/Views/layout/ directory.Examples: layout('foo') or layout('foo/bar/baz')

response

Initiate a view response object and render any response content.It allows you to render content of any format in view or download content within the view controller.

function response(int $status = 200, ?array $headers = null, bool $shared = true): ViewResponseInterface

Parameters:

Return Value:

\Luminova\Interface\ViewResponseInterface - Return vew response object.

See Also

View the Response Class documentation for detailed information on methods and usage examples.

func

Return instance a specific context if specified, otherwise get the instance anonymous class which extended CoreFunction.

function func(string|null $context = null, mixed ...$arguments): mixed

Parameters:

Supported contexts:

• ip - Return instance of Luminova\Functions\IP.
• document - Return instance of Luminova\Functions\IP.
• tor - Return instance of Luminova\Functions\Tor,
• math - Return instance of Luminova\Functions\Maths.

Return Value:

class-object<CoreFunction>|class-object<\T>|mixed - Returns an instance of Functions, object, string, or boolean value depending on the context.

Throws:

• \Exception - If an error occurs.
• \Luminova\Exceptions\RuntimeException - If unable to call method.

See Also

Core Functions - Learn more about the Luminova's CoreFunction documentation.

shared

Temporarily stores and retrieves values within the same scope.It allows you to set and get shared values. It uses a static array to store the shared preference, which persists across multiple calls to the function within the same script execution.

function shared(string $key, mixed $value = null, mixed $default = null): mixed

Parameters:

Return Value:

mixed - Returns the value associated with the key, or default value if the key does not exist.

browser

Get the information about user's browser, based on the user-agent string.

function browser(?string $user_agent = null, string $return = 'object', bool $shared = true): mixed

Parameters:

Return Value:

array<string,mixed>|object<string,mixed>|UserAgent|false - An array, object containing browser information or user-agent class instance.

See Also

User Agents - See the documentation for browser user-agent methods and usages.

href

Create a hyperlink to another view or file.This function creates a link to a view or file, ensuring the base starts from your application's public document root.

function href(?string $view = null, bool $absolute = false): string 

Parameters:

Return Value:

string - Return link of view, If $absolute is true, the absolute URL is returned; otherwise, a relative URL is returned.

If an absolute URL is requested, concatenates the base URL (APP_URL) with the view path.If a relative URL is requested, it concatenates it with the view path.

asset

Create a link to a file in the assets folder.This function generates a URL to a file within the assets folder, ensuring the base starts from your application's public document root.

function asset(?string $filename = null, bool $absolute = false): string 

Parameters:

Return Value:

string - Return asset link of view, If $absolute is true, the absolute URL is returned; otherwise, a relative URL is returned.

root

Get the application root directory of your project anywhere, optionally pass a path to append the the root directory, all return path will be converted to unix or windows directory separator style.

function root(?string $suffix = null): string

Parameters:

Return Value:

string - Return application document root, and optional appended suffix.

path

Get system or application path, compatible with unix or windows directory separator style.

function path(string $file): string

Parameters:

Return Value:

string - Return directory path, windows, unix or windows style path.

See Also

File Manager - Also checkout the documentation for file manager methods and usages.

env

Get environment variable value from registered ENV variables, its a wrapper that combines both $_ENV, $_SERVER and getenv, with an additional feature to ensure the accuracy of the return type and default value if the key was not found in the environment.

function env(string  $key, mixed  $default = null): mixed

Parameters:

Return Value:

mixed - Return the value of the specified environment key or default value if not found.

See Also

Environment Variables - Learn more from documentation about Luminova's env variable keys.

If your variable value is like: foo = [1, 2, 4], this function will return an array representation of the value.

setenv

Set an environment variable if it doesn't already exist.

function setenv(string $key, string $value, bool $append_to_env = false): bool

Parameters:

Return Value:

bool - Return true on success, otherwise false on failure.

By default when you set an environment variable, it doesn't permanently stored in other to access it in entire code-base.

If you wish to write the key and value in your environment variables file .env, then you must specify the third argument true.

More efficient method of doing this is by utilizing the NovaKit Command to write the key and value to env file. using command php novakit env:add --key="my_new_key" --value="my key value".

import

Import a custom library into your project.

function  import(string $library): bool

Parameters:

Throws:

• \Luminova\Exceptions\RuntimeException - If the library could not be found

Return Value:

bool - Return true if the library was successfully imported.

You must place your external libraries in libraries/libs/ directory in other to use file import.

logger

Logs a message to a specified destination using the configured preferred PSR logger class if define in App\Config\Preference, otherwise it will use default Luminova\Logger\NovaLogger.

The destination can be a log level, email address, or URL endpoint. This function delegates the logging action to the dispatch method, which handles the asynchronous or synchronous execution as needed.

function logger(string $to, string $message, array $context = [], bool $asynchronous = false): void

Parameters:

Log levels

• emergency - Log urgent errors requiring immediate attention.
• alert - Log important alert messages.
• critical - Log critical issues that may disrupt application functionality.
• error - Log minor errors.
• warning - Log warning messages.
• notice - Log messages that require attention but are not urgent.
• info - Log general information.
• debug - Log messages for debugging purposes.
• exception - Log exception messages.
• php_errors - Log PHP-related errors.
• metrics - Log performance metrics for APIs.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - Throws if an error occurs while logging or an invalid destination is provided.

All non-network and email logs are located in /writeable/log/, each log level has it own file name (e.g, warning.log).

To set your own logging handler class, it can be done in App\Config\Preference, your logger must implement PSR logger interface.

locale

Set application locale or return current application local.

function locale(?string $locale = null): string|bool

Parameters:

Return Value:

string|bool - If locale is passed it will set it and return true, else return previous locale.

uuid

Generates a UUID string of the specified version such as 1, 2, 3, 4, or 5.

function uuid(int $version = 4, ?string $namespace = null, ?string $name = null): string 

Parameters:

Return Value:

string -Return the generated UUID string.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - f the namespace or name is not provided for versions 3 or 5.

To check if UUID is valid use func()->isUuid(string, version)

escape

Escapes a string or array of strings based on the specified context.

This is particularly useful when dealing with escaping and sanitizing inputs and output to prevent cross-site scripting (XSS) and other injection attacks, the escape context parameter accept values like html, js, css, url, attr, and raw are used to specify the context in which the data is being output. Each context requires different escaping rules to ensure the output is safe.

function escape(string|array $input, string $context = 'html', string|null $encoding = 'utf-8'): array|string

Parameters:

Throws:

• \Luminova\Exceptions\InvalidArgumentException - When an invalid, blank encoding is provided or unsupported encoding or empty string is provided.
• \Luminova\Exceptions\BadMethodCallException - When an invalid context is called.

Return Value:

array|string - Return the escaped string or array of strings.

Input Argument

• Associative Array array<string, string>: Use the keys of the array to specify the escape context for each value. Each key-value pair determines the context in which the corresponding value should be escaped.

• Indexed Array array<int, string>: Apply the default escape context to all values in the array. The default context will be used for escaping each value uniformly.

Supported Context

Context names and a brief explanation of each:

1. html:

   • Purpose: Escapes characters that could be interpreted as HTML tags or entities. It replaces characters like <, >, and & with their corresponding HTML entities (<, >, &), ensuring that they are displayed as plain text and not interpreted as HTML.

2. js:

   • Purpose: Escapes characters that have special meanings in JavaScript, such as quotes and backslashes, to prevent injection attacks when inserting data into JavaScript strings or variables.

3. css:

   • Purpose: Escapes characters that could affect CSS styling or lead to CSS injection attacks, such as special characters in style attributes or css rules.

4. url:

   • Purpose: Escapes characters that are not valid in URLs or could break URL structure. This ensures that user-provided data included in URLs does not lead to unexpected behavior or vulnerabilities.

5. attr:

   • Purpose: Escapes characters that could interfere with HTML attributes, such as quotes and angle brackets, to prevent breaking out of the attribute value or introducing additional attributes.

6. raw:

   • Purpose: No escaping is applied; the data is output as-is. This is used when you are certain that the data is safe and does not need to be sanitized.

strict

Sanitize user input by removing disallowed characters, retaining only those permitted. Unlike the escape function, which encodes characters for safe output, the strict function replaces unwanted characters in the input string with $replacer and returns the sanitized value. This method is particularly useful when you need to enforce strict input validation, ensuring that only expected characters are present.

function strict(string $input, string $type = 'default', string $replacer = ''): string

Parameters:

Filters Types

• int: Accepts only integer values.
• digit: Accepts only digit values including decimals and negatives.
• key: Accepts only alphanumeric characters, underscores, and dashes.
• password: Accepts alphanumeric characters, underscores, dashes, and special characters: @, !, *, and _.
• username: Accepts alphanumeric characters, underscores, dashes, and periods.
• email: Accepts valid email addresses containing alphanumeric characters, underscores, dashes, periods, and @.
• url: Accepts valid URLs containing alphanumeric characters, underscores, dashes, periods, question marks, hashtags, ampersands, plus signs, equal signs, colons, slashes, and spaces.
• money: Accepts only numeric values, including decimals and negative numbers.
• double: Accepts only numeric values, including decimals.
• alphabet: Accepts only alphabetical characters (uppercase and lowercase).
• phone: Accepts only phone numbers containing numeric characters, dashes, and plus signs.
• name: Accepts names containing letters, digits, spaces, underscores, periods, apostrophes, and hyphens.
• timezone: Accepts valid timezone strings containing alphanumeric characters, underscores, dashes, commas, colons, plus signs, and spaces.
• time: Accepts valid time strings containing alphanumeric characters, dashes, colons, and spaces.
• date: Accepts valid date strings containing alphanumeric characters, dashes, colons, slashes, commas, and spaces.
• uuid: Accepts valid UUID strings in the format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
• default: Removes any HTML tags from the input string.

Return Value:

string - Return sanitized string.

lang

Translate multiple languages with support for nested arrays.

function lang(string $lookup, string|null $default = null, string|null $locale = null, array $placeholders = []): string

Parameters:

Return Value:string - The translated text.

Throws:

• \Luminova\Exceptions\NotFoundException - If translation is not found and no default is provided.

To create a language translations you need to define it in /app/Languages/.

The file name format should be like Example.en.php, where the Example is the context and en is the locale.

See Also

Translations - See the documentation for translation methods and usages.

Example.en.php

return [
    'error' => 'Error your example encountered error',
    'users' => [
        'notFound' => 'Username "{username}" does not exist.',
        'password' => 'Error your password {0} doesn\'t match with {1}'
    ]
];

Assuming your application locale is already set to EN.

<?php
echo  lang('Example.error'); // Error your example encountered error

<?php
echo  lang('Example.error.users.notFound', null, null, [
    'username' => "peterujah"
]); 
// Username "peterujah" does not exist.

<?php
echo  lang('Example.error.users.password', null, null, [
    '12345@199',
    "12345@123"
]); 
// Error your password 12345@199 doesn't match with 12345@123

configs

Retrieves the configurations for the specified context.This function can only be use to return configuration array stored in app/Configs/ directory.

function configs(string $filename, array|null $default = null): ?array

Parameters:

Return Value:

array|null - Return array of the configurations for the filename, or false if not found.

cache

Initialize or retrieve a new instance of the cache class.

function cache(string $driver, ?string $storage = null, ?string $persistentIdOrSubfolder = null): \Luminova\Base\BaseCache

Parameters:

Persistent Id Or Subfolder Param

• For Memcached: A unique persistent connection ID. If null, the default ID from environment variables is used, or default if not set.
• For Filesystem Cache: A subdirectory within the cache directory. If null, defaults to the base cache directory.

Return Value:

\Luminova\Base\BaseCache - Return new instance of instance of FileCache or MemoryCache cache based on specified driver.

Throws:

• \Luminova\Exceptions\ClassException - If unsupported driver is specified.
• \Luminova\Exceptions\CacheException - If there is an issue initializing the cache.
• \Luminova\Exceptions\InvalidArgumentException - If an invalid subdirectory is provided for the filesystem cache.

write_content

Write or append string contents or stream to file.This function is an alternative for file_put_contents, it uses SplFileObject to write contents to file.

function write_content(string $filename, string|resource  $content, int  $flag, resource $context = null): bool

Parameters:

Return Value:

boo - Return true if successful, otherwise false on failure.

Throws:

• \Luminova\Exceptions\FileException - If unable to write file.

See Also

File Manager - Also checkout the documentation for file manager methods and usages.

get_content

Reads the content of a file with options for specifying the length of data to read and the starting offset.This function is an alternative for file_get_contents, it uses SplFileObject to open the file and read its contents.It can handle reading a specific number of bytes from a given offset in the file.

function get_content(string $filename, int $length = 0, int $offset = 0,  bool $useInclude = false,  $context = null): string|bool;

Parameters:

Return Value:

string|false - Returns the contents of the file as a string, or false on failure.

Throws:

• \Luminova\Exceptions\FileException - If unable to write file.

make_dir

Attempts to create the directory specified by pathname if it does not exist.

function make_dir(string  $path, int|null  $permissions = null, bool  $recursive = true): bool

Parameters:

Return Value:

bool - Return true if files already existed or was created successfully, otherwise false.

Throws:

• \Luminova\Exceptions\FileException - If unable to create directory.
• \Luminova\Exceptions\RuntimeException - If the path is not readable.

See Also

File Manager - Also checkout the documentation for file manager methods and usages.

get_temp_file

Retrieves the path for temporary files or generates a unique temporary file name.

This function can return either the path to a temporary directory or a unique temporary filename with an optional specified extension. If local is set to true, it will create the directory in the local writable path. If extension is provided, the returned filename will have that extension.

function get_temp_file(?string $prefix = null, ?string $extension = null, bool $local = false): string|false

Parameters:

Return Value:

string|false - Returns the path of the temporary directory, a unique temporary filename with the specified extension, or false on failure.

validate

Validate user input fields or get a validation instance.

function validate(?array $inputs = null, ?array $rules = null, array $messages = []): Luminova\Interface\ValidationInterface

Parameters:

Return Value:

ValidationInterface - Return validation instance if NULL is passed on $inputs or $rules.

See Also

Input Validations - Also checkout the documentation for input validation methods and usages.

Sample Usages

Assuming you have a post or get request like below:

<?php 
    $inputs = [
        'name' => 'Peter',
        'email' => '[email protected]',
    ];

Configure validation rules as below:

```php
$rules = [
    'name' => 'require|alphanumeric|max(50)',
    'email' => 'require|email'
];
$messages = [
    'name' => [
        'require' => 'Name is required',
        'alphanumeric' => 'Invalid name character',
        'max' => 'Invalid name cannot be more than 50 character'
    ],
    'email' => [
        'require' => 'Email is required',
        'email' => 'Invalid email address "{value}"'
    ]
];

Validating request against rules.

```php
    $validation = validate($inputs, $rules, array $messages);

    if($validation->isPassed()){
        echo 'Success';
    }else{
        echo 'Error: ' . $validation->getErrorLine();
        var_export($validation->getErrors());
    }

start_url

Get the start URL with an optional suffix and port hostname if available.This function generates the base URL of the application, optionally appending a provided suffix. It includes the port hostname if available.

function start_url(?string $suffix = null): string

Parameters:

Return Value:

string Return the generated start URL of your project.

ExampleIf your application path is like: /Some/Path/To/htdocs/my-project-path/public/.It returns depending on your development environment and suffix if specified:

• https://localhost:8080
• https://localhost/my-project-path/public/
• https://localhost/public
• https://example.com:8080
• https://example.com/

If the application is in production (PRODUCTION), it returns the base application URL (APP_URL) with the optional suffix.If not in production, it constructs the URL using the server's hostname and the PROJECT_ID, and appends the optional suffix.

absolute_url

Convert an application-relative path to an absolute URL.This function converts a given application-relative path to its corresponding absolute URL.

function absolute_url(string $path): string

Parameters:

Return Value:

string - Return the absolute URL of the specified path.

Examples:

If on development environment.

<?php 
echo absolute_url('/Applications/XAMPP/htdocs/project-base/public/asset/files/foo.text');
//Output: http://localhost/project-base/public/asset/files/foo.text.

If on projection environment.

<?php 
echo absolute_url('/example.com/www/public/asset/files/foo.text');
//Output: http://example.com/asset/files/foo.text.

ip_address

Retrieve the user's IP address or obtain IP address information using a third-party API service.

function ip_address(bool $ip_info = false, array $options = []): string|object|null

Parameters:

Return Value:

string|object|null - The IP address if $ip_info is false, else return IP address information or null if IP address cannot be determined.

Utilize a third-party API to fetch IP address information. Your API configuration can be done in /app/Config/IPConfig.php.

get_class_name

Get class basename from namespace or class object.

function get_class_name(string|object $from): string

Parameters:

Return Value:

string - Return the class basename.

Note: This method is not same as PHP get_class, this method return the base name of a class no full qualified class.

get_mime

Detect MIME content type of a given file, (e.g text/plain).

function get_mime(string $filename): string|false

Parameters:

Return Value:

string|false - Return the content type in MIME format, otherwise false.

get_column

Return the values from a single column in the input array or an object.

function get_column(array|object $from, null|string|int $property, null|string|int $index = null): array 

Parameters:

Return Value:

array - Returns an array of values representing a single column from the input array or object.

This function is a wrapper for PHP array_column, but with additional optimization to handle both object or an array column.

filter_paths

Filter the display path, to remove private directory paths before previewing to users.

function filter_paths(string $path): string

Parameters:

Return Value:

string - Return the filtered path.

This method is useful when you want to throw an exceptions, use it to remove your server path and return only path which should be seen by users.

to_array

Convert an object to an array.

function to_array(mixed  $input): array

Parameters:

Return Value:

array - The finalized array representation of the object.

to_object

Convert an array or string list to a JSON object.

function to_object(array|string $input): object|false

Parameters:

Return Value:

object|false - Return JSON object, otherwise false.

array_extend_default

This function is designed to merge two arrays, where the first array ($default) represents default values, and the second array ($new) contains updated or new values. The function recursively merges arrays for keys that exist in both arrays but leaves the default values untouched if no corresponding value is found in $new.

function array_extend_default(array $default, array $new): array

Parameters:

Return Value:

array - Return the merged options array with defaults preserved.

Usage Examples:

$default = ['a' => 1, 'b' => 2, 'c' => 3];
$new = ['b' => 20, 'd' => 4];

$result = array_extend_default($default, $new);
print_r($result);

Output:

Array
(
    [a] => 1
    [b] => 2
    [c] => 3
    [d] => 4
)

array_merge_recursive_replace

This function is designed to merge multiple arrays recursively, but with a replacement strategy. If two arrays have the same key, the values in the second array will overwrite those in the first array. For numeric keys, it appends the values only if they don't already exist in the array.

public array_merge_recursive_replace(array ...$array): array

Parameters:

Return Value:

array - Return the merged result array.

Usage Examples:

$array1 = ['a' => 1, 'b' => 2, 'c' => 3];
$array2 = ['b' => 20, 'd' => 4];

$result = array_merge_recursive_replace($array1, $array2);
print_r($result);

Output:

Array
(
    [a] => 1
    [b] => 20
    [c] => 3
    [d] => 4
)

array_merge_recursive_distinct

This function is designed to merge two arrays ($array1 and $array2) in a way that is distinct from PHP's native array_merge_recursive. It avoids combining values under the same key as an array and instead replaces existing values if needed.

public array_merge_recursive_distinct(array &$array1, array &$array2): array

Parameters:

Return Value:

array - Return the merged array with unique values.

Usage Examples:

$array1 = ['a' => 1, 'b' => 2];
$array2 = ['b' => 20, 'c' => 3];

$result = array_merge_recursive_distinct($array1, $array2);
print_r($result);

Output:

Array
(
    [a] => 1
    [b] => 20
    [c] => 3
)

array_merge_result

Merges a response into the provided results variable while optionally preserving the structure of nested arrays.

This function checks the type of the results variable and appropriately merges or appendsthe response based on its type. It supports various scenarios:

• If results is null, it assigns response to it.
• If results is an array and preserve_nested is true, it adds the response as a nested element if response is an array, or appends response directly otherwise.
• If results is an array and preserve_nested is false, it merges results and response directly when response is an array.
• If results is not an array (like a string or scalar), it converts results into an array and merges or appends the response based on the preserve_nested flag.

public array_merge_result(mixed &$results, mixed $response, bool $preserve_nested = true): void

Parameters:

Usage Examples:

<?php
$results = null;

// Case 1: Merging a new string response.
$response1 = 'Task 1 completed';
array_merge_result($results, $response1);
var_export($results);

// Case 2: Merging an array response while preserving the nested structure.
$response2 = ['Task 2 completed'];
array_merge_result($results, $response2);
var_export($results);

// Case 3: Merging another array response without preserving nested structure.
$response3 = ['Task 3 completed', 'Task 4 completed', (object)[1,2,3]];
array_merge_result($results, $response3, false);
var_export($results);

Output:

// Case 1: Output
'Task 1 completed'

// Case 2: Output
array (
  0 => 'Task 1 completed',
  1 => 
  array (
    0 => 'Task 2 completed',
  ),
)

// Case 3: Output
array (
  0 => 'Task 1 completed',
  1 => 
  array (
    0 => 'Task 2 completed',
  ),
  2 => 'Task 3 completed',
  3 => 'Task 4 completed',
  4 => 
  (object) array(
     '0' => 1,
     '1' => 2,
     '2' => 3,
  ),
)

string_length

Calculate string length based on different charsets.

function string_length(string $content, ?string $charset = null): int

Parameters:

Return Value:

int - Returns the string length.

kebab_case

Convert a string to kebab case.

function kebab_case(string $input, bool $lower = true): string

Parameters:

Return Value:

string - Return the kebab-cased string.

camel_case

Convert a string to camel case.

function  camel_case(string  $input): string

Parameters:

Return Value:

string - Return string. as camel cased.

which_php

Find the PHP script executable path.

function which_php(): string|null

Return Value:

string|null - Return PHP executable path or null.

status_code

Gets request status code from executed command or controller method.

function status_code(mixed $result = null, bool $return_int = true): int|bool

Parameters:

Return Value:

int|bool - Return the status code int or bool.

If passed result is boolean (false), integer (1) or NULL, the method will return STATUS_ERROR.

If passed result is boolean (true), integer (0), VOID or any other values, the method will return STATUS_SUCCESS.

http_status_header

Sets the HTTP response status code and sends appropriate headers.

This function sets the HTTP status code and sends the corresponding status message header.If the status code is not predefined, it returns false. For predefined status codes, it sends headers including the status message. The function determines the HTTP protocol version based on the server's protocol.

function http_status_header(int $status): bool

Parameters:

Return Value:

bool - Returns true if the status code is found in the predefined list and headers are set, otherwise false.

text2html

Converts text characters in a string to HTML entities.

function  text2html(string|null  $text): string

Parameters:

Return Value:

string - Return processed text with HTML entities.

nl2html

Converts newline characters in a string to HTML entities.

function  nl2html(string|null  $text): string

This is useful when you want to display text in an HTML textarea while preserving the original line breaks.

Parameters:

Return Value:

string - Return processed text with HTML entities.

uppercase_words

Uppercase the first character of each word in a string, it also handles underscores (_) and hyphens (-), converting them to spaces before applying capitalization.

function uppercase_words(string $string): bool

Parameters:

Return Value:

bool - Return the string with the first character of each word capitalized.

Usage Example:

echo uppercase_words('foo-bar_baz');
// Output: // Foo-Bar_Baz

More Patterns:

$strings = [
    'foo-bar_baz'
    'hello-world_this_is_a_test'
    'example'
    '_leading_and_trailing_'
    '-leading-plus-trailing-'
    'multiple---dashes_and__underscores'
    'foo-bar baz_baz'
];

$results = array_map('uppercase_words', $strings);

// Print the results
echo implode("\n", $results);

Output:

Foo-Bar_Baz
Hello-World_This_Is_A_Test
Example
_Leading_And_Trailing_
-Leading-Plus-Trailing-
Multiple-Dashes_And_Underscores
Foo-Bar Baz_Baz

has_uppercase

Checks if a given string contains an uppercase letter.

function has_uppercase(string $string): bool

Parameters:

Return Value:

bool - Returns true if the string has uppercase, false otherwise.

list_to_array

Convert a string list to an array.

function list_to_array(string $list): array|false

Parameters:

Return Value:

array|false - The resulting array or false on failure.

In Luminova, a string list typically consist of comma-separated values, which may or may not be enclosed in quotes.

Examples: Foo, Bar, Baz, "Foo", "bar", "Baz"

list_in_array

Check if string list exists, matched an array.

function list_in_array(string $list, array $array = []): bool

Parameters:

Return Value:

bool - Return true if the list exists in the array, otherwise false.

<?php
$list = "Foo, Bar, Baz";

list_in_array($list, ['Foo', 'Bra']); // false

list_in_array($list, ['Foo', 'Baz', 'Bar']); // true

If any of the list value doesn't exist in the array, it will return false.

is_list

Test if a string is in a valid list format.

function is_list(string $input, bool $trim = false): bool

Parameters:

Return Value:

bool - Return true if the string is in a valid list format, false otherwise.

is_platform

Tells which platform your application is running on.

function is_platform(string $os): bool

Parameters:

Return Value:

bool - Return true if the application is running on the specified platform, false otherwise.

is_tor

Determines if the provided IP address corresponds to a Tor exit node.

function is_tor(?string $ip = null): bool

Parameters:

Return Value:

bool - Return true if the IP address is a Tor exit node, false otherwise.

is_empty

Check if values are empty.

function is_empty(mixed  $values): bool

Parameters:

Return Value:

bool - True if any of the values are empty, false otherwise.

This function treats 0 as non-empty.

If you want different behavior, use the PHP empty() function instead.

is_nested

Determine if an array is a nested array.If recursive is false it only checks one level of depth.

function is_nested(array $array, bool $recursive = false): bool 

Parameters:

Return Value:

bool - Return true if the array is nested, false otherwise.

Note:An empty array is considered as none nested array, so it will return false.

is_associative

Determine if an array is associative.

function is_associative(array $array): bool

Parameters:

Return Value:

bool - True if the array is associative, false otherwise.

is_command

Check if the application is running in command-line interface CLI mode.

function is_command(): bool

Return Value:bool - Returns true if the execution was made in CLI mode, false otherwise.

is_dev_server

Check if the application is running locally on any development environment.

function is_dev_server(): bool

Return Value:

bool - Returns true if the application is running on the development server, false otherwise.

This function utilizes server variable SERVER_NAME to check the server name matches any of 127.0.0.1 ::1 localhost.

Additionally it checks a custom Luminova server variable NOVAKIT_EXECUTION_ENV which is set when using builtin PHP development server.

is_blob

Determine whether the type of a variable is blob.

function is_blob(mixed $value): bool

Parameters:

Return Value:

bool - Return true if the value is a blob, false otherwise.

is_utf8

Determine weather a given string is UTF-8 encoded.

function is_utf8(string $input): bool

Parameters:

Return Value:

bool - Returns true if the string is UTF-8 encoded, false otherwise.

function_exists_cached

Checks if a function exists and caches the result to avoid repeated checks.

This function uses a static cache to store whether a function exists or not.If the function's existence has been checked before, the cached result is returned.Otherwise, it checks the function's existence using function_exists() and caches the result, improving performance by avoiding repeated function existence checks.

function function_exists_cached(string $function): bool

Parameters:

Return Value:

bool - Returns true if the function exists, false otherwise.