Práce s polem - Jet\Data_Array

Třída pro práci s daty uloženými v asociovaných vícerozměrných polích, která je velice hojně využívána na řadě míst platformy Jet. Jejím smyslem je unifikovat a usnadnit čtení a zápis dat v podobě vícerozměrných asociovaných polí, ale také umožňuje taková data exportovat do JSON, nebo do PHP deklarace pole.

Čtení hodnot z pole

Dejme tomu, že máte nějaká konfigurační data v podobě pole (nechme teď stranou, že ve skutečnosti použijete systém definice konfigurace) a chcete získat číslo TCP portu určitého spojení. Standardně to můžete udělat například takto:


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

To není z mnoha důvodů úplně ideální způsob. V moderním PHP by bylo lepší udělat to takto:


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

Ovšem Jet má unifikovaný způsob práce s takovými daty (a nejen z důvodu že vznikl ještě v době, kdy PHP nemělo operátor ??) a správně se to v Jet řeší takto:


$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 );

Tedy nejde "pouze" o bezpečné čtení hodnot ze surových dat v poli - i když to je samo o sobě důležité. Dalším užitečným rysem je to, že se dá cesta k datům jednoduše definovat jako textový řetězec. Je to takový hodně zjednodušený (ale dostačující) XPath pro práci s poli.

Jak vidno z příkladu, tak při čtení hodnoty se počítá s přetypováním na požadovaný typ a také s výchozí hodnotou. Všechny metody pro čtení jsou popsány níže v přehledu.

Zápis hodnot do pole

Zápis funguje zcela identicky jako čtený - tedy opět používá cestu k datům. Navažme tedy na výše uvedený příklad a ukažme si jak by bylo nové hypotetické spojení do dat zapsáno:


$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

Možnost pole exportovat je také nezanedbatelná funkce. Existuje možnost exportu do JSON a do PHP deklarace. Pojďme si to ukázat.

Export do JSON

Třída Jet\Data_Array implementuje rozhraní Jet\BaseObject_Interface_Serializable_JSON a to rozšiřuje PHP rozhraní \JsonSerializable. To znamená, že instanci Jet\Data_Array je možné přímo předat funkci json_encode, nebo použít metodu toJSON(): $json = $cfg_data->toJSON(); $json = json_encode($cfg_data); Oba způsoby jsou zcela ekvivalentní.

Export do PHP deklarace

Jet potřebuje často pole ukládat (jako pro daný účel nejefektivnější datový formát). Tedy zůstaňme u našich ukázkových hypotetických dat. Ta potřebujeme uložit do této podoby:[ 'connections' => [ 'default' => [ 'host' => '127.0.0.1', 'port' => 8443, 'is_persistent' => false, ], 'erp' => [ 'host' => '123.123.123.123', 'port' => 64443, 'is_persistent' => false, ], ], ];

Provede se to jednoduše takto: $cfg_str = $cfg_data->export();

Krom několika vnitřních odlišností metoda poskytuje zatím trochu "hezčí" výstup, než funkce var_export.

Přehled metod

Metoda	Význam
public __construct( array $data=[] )
public getRawData( ) : array	Vrátí aktuální data opět v podobě pole.
public exists( string $key ) : bool	Ověří zda daný klíč - adresa dat v poli vůbec existuje.
public set( string $key, mixed $value ) : void	Nastaví hodnotu dat na daném klíči - adrese pole.
public remove( string $key ) : void	Odstraní data podle daného klíče - adresy pole.
public getInt( string $key, int $default_value=0 ) : int	Vrátí hodnotu jako celé číslo. Pokud daný klíč - adresa v poli neexistuje, pak vrátí výchozí hodnotu.
public getFloat( string $key, float $default_value=0.0 ) : float	Vrátí hodnotu jako desetinné číslo. Pokud daný klíč - adresa v poli neexistuje, pak vrátí výchozí hodnotu.
public getBool( string $key, bool $default_value=false ) : bool	Vrátí hodnotu jako bool. Pokud daný klíč - adresa v poli neexistuje, pak vrátí výchozí hodnotu.
public getString( string $key, string $default_value='', array $valid_values=[] ) : string	Vrátí hodnotu jako řetězec. POZOR! Řetězec je před vrácením zakódován pomocí Data_Text::htmlSpecialChars!. Pokud daný klíč - adresa v poli neexistuje, pak vrátí výchozí hodnotu. Parametr $valid_values umožňuje omezit platnost hodnot na určitou konkrétní množinu. Pokud hodnota nepatří do této množiny, pak je vrácena výchozí hodnota.
public getRaw( string $key, mixed $default_value=null ) : mixed	Vrátí hodnotu bez jakéhokoliv zásahu. Je tak možné vracet neskalární typy, nebo řetězec pokud jste si jistí, že jej opravdu nechcete prohnat přes htmlSpecialChars. Pokud daný klíč - adresa v poli neexistuje, pak vrátí výchozí hodnotu.
public export( ) : string	Exportuje pole v podobě PHP deklarace.
public toJSON( ) : string	Exportuje data do formátu JSON.
public jsonSerialize( ) : array	Umožňuje předat instanci třídy funkci json_encode. Viz PHP rozhraní \JsonSerializable.