Helper Functions

Simplifying and Streamlining Your Development Process with Zemit Core

These functions are designed to enhance your productivity by offering a suite of utility tools that simplify and streamline common programming tasks within Zemit CMS Core. These raw functions encompass a broad range of functionalities and are integral to making the most of the Zemit Core Framework. Understanding these helper functions and how to use them effectively will equip you to leverage Zemit Core's full potential and create powerful, efficient applications.

Dumping & Debugging

Var Dump & Die (vdd)

The vdd function, short for 'var_dump and die', is another debug helper function provided by the Zemit Core Framework. Similar to the dd function, vdd allows you to output the values of one or more variables and then halt the execution of the script.

The vdd function, however, uses PHP's built-in var_dump function to output the variables rather than Zemit's custom dump function. This leads to a difference in how the output is formatted. While dump provides formatted output that's designed to be more readable and often includes HTML formatting for display in a web browser, var_dump produces plain text output that includes more detailed information, such as the types and sizes of values.

After dumping the variables, vdd calls the exit_500 function to terminate the script and send a 500 Internal Server Error header to the client, if the headers have not already been sent.

Here's an example of how you might use vdd in your code.

vdd($variable1, $variable2, $variable3, ...$variables);

Die & Dump (dd)

The dd function is a debug helper function in the Zemit Core Framework. The name 'dd' stands for 'dump and die'. This function enables you to dump the values of one or more variables to the output and then terminate the script.

When called, the dd function will use the dump function to output the values of all the variables that you pass to it. After it has dumped the variables, it will call the exit_500 function to terminate the script and send a 500 Internal Server Error header to the client, if the headers have not already been sent.

The dd function is extremely useful for debugging, as it allows you to inspect the current values of variables and then stop the script execution, preventing any further code from running.

Here is an example of how to use the dd function in your code:

dd($variable1, $variable2, $variable3, ...$variables);

Dump (dump)

The dump function is a utility helper provided by the Zemit Core Framework that aids in debugging your application. This function allows you to print or "dump" the value of one or more variables to the output without ending the script.

When called, the dump function will output the values of all the variables that you pass to it. It does this by creating a new Dump object for each variable, converting that variable to a string, and then echoing that string.

If the script is running in a command line environment (detected by checking if PHP_SAPI equals 'cli'), it will additionally strip out any HTML tags from the output and append a newline character. This makes the output more readable when working in a console.

Here is an example of how to use the dump function in your code:

$variable1 = "Hello, world!";
$variable2 = [1, 2, 3, 4, 5];
$variable3 = new StdClass();
$variable3->foo = 'bar';

dump($variable1, $variable2, $variable3);

In this example, dump will output the values of $variable1, $variable2, and $variable3 to the console or web page, allowing you to see their current values at that point in the script.

Exit & Status 500 (exit_500)

The exit_500 function is a utility helper in the Zemit Core Framework that enables you to exit your application while setting an HTTP 500 Internal Server Error header. This function is particularly useful when you want to terminate the script and send an error status to the client due to an unexpected condition in your server-side code.

When called, the function first checks if the PHP Server API (SAPI) is not one of 'cli' or 'phpdbg', indicating that the code is not being run from the command line or a debugger. It then checks if headers have not already been sent. If both conditions are true, the function sets an HTTP header indicating a 500 Internal Server Error.

The function exits the script with a status code of 1, which typically indicates an error or abnormal termination.

Please note that the exit_500 function will only set the HTTP header if it is called before any output has been sent to the client. After output has started, HTTP headers can no longer be modified.

Here is an example of how to use the exit_500 function in your code:

exit_500(); // Exit the script and send a 500 Internal Server Error header

Printing & Output

Multibyte support for vSprintF (mb_vsprintf)

The mb_vsprintf function is a multibyte-safe version of the vsprintf function in PHP, designed to work with any "ASCII preserving" encoding, such as UTF-8 and all ISO-8859 charsets. This is especially useful for processing strings in languages that use characters not covered by ASCII.

The function takes a format string, an array of arguments, and an optional encoding, then returns a string produced according to the formatting string using the elements of the array. The format string consists of zero or more placeholders - these are replaced by the values from the argument array.

The function supports sign, padding, alignment, width, and precision, but it doesn't support argument swapping.

Here's a usage example:

$format = 'Hello, %s!';
$name = '世界'; // 'world' in Chinese
echo mb_vsprintf($format, [$name], 'UTF-8');
// Outputs: 'Hello, 世界!'

In this example, mb_vsprintf replaces %s in the format string with the value of $name. It correctly handles the multibyte string thanks to the 'UTF-8' encoding specification.

Please note that mb_vsprintf function expects all strings, both format and arguments, to be in the same encoding specified. If no encoding is specified, it will use the internal encoding returned by mb_internal_encoding().

As with all functions in PHP that manipulate strings, if you're working with multibyte strings (like UTF-8), make sure the encoding is specified correctly for accurate results.

Multibyte Support for sPrintF (mb_sprintf)

The mb_sprintf function is a multibyte-safe version of the sprintf function in PHP. It provides a way to format a string with a variable number of arguments, and it is designed to work with any "ASCII preserving" encoding, such as UTF-8 and all ISO-8859 charsets.

