Co YAML vlastně je a k čemu slouží?

Zkratka YAML vznikla z věty Ain’t Markup Language. Už sám název napovídá, že se nejedná o značkovací jazyk. Dle oficiální dokumentace jde o lidsky přívětivý standard k serializaci dat pro všechny programovací jazyky.

V zápisu nehledejte žádné složitosti

Pro jednoduché datové typy (string, boolean, float nebo integer) má stejnou syntaxi jako PHP. Na rozdíl od PHP rozlišuje pole na sekvence – v PHP indexované pole [‘pdo_pgsql’] a hash v PHP asociativní pole [‘driver‘ => ‘pdo_pgsql’].

YAML syntaxe v kostce

Ukážeme si několik příkladů, které v konfiguraci využijeme nejčastěji. Více se dočtete v oficiální dokumentaci.

Řetězce

Přestože YAML umožňuje více způsobů pro zápis řetězců, doporučuji stringy uvádět do uvozovek. Symfony 3 totiž jiný formát nerespektuje.

Čísla

Se zapisují identicky s PHP.

• Integer: 319
• Float: 31.9
• Hexadecimální: 0x13f

NULL

Akceptovány jsou hodnoty null nebo ~.

Boolean

Stejně, jak jsme zvyklí Z PHP zapisujeme true/false.

Kolekce

YAML rozlišuje dva druhy – sekvence a hash (mapování).

• Sekvence (PHP indexované pole)

YAML zápis

- "XML"
- "PHP"
- "YML"

PHP ekvivalent

['XML', 'PHP', 'YML']

• Hash (PHP asociativní pole) lze uvést dvěma způsoby

YAML zápis

database: 
    host: "localhost"
    username: "roxtri"
    password: "yamlConfig"

nebo

{database: {host: "localhost", username: "roxtri", password: "yamlConfig"}}

PHP ekvivalent

[
    'database' => [
        'host' => 'localhost',
        'username' => 'roxtri',
        'password' => 'yamlConfig'
    ]
];

Ovšem, pozor na tento způsob zápisu!

YAML syntaxe

database: [ host: "localhost", username: "roxtri", password: "yamlConfig" ]

PHP ekvivalent

[
    'database' =>
    [
        0 => ['host' =>'localhost'],
        1 => ['username' =>'roxtri'],
        2 => ['password' =>'yamlConfig']
    ]
];

YAML Component

K převodu YAML na PHP pole a samozřejmě také reverzní konverzi Symfony poskytuje komponentu YAML. Respektuje specifikaci verze YAML 1.2. Podívejme se, jak je její použití jednoduché.

K instalaci můžeme využít Composer

composer require symfony/yaml

Pro konverzi YAML na PHP pole souží Parser

// index.php
require_once __DIR__ . '/vendor/autoload.php';

$yaml = new Symfony\Component\Yaml\Parser();
$phpArray = $yaml->parse(file_get_contents('/path/to/file.yml'));

// /path/to/file.yml
locales: ["cs", "en"]
default_format: "json"
log_history: true
price: 2000

PHP výstup

[
    'locales' =>
    [
        0 => 'cs',
        1 => 'en'
    ],
    'default_format' => 'json',
    'log_history' => true,
    'price' => 2000
];

Jak načítání konfigurace funguje?

Nejprve dojde k nalezení zdrojů pomocí třídy FileLocator, poté k načtení příslušným loaderem. Symfony poskytuje pro tyto účely komponentu Config. Ta umožňuje nalezení, načtení, slučování, automatického vyplňování a ověřování konfigurační hodnoty jakéhokoliv druhu, bez ohledu na jejich zdroj (YAML, XML, INI soubory, nebo například databáze).

Lokalizace zdrojů

Načítání konfigurace začíná hledáním zdrojů. K tomuto účelu slouží třída FileLocator, která v konstruktoru přijímá cestu nebo pole cest k adresářům, kde jsou konfigurační soubory umístěny. Na locatoru zavoláme metodu locate, kdy první argument je název souboru, druhý nepovinný udává cestu, kde bude soubor hledán jako první, třetí určuje, zda se vrátí hodnoty z prvního nalezeného souboru nebo pole všech nalezených.

Podívejme se na jednoduchou ukázku

K instalaci opět použijeme Composer

composer require symfony/yaml

// index.php
require_once __DIR__'./vendor/autoload.php';

$locator = new Symfony\Component\Config\FileLocator(__DIR__.'/app/config');
$yamlUserFiles = $locator->locate('config.yml');

Načítání konfigurace

Pro každý typ zdroje (YAML, XML…) musí být definován loader (implementující LoaderInterface, potomek abstraktní třídy FileLoader) umožňující rekurzivní načítání dalších zdrojů.

V každém konfiguračním YAML souboru můžeme implementovat sekci imports. Ta slouží k načítání dalších konfiguračních souborů:

// config.yml
imports:
  - { resource: parameters.yml }
  - { resource: security.yml }

Konfigurace routování

Specifikuje mapování URL k příslušnému controlleru. Nejčastěji využijeme soubor v cestě app/config/routing.yml, ale v config.yml lze lokalizaci libovolně upravit.

# app/config/config.yml
framework:
    # ...
    router: { resource: "%kernel.root_dir%/config/routing.yml" }

PHP zápis

[
    'framework' => [
        'router' => [
            'resource' => '%kernel.root_dir%/config/routing.yml'
        ]
    ]
];

Zase o krok dál

Číst i psát konfigurační soubory v YAMLu již zvládáme levou zadní. Narazíte-li na nastavení, která jste se v článku nedočetli, jistě odpověď naleznete v oficiální dokumentaci Symfony či samotného Yamlu. Tento formát pro svou jednoduchost a přehlednost je dobrý v podstatě pro všechna nastavení: překladů, rout, služeb i definování parametrů. Způsob konfigurace Symfony je velmi propracovaný, věnuje se mu komponenta Config.