Reference Array funkcí

Funkce pro práci s vnořenými poli a normalizaci strukturovaných dat.

---

getArrayValue()

Načte vnořenou hodnotu z pole pomocí oddělovače : v klíči.

getArrayValue(array $array, string $key, bool $emptyIsNull = false, string $separator = ':'):mixed

Parametry:

Parametr	Typ	Popis
$array	array	Zdrojové pole
$key	string	Klíčová cesta (např. 'smtp:use', 'email:from')
$emptyIsNull	bool	Vrátit null pro prázdné hodnoty (default: false)
$separator	string	Oddělovač pro cesty (default: ':')

Návratová hodnota:

• Načtená hodnota ze vnořeného pole
• null pokud klíč neexistuje
• null pokud $emptyIsNull = true a hodnota je prázdná

Příklady:

$array = [
    'smtp' => [
        'use'  => true,
        'host' => 'smtp.example.com'
    ]
];

getArrayValue($array, 'smtp:use');           // true
getArrayValue($array, 'smtp:host');          // 'smtp.example.com'
getArrayValue($array, 'smtp:port');          // null
getArrayValue($array, 'nonexistent:key');    // null

---

setArrayValue()

Nastaví vnořenou hodnotu v poli a vytvoří potřebné vnořené struktury.

setArrayValue(array &$array, string $key, mixed $value, string $separator = ':'):mixed

Parametry:

Parametr	Typ	Popis
$array	array	Cílové pole (předáno odkazem)
$key	string	Klíčová cesta
$value	mixed	Hodnota k nastavení
$separator	string	Oddělovač (default: ':')

Návratová hodnota:

• Vrácená hodnota (stejná jako $value)

Poznámka: Funkce používá referencování (&$array) – pole se modifikuje na místě.

Příklady:

$data = [];

// Vytvoří vnořenou strukturu
setArrayValue($data, 'user:profile:name', 'John');
setArrayValue($data, 'user:profile:email', 'john@example.com');

// Výsledek:
// [
//     'user' => [
//         'profile' => [
//             'name' => 'John',
//             'email' => 'john@example.com'
//         ]
//     ]
// ]

---

deleteArrayValue()

Smaže vnořenou hodnotu z pole.

deleteArrayValue(array &$array, string $key, string $separator = ':'):void

Parametry:

Parametr	Typ	Popis
$array	array	Cílové pole (předáno odkazem)
$key	string	Klíčová cesta k mazání
$separator	string	Oddělovač (default: ':')

Návratová hodnota:

• void (nic nevrací)

Chování:

• Pokud cesta neexistuje, funkce ji tiše ignoruje (safe delete)
• Smaže pouze poslední klíč v cestě, vnořené struktury zůstávají

Příklady:

$data = [
    'user' => [
        'name'  => 'John',
        'email' => 'john@example.com'
    ]
];

deleteArrayValue($data, 'user:email');

// Výsledek: $data = ['user' => ['name' => 'John']]

// Bezpečné – neexistující klíč nezpůsobí chybu
deleteArrayValue($data, 'user:phone');

---

removePrefixFromFieldKeys()

Odstraní zadaný prefix ze všech klíčů asociativního pole.

removePrefixFromFieldKeys(array $fields, string $prefix = 'f_'):array

Parametry:

Parametr	Typ	Popis
$fields	array	Pole s klíči obsahujícími prefix
$prefix	string	Prefix k odstranění (default: 'f_')

Návratová hodnota:

• Nové pole se stejnými hodnotami, ale bez zadaného prefixu v klíčích

Účel: Normalizace dat z HTML formulářů, kde se používá prefix pro identifikaci. Nejčastější použití je f_ prefix z admin formulářů.

Příklady:

$fields = [
    'f_name'      => 'John',
    'f_email'     => 'john@example.com',
    'f_age'       => 25
];

// Výchozí prefix 'f_'
$normalized = removePrefixFromFieldKeys($fields);

// Výsledek:
// [
//     'name'  => 'John',
//     'email' => 'john@example.com',
//     'age'   => 25
// ]

Vlastní prefix:

$fields = [
    'input_name'   => 'John',
    'input_email'  => 'john@example.com',
    'input_age'    => 25
];

