Additionally/Functions

Built-in Framework Functions

The HLEB2 framework introduces a number of its own functions of various purposes, which reduce code size and accelerate application development, as they are shorthand for common actions.

Some built-in framework functions have hl_ at the beginning of their names, and there are also duplicates of functions without this prefix. Therefore, if you forget the name of the desired function, just type hl_ and your IDE should suggest available options.

#Working with Route Data

The HLEB2 framework has its own routing system. The following functions are intended to interact with this system. If you practice assigning custom names to routes, they might be useful here.

#route_name()

This function returns the name of the current route or null if it is not assigned.
Despite this very useful information, it may only be needed in conjunction with another function that works with addresses.

#url()

The url() function returns a relative URL by route name with substitutions for necessary parameters.
Function arguments:
routeName - the name of the route for which the address is needed.
replacements - an array of substitution parts if the route is dynamic.
endPart - a boolean value determining if the last part of the address is required, if it is optional in the route.
method - for which HTTP method the address is needed. Some methods may not fit the route, and in such cases, it will return an error. By default, 'get'.

Consistent use of internal URLs by their route names allows the entire application to change static parts of addresses in routes without making changes to the rest of the code.

#address()

The address() function returns the full URL based on the route name with the substitution of the current domain. Since the domain is only the current one, use concatenation with url() for a different domain.
The set of parameters is similar to the url() function. This function allows you to generate correct links to the project pages. However, it is better to use relative URLs for in-app navigation.

#Retrieving Current HTTP Request Data

#request_uri()

Returns an object with information from the relative URL of the current request.
The basis for the object returned by the request_uri() function is the UriInterface (method getUri()) from PSR-7, which allows you to obtain the following request data:
request_uri()->getHost() - The domain name of the current request, such as 'mob.example.com'. May include the port depending on its presence in the request.
request_uri()->getPath() - The path from the address after the host, such as '/ru/example/page' or '/ru/example/page/'.
request_uri()->getQuery() - Request parameters, such as '?param1=value1&param2=value2'.
request_uri()->getPort() - The request port.
request_uri()->getScheme() - The HTTP scheme of the request, either 'http' or 'https'.
request_uri()->getIp() - The IP address of the request.

In these examples with request_uri(), two styles of naming conventions are used within a single expression (snake_case and camelCase), which is because most functions of the HLEB2 framework are in snake_case similar to PHP functions, while the methods of the returned object are in camelCase, according to PSR-12. If you are accustomed to a different function format, wrap the current ones in the necessary style.

#request_host()

The request_host() function allows you to obtain the current host, possibly along with the port. For example, example.com or example.com:8080 if it is specified in the request URL. This is useful for generating correct links to project pages. However, for internal navigation within the application, it is better to use relative URLs.

#request_path()

The request_path() function returns the current relative request path from the URL without GET parameters. For example, /ru/example/page or /ru/example/page/.

#request_address()

The request_address() function returns the complete current request address from the URL without GET parameters. For example, `https://example.com/ru/example/page` or `https://example.com/ru/example/page/`.

#Redirect

Redirecting to other pages of the application or other URLs.

#hl_redirect()

The hl_redirect() function performs a redirect using a specified header and exits the script. Thus, if content has already been output before this function is applied, headers will not be sent, and a warning will be displayed instead of redirecting. It operates based on the 'Location' header. When used in framework-based classes, such as in controllers, it's more appropriate to use a similar method Redirect::to().

#Fetching Framework Configuration Data

Configuration data from the framework or custom settings can be used in the application code. The following functions allow these data to be retrieved anywhere in the project code.

Project parameters and settings should be collected in its configuration files, and they can be used not only for the application's needs but also for configuring connected third-party libraries.

#config()

Each configuration parameter is distributed by groups according to the main filename.
These might be standard groups ('common', 'database', 'main', 'system') or additional ones created for the project. The group's name is passed as the first argument to the config() function.
The parameter's name itself is the second argument. The function returns this parameter's value. For example:

#get_config_or_fail()

As the name get_config_or_fail() suggests, this function returns the configuration parameter's value or throws an error if the parameter is not found or is null. The arguments are similar to the config() function.

#setting()

Since it’s recommended to add custom values to the 'main' group, a separate function setting() is provided for frequent use of this configuration. Its application is similar to the config() function with the first argument 'main'.

#hl_db_config()

The special function hl_db_config() serves as an equivalent of the config() function with the first argument 'database'.

#hl_db_connection()

The hl_db_connection() function is used to retrieve data from any existing connection in the 'db.settings.list' of the 'database' settings group. It returns an array of settings or throws an error if they are not found.

