Working with an array - Jet\Data_Array

A class for working with data stored in associated multidimensional arrays that is very widely used in many places on the Jet platform. Its purpose is to unify and make it easier to read and write data in the form of multidimensional associated arrays, but it also allows such data to be exported to JSON or PHP array declarations.

Reading values from an array

Suppose you have some configuration data in the form of an array (let's leave aside for now that you actually use the configuration definition system) and you want to get the TCP port number of a particular connection. By default, you can do this, for example:


$tcp_port = $cfg_data['connections'][$connection_name]['tcp_port'];

This is not an ideal way for many reasons. In modern PHP it would be better to do it this way:


$tcp_port = (int)($cfg_data['connections'][$connection_name]['tcp_port']??8443);

But Jet has a unified way of working with such data (and not only because it was created when PHP didn't have the ?? operator) and the correct way to handle it in Jet is as follows:


$cfg_data = new Data_Array($cfg_data);



$connection_cfg = '/connections/'.$connection_name.'/';



$host = $cfg_data->getString( $connection_cfg.'host', 'localhost');

$port = $cfg_data->getInt( $connection_cfg.'port', 8443);

$is_persistent = $cfg_data->getBool( $connection_cfg.'is_persistent', false );

So it is not "just" about safely reading values from raw data in an array - although that is important in itself. Another useful feature is that the path to the data can be easily defined as a text string. It's kind of a very simplified (but sufficient) XPath for working with arrays.

As you can see from the example, when reading the value, the overwriting to the desired type and also the default value are taken into account. All methods for reading are described in the overview below.

Writing values into the field

The write works identically to the read - i.e. it uses the data path again. So let's follow the example above and show how the new hypothetical connection would be written to the data:


$connection_cfg = '/connections/'.$new_connection_name.'/';



$cfg_data->set( $connection_cfg.'host', $new_host );

$cfg_data->set( $connection_cfg.'port', $new_port );

$cfg_data->set( $connection_cfg.'is_persistent', false );

Export

The ability to export an array is also a notable feature. There is an option to export to JSON and to PHP declaration. Let's demonstrate.

Export to JSON

The Jet\Data_Array class implements the Jet\BaseObject_Interface_Serializable_JSON interface and this extends the PHP interface \JsonSerializable. This means that the Jet\Data_Array instance can be passed directly to the json_encode function, or use the toJSON() method:


$json = $cfg_data->toJSON();

$json = json_encode($cfg_data);

The two methods are completely equivalent.

Export to PHP declaration

Jet often needs to save the fields (as for the purpose the most efficient data format). So let's stick with our sample hypothetical data. We need to store them in this form:


[

    'connections' => [

        'default' => [

            'host' => '127.0.0.1',

            'port' => 8443,

            'is_persistent' => false,

        ],

        'erp' => [

            'host' => '123.123.123.123',

            'port' => 64443,

            'is_persistent' => false,

        ],

    ],

];

It's easy to do as follows:


$cfg_str = $cfg_data->export();

Aside from a few internal differences, the method provides a slightly "nicer" output than the var_export function so far.

Overview of methods

Method	Meaning of
public __construct( array $data=[] )
public getRawData( ) : array	Returns the current data again in the form of an array.
public exists( string $key ) : bool	Verifies whether the key - data address in the array exists at all.
public set( string $key, mixed $value ) : void	Sets the data value on the given key - array address.
public remove( string $key ) : void	Removes data according to the given key - array address.
public getInt( string $key, int $default_value=0 ) : int	Returns the value as an integer. If the key - address does not exist in the field, then it returns the default value.
public getFloat( string $key, float $default_value=0.0 ) : float	Returns the value as a decimal number. If the key - address does not exist in the field, then it returns the default value.
public getBool( string $key, bool $default_value=false ) : bool	Returns the value as bool. If the key - address does not exist in the field, then it returns the default value.
public getString( string $key, string $default_value='', array $valid_values=[] ) : string	Returns the value as a string. WARNING! The string is encoded before returning using Data_Text::htmlSpecialChars!. If the given key - address does not exist in the field, then it returns the default value. The $valid_values parameter allows to limit the validity of values to a specific set. If the value is not in this set, then the default value is returned.
public getRaw( string $key, mixed $default_value=null ) : mixed	Returns the value without any intervention. It is possible to return non-scalar types, or a string if you are sure that you really don't want to pass it through htmlSpecialChars. If the key - address does not exist in the field, then it returns the default value.
public export( ) : string	Exports the array as a PHP declaration.
public toJSON( ) : string	Exports data to JSON format.
public jsonSerialize( ) : array	Allows to pass an instance of the class to the json_encode function. See the PHP interface \JsonSerializable.