YAML – Načítání a Manipulace

Funkce pro práci s YAML soubory. Obal kolem Symfony\Component\Yaml s dodatečnou logikou pro stránky a error handling.

Přehled

Petrovo\Yaml poskytuje čtyři funkce pro:

• Načítání a parsování YAML souborů
• Konverzi polí na YAML formát
• Přeformátování souborů
• Slučování konfiguračních dat

Funkce

load()

Načte a parsuje YAML soubor.

use function Petrovo\Yaml\load;

// Základní načítání
$config = load('/app/config/settings.yaml');

// Bez .yaml přípony (přidá se automaticky)
$config = load('/app/config/settings');

// S override šablony
$config = load('/path/to/page', 'custom-template');

Podpis:

function load(string $filename, string $changeTemplate = ''): array

Parametry:

• $filename - Cesta k souboru (s .yaml nebo bez)
• $changeTemplate - (Volitelně) Přepíše pole template v načtených datech

Vrací: Asociativní pole s parsovanými YAML daty, nebo prázdné pole pokud soubor neexistuje

Chování:

• Automaticky přidá .yaml příponu, pokud chybí
• Pokud je soubor stránka (v cestě /pages/) a má méně než 2 prvky:
• Nastaví chybu do session: $_SESSION['exit']
• Type: page
• Message: Page [filename] not found or is empty.

Příklady:

// Načítání konfigurace
$settings = load('/config/session.yaml');
// Vrátí: ['gc_maxlifetime' => 1800, 'name' => 'PHPSESSID', ...]

// Načítání stránky s auto-error handling
$page = load('/pages/home');
// Pokud neexistuje nebo je prázdná, nastaví $_SESSION['exit']

// Override šablony
$page = load('/pages/contact', 'contact-form');
// $page['template'] bude 'contact-form' místo původní

---

dump()

Konvertuje PHP pole na YAML formát.

use function Petrovo\Yaml\dump;

$data = [
    'title' => 'My Page',
    'items' => ['one', 'two', 'three'],
];

$yaml = dump($data);
echo $yaml;
// title: My Page
// items:
//   - one
//   - two
//   - three

Podpis:

function dump(array $array): string

Parametry: - $array - pole k převodu

Vrací: YAML řetězec s 4-úrovňovou hloubkou a 2-mezerovou indentací

Chování:

• Pro indexovaná pole (klíče 0,1,2...): Vrátí jen hodnoty jako seznam
• Pro asociativní pole: Zachovává strukturu klíč-hodnota
• Formátování: 4 úrovně hloubky, 2-mezerové odsazení

Příklady:

// Asociativní pole
$data = ['name' => 'John', 'age' => 30];
echo dump($data);
// name: John
// age: 30

// Indexované pole
$data = ['apple', 'banana', 'cherry'];
echo dump($data);
// - apple
// - banana
// - cherry

// Vnořené struktury
$data = [
    'user' => ['name' => 'John', 'email' => 'john@example.com'],
    'items' => ['a', 'b'],
];
echo dump($data);
// user:
//   name: John
//   email: john@example.com
// items:
//   - a
//   - b

---

reformat()

Přeformátuje YAML soubor na konzistentní formát.

use function Petrovo\Yaml\reformat;

// Přeformátuje soubor a zapíše ho zpět
$success = reformat('/config/my-config.yaml');

if ($success) {
    echo 'File reformatted';
} else {
    echo 'File not found or write failed';
}

Podpis:

function reformat(string $file): bool

Parametry: - $file - Cesta k YAML souboru

Vrací: true pokud byl úspěšně přeformátován, false pokud soubor neexistuje nebo zápis selhal

Chování:

1. Kontroluje, zda soubor existuje
2. Načte a parsuje jej pomocí load()
3. Konvertuje zpět na YAML pomocí dump()
4. Zapíše normalizovaný obsah zpět do souboru

Použití:

// Normalizace formátování
reformat('/app/config/session.yaml');

// Hromadné přeformátování
$files = glob('/app/config/*.yaml');
foreach ($files as $file) {
    reformat($file);
}

---

joinTwo()

Sloučí dva YAML arraye kombinováním specifických polí a form_fields sekcí.

use function Petrovo\Yaml\joinTwo;

$base = [
    'title' => 'Base Title',
    'form_fields' => [
        ['name' => 'field1'],
        ['ADD_SECTIONS' => true],  // Marker pro vložení
        ['name' => 'field2'],
    ],
];