// Vlastní prefix 'input_'
$normalized = removePrefixFromFieldKeys($fields, 'input_');

// Výsledek:
// [
//     'name'  => 'John',
//     'email' => 'john@example.com',
//     'age'   => 25
// ]

Regex speciální znaky:

Prefix je automaticky escapován, takže regex speciální znaky se bezpečně zpracují:

$fields = ['field.name' => 'John', 'field.email' => 'test@example.com'];

// Tečka se bezpečně escapuje
$normalized = removePrefixFromFieldKeys($fields, 'field.');
// Výsledek: ['name' => 'John', 'email' => 'test@example.com']

---

flattenArray()

Zploští vnořené pole na jednoúrovňové pole s oddělovačem v klíčích.

flattenArray(array $array, string $separator = ':'):array

Parametry:

Parametr	Typ	Popis
$array	array	Vnořené pole
$separator	string	Oddělovač pro klíče (default: ':')

Návratová hodnota:

• Jednoúrovňové pole s vnořenými klíči spojenými oddělovačem

Příklady:

$nested = [
    'customer' => [
        'name'  => 'John',
        'email' => 'john@example.com'
    ],
    'order' => [
        'id'     => 123,
        'total'  => 1500
    ]
];

$flat = flattenArray($nested);

// Výsledek:
// [
//     'customer:name'   => 'John',
//     'customer:email'  => 'john@example.com',
//     'order:id'        => 123,
//     'order:total'     => 1500
// ]

Vlastní oddělovač:

$flat = flattenArray($nested, '.');

// Výsledek:
// [
//     'customer.name'   => 'John',
//     'customer.email'  => 'john@example.com',
//     'order.id'        => 123,
//     'order.total'     => 1500
// ]

---

unflattenArray()

Rozpojí zploštěné pole zpět na vnořenou strukturu.

unflattenArray(array $array, string $separator = ':'):array

Parametry:

Parametr	Typ	Popis
$array	array	Zploštěné pole s oddělenými klíči
$separator	string	Oddělovač v klíčích (default: ':')

Návratová hodnota:

• Vnořené pole se rekonstruovanou strukturou

Poznámka: Tato funkce je inverzní operace k flattenArray(). Pokud zploštíš pole a pak ho rozvinueš, měl by se vrátit do původního stavu.

Příklady:

$flat = [
    'customer:name'   => 'John',
    'customer:email'  => 'john@example.com',
    'order:id'        => 123
];

$nested = unflattenArray($flat);

// Výsledek:
// [
//     'customer' => [
//         'name'  => 'John',
//         'email' => 'john@example.com'
//     ],
//     'order' => [
//         'id' => 123
//     ]
// ]

Reversibilita:

$original = ['user' => ['name' => 'John']];
$flat = flattenArray($original);
$restored = unflattenArray($flat);

// $restored === $original  (true)

---

Technické poznámky

Oddělovače

Všechny funkce pracující s klíči (getArrayValue, setArrayValue, deleteArrayValue, flattenArray, unflattenArray) akceptují parametr $separator:

• Výchozí: ':'
• Vlastní: Jakýkoliv string (např. ., /, |)

getArrayValue($array, 'smtp.use', false, '.');
setArrayValue($array, 'user/profile/name', 'John', '/');

Bezpečnost

• getArrayValue() vrací null pro neexistující klíče (bezpečné)
• deleteArrayValue() ignoruje neexistující klíče (bezpečné)
• setArrayValue() si vytvoří potřebné vnořené struktury automaticky

Performance

• Všechny funkce používají explode() pro rozdělení klíčů
• Pro hluboké vnořování (5+ úrovní) jsou relativně rychlé
• Pro hromadné operace v smyčce zvažuj cachování cest

---

Shrnutí

Funkce	Účel	Typ operace
getArrayValue()	Načtení vnořené hodnoty	Read
setArrayValue()	Nastavení vnořené hodnoty	Write
deleteArrayValue()	Smazání vnořené hodnoty	Delete
removePrefixFromFieldKeys()	Normalizace klíčů	Transform
flattenArray()	Zploštění struktury	Transform
unflattenArray()	Rozvinutí struktury	Transform