This function utilizes the mb_vsprintf function internally. Therefore, like mb_vsprintf, mb_sprintf supports sign, padding, alignment, width, and precision, but it does not support argument swapping.

Here's an example of how to use the mb_sprintf function:

$format = 'Hello, %s and %s!';
$name1 = '世界'; // 'world' in Chinese
$name2 = 'フレンド'; // 'friend' in Japanese
echo mb_sprintf($format, $name1, $name2);
// Outputs: 'Hello, 世界 and フレンド!'

In this example, mb_sprintf replaces the first %s in the format string with the value of $name1 and the second %s with the value of $name2. It correctly handles the multibyte strings.

Remember that mb_sprintf function, like mb_vsprintf, expects all strings, both the format and the arguments, to be in the same encoding. If no encoding is specified, the internal encoding returned by mb_internal_encoding() will be used. Make sure the encoding is specified correctly for accurate results when working with multibyte strings.

Named Argument for SprintF (sprintnf)

The sprintfn function is a named-argument version of the sprintf function in PHP. Instead of using the standard numerical placeholders for values (like %1$s), you can use named placeholders in the format string and provide an associative array of arguments.

This function can be particularly useful when you have a complex format string with many values to replace, and you want to make your code more readable and maintainable.

Here's an example of how to use the sprintfn function:

$format = 'Hello, %name$s. You have %quantity$d new messages.';
$args = [
    'name' => 'Alice',
    'quantity' => 5,
];
echo sprintfn($format, $args);
// Outputs: 'Hello, Alice. You have 5 new messages.'

In this example, sprintfn replaces %name$s in the format string with the value of 'name' from the $args array, and %quantity$d with the value of 'quantity'.

It's important to ensure that all placeholders in the format string have corresponding keys in the $args array. If a key in the format string does not have a corresponding value in the $args array, sprintfn will trigger a E_USER_WARNING and return false.

Note that the sprintfn function uses vsprintf internally to replace the named arguments with their corresponding values.

Implode Multibyte sPrintF (implode_mb_sprintf)

The implode_mb_sprintf function is an utility function that applies the mb_sprintf function to each element of an array, then concatenates those results into a string using a provided "glue" string.

This function is particularly useful when you want to convert an array of values into a formatted string, and the values or the format may contain multibyte characters.

Here's how to use implode_mb_sprintf:

$array = ['Alice', 'Bob', 'Charlie'];
$glue = ', ';
$format = 'Hello, %s!';
echo implode_mb_sprintf($array, $glue, $format);
// Outputs: 'Hello, Alice!, Hello, Bob!, Hello, Charlie!'

In this example, implode_mb_sprintf applies the mb_sprintf function to each name in the $array, using the provided format string. It then joins the results into one string, with each formatted name separated by the $glue string.

Please note that the $format string should contain one %s placeholder for each element of the array. The function will not work correctly if the number of placeholders does not match the number of elements in the array. The function internally utilizes implode_sprintf with multibyte support enabled.

Implode sPrintF (implode_sprintf)

The implode_sprintf function is a utility helper function that applies either the sprintf or mb_sprintf function (depending on the $multibyte flag) to each element of an array, and then concatenates those results into a single string using a specified "glue" string.

The purpose of this function is to format each element in an array and then join them together in a string, which is especially useful when the elements are multibyte strings or when specific formatting for each element is desired.

Here's an example of how to use the implode_sprintf function:

$array = ['Alice', 'Bob', 'Charlie'];
$glue = ', ';
$format = 'Hello, %s!';
$multibyte = true;
echo implode_sprintf($array, $glue, $format, $multibyte);
// Outputs: 'Hello, Alice!, Hello, Bob!, Hello, Charlie!'

In this example, implode_sprintf applies the mb_sprintf function to each name in the $array using the specified format string. It then merges the results into one string, with each formatted name separated by the $glue string.

Please note that the $format string should contain one %s placeholder for each array element. The function may not operate correctly if the number of placeholders doesn't match the number of elements in the array.

Array

Array Unset Recursive (array_unset_recursive)

The array_unset_recursive function is a utility function provided by the Zemit Core Framework that allows you to remove specific keys from an array and its nested arrays. This function operates recursively, meaning it will traverse through all levels of multi-dimensional arrays to locate and unset the keys that match those specified in the $keyList.

The function accepts three parameters:

1. $array (passed by reference) - The array from which keys will be removed.

2. $keyList - An array of keys that you want to remove from $array.

3. $strict (optional, default is true) - If true, the function will also check the type of the key in addition to its value when comparing it with the keys in $keyList.

The function returns the number of keys removed from the array.

Here is an example of how you might use the array_unset_recursive function:

$data = [
    "name" => "John Doe",
    "age" => 30,
    "contact" => [
        "email" => "[e-mail]",
        "phone" => "1234567890"
    ]
];

$keysToRemove = ["age", "phone"];
$removedCount = array_unset_recursive($data, $keysToRemove);

echo $removedCount;
// Outputs: 2

In this example, array_unset_recursive will remove the keys "age" and "phone" from the $data array, and return the total number of keys removed. The $data array is modified directly since it's passed by reference to the function.