$override = [
    'title' => 'Override Title',
    'header_new' => 'New Item',
    'header_edit' => 'Edit Item',
    'form_fields' => [
        ['name' => 'added1'],
        ['name' => 'added2'],
    ],
];

$merged = joinTwo($base, $override);

Podpis:

function joinTwo(array $y1, array $y2): array

Parametry:

• $y1 - Základní YAML pole (sloučí SE)
• $y2 - Override YAML pole (sloučí Z)

Vrací: Sloučené pole

Chování:

1. Zkopíruje pole z $y2 do $y1:
2. title
3. header_new

4. header_edit

5. Sloučí form_fields:

6. Iteruje přes $y1['form_fields']
7. Když najde pole s klíčem ADD_SECTIONS, vloží všechny $y2['form_fields'] na to místo
8. Zachovává ostatní pole z $y1

Příklad s form_fields:

$y1 = [
    'title' => 'Original',
    'form_fields' => [
        ['name' => 'field_a'],
        ['ADD_SECTIONS' => true],    // Zde se vloží y2 fields
        ['name' => 'field_z'],
    ],
];

$y2 = [
    'title' => 'Extension',
    'form_fields' => [
        ['name' => 'field_x'],
        ['name' => 'field_y'],
    ],
];

$result = joinTwo($y1, $y2);

// Výsledek form_fields:
// [
//   ['name' => 'field_a'],
//   ['name' => 'field_x'],      // z y2
//   ['name' => 'field_y'],      // z y2
//   ['name' => 'field_z'],
// ]

Praktické použití:

// Sloučení base konfigu s custom fieldy
$baseForm = load('/app/cubes/default/data.yaml');
$customForm = load('/app/cubes/custom-override/data.yaml');

$merged = joinTwo($baseForm, $customForm);
// Nyní má custom pole v místě ADD_SECTIONS

---

Příklady

Načítání a Přeformátování

use function Petrovo\Yaml\load;
use function Petrovo\Yaml\reformat;

// Načti konfiguraci
$config = load('/config/database');

// Modifikuj
$config['debug'] = true;

// Zapíšu zpět (můžeš měnit přímo v souboru a pak přeformátovat)
// ...

// Přeformátuj na konzistentní formát
reformat('/config/database.yaml');

Výroba Konfigurace

use function Petrovo\Yaml\dump;

$newConfig = [
    'server' => 'localhost',
    'port' => 3306,
    'username' => 'user',
];

$yaml = dump($newConfig);
file_put_contents('/config/database.yaml', $yaml);

Dynamické Slučování

use function Petrovo\Yaml\load;
use function Petrovo\Yaml\joinTwo;

// Načti base teplotu
$baseTemplate = load('/app/cubes/button/data.yaml');

// Načti override
$customTemplate = load('/app/cubes/button-extended/data.yaml');

// Sloučit s vložením custom fields
$finalTemplate = joinTwo($baseTemplate, $customTemplate);

// Použití v aplikaci
// ...

---

Integrace s Aplikací

V Cocks/Components

use function Petrovo\Yaml\load;

// Načtení cube typu
$cubeType = load(DIR . '/app/cubes/button/data');

// Načtení s override šablony
$cubeType = load(DIR . '/app/cubes/button/data', 'custom-button-template');

V Controlleru

use function Petrovo\Yaml\load;
use function Petrovo\Yaml\dump;

// Načtení konfigurace strany
$pageConfig = load('/pages/home');

// Modifikace a uložení
if ($modified) {
    // ... změny v $pageConfig
    file_put_contents($file, dump($pageConfig));
}

---

Chyby a Validace

Error Handling pro Stránky

Když load() detekuje, že je to stránka (v cestě /pages/) a soubor neexistuje nebo je prázdný:

$_SESSION['exit'] = [
    'type' => 'page',
    'message' => 'Page /pages/contact.yaml not found or is empty.',
    'url' => 'https://example.com/contact',
];

Middleware pak zobrazí chybu.

Ruční Validace

use function Petrovo\Yaml\load;

$data = load('/config/my-config');

if (empty($data)) {
    // Soubor neexistuje nebo je prázdný
    throw new Exception('Configuration not found');
}

---

API Reference

Funkce	Parametry	Vrací	Popis
load()	string, string	array	Načte YAML soubor
dump()	array	string	Konvertuje array na YAML
reformat()	string	bool	Přeformátuje YAML soubor
joinTwo()	array, array	array	Sloučí dvě YAML pole

---

Reference

• Symfony YAML Component
• YAML Specification