#hl_db_active_connection()

The hl_db_active_connection() function, like the hl_db_connection() function, returns a settings array but specifically for the connection marked as "active" in the 'base.db.type' parameter.

These functions for accessing database parameters are essential when adding third-party libraries that require a connection configuration to a specific database.

#Debugging Functions

The framework includes several functions for quick code debugging. They complement and extend the PHP var_dump() function in various ways. Depending on the situation, a suitable one can be chosen.

#print_r2()

This function has been retained from the first version of the framework. It is used to display data in a readable format for the debug panel. Thus, when DEBUG mode is off, debug data passed to the function won’t be displayed, as the debug panel is disabled. This is convenient during development, as you don’t need to worry about its visibility outside of debug mode. An optional second argument to the print_r2() function allows you to add a description to the displayed data for easy identification in the panel. Example:

#var_dump2()

The var_dump2() function is a complete analog of var_dump(), but it outputs more structured information. If the output is intended for a browser, the original line breaks and indents are preserved.

#dump()

The dump() function is another wrapper around var_dump(), but it converts the result to HTML code, which appears cleaner and more informative than the standard output.

#dd()

Similar to dump(), it outputs HTML code but also terminates the script after that. The dd() function is easy to locate on the application page, as its output will be at the very bottom.

#File System Operations

The HLEB2 framework organizes file and directory operations based on relative paths from the project root. Such paths begin with '@/' to denote the root directory. This approach is used across many standard services in the framework and is recommended for consistent usage. The following functions serve as wrappers around equivalent PHP functions, adding the capability to use the '@' prefix.

#hl_file_exists()

The hl_file_exists() function is analogous to the PHP function file_exists(), but it also accepts special paths starting with '@'.

#hl_file_get_contents()

The hl_file_get_contents() function is similar to the PHP function file_get_contents(), but it allows for special paths starting with '@'.

#hl_file_put_contents()

The hl_file_put_contents() function is equivalent to the PHP function file_put_contents() and also accepts paths starting with '@'.

#hl_is_dir()

The hl_is_dir() function is similar to the PHP function is_dir(), but it can also accept paths with a starting '@'.

#CSRF Protection

Detailed documentation on the implementation of protection against CSRF attacks in the framework.

#csrf_token()

The csrf_token() function returns a secure token for protection against CSRF attacks.

#csrf_field()

The csrf_field() function returns HTML content to insert into a form for CSRF attack protection.

#Templates

Although the framework allows integration with the Twig templating engine, it also provides a straightforward implementation of built-in templates that do not use custom syntax different from standard PHP or HTML. Learn more about the framework's standard templates.

#insertTemplate()

With the insertTemplate() function, the generated template is inserted at the location in the file where this function is called. Key parameters:
viewPath - a specific path to the template file. This format is similar to the path types used in the view() function.
extractParams - an associative array of values that will be converted into template variables.

#template()

The template() function returns the framework template's text representation. This is useful if you need to pass the content further, for example, if it is an email template. Parameters are similar to those in the insertTemplate() function.

#insertCacheTemplate()

The insertCacheTemplate() function is similar to insertTemplate() except that the template is cached for the specified number of seconds in the sec parameter. Other arguments are identical to those in the insertTemplate() function.

#Additional

Various specialized functions.

#is_empty()

Checks for emptiness in a more selective way than the PHP function empty(). The is_empty function will return false only in four scenarios: an empty string, null, false or an empty array. Passing an undeclared variable will result in an error; therefore, to mimic the original function, you can suppress this error by adding '@' before the function like this:

While using error suppression is poor practice, the code within the is_empty() function does not imply the occurrence of other errors.

#logger()

The function for logging logger() returns an object with methods for logging data across various levels.

#once()

The once() function allows code to be executed only once for a single request, and on subsequent calls, it returns the previous result.
The result of execution is stored in memory for the entire duration of the request.
In this scenario, the anonymous function passed to once() will execute on the first call to once:

#param()

Returns an object containing dynamic request data by parameter name with the option to select the value format.
For example, if the dynamic route specified the parameter /{test}/, and the request was /example/, then param('test')->value will return 'example'.
param('test')->value; - directly retrieves the value.
param('test')->value(); - directly retrieves the value.
param('test')->asInt(); - returns the value converted to an integer, or null if absent.
param('test')->asInt($default); - returns the value converted to an integer, and $default is returned if absent.
If the last part of the route is an optional variable value, it will be null.
Caution is advised with user data obtained as direct values.

#Framework Function Testing

In most cases, the framework's standard functions are wrappers around corresponding services, so testing them is similar to testing the service.