Část III · Enum sloupce

8.1. Sloupec nad backed enumem

addEnum($alias, $title, Enum::class) – totéž co addSelect(), jen nabídku nepíšete: vezme se z cases(). Název case je hodnota v databázi, backed hodnota je popisek.

Ukázka

Táž kategorie třikrát: přeložená enumem, syrová přes add() a se výjimkou – u posledních kusů (skladem méně než 20) vrací dotaz last_pieces, což žádný case není. Seřaďte si grid podle Skladem, ať je vidět.

Zdrojový kód

php app/Modules/AdminModule/Components/Docs/Columns/EnumBasicGridControl/EnumBasicGridControl.php

<?php

declare(strict_types=1);

namespace App\Components\Docs\Columns\EnumBasicGridControl;

use Xart\Grid\Button\ButtonManager;
use Xart\Grid\Column\ColumnManager;
use Xart\Grid\Control\GridControl;
use Xart\Grid\DataOutput\Row;
use Xart\Grid\DataSource\DataSource;
use Xart\Grid\DataSource\SQL\SQLDataSource;

/**
 * Dokumentace, kapitola 8.1 – Sloupec nad backed enumem.
 *
 * Táž kategorie třikrát: přeložená enumem, syrová z databáze a s hodnotou, kterou enum nezná.
 */
class EnumBasicGridControl extends GridControl
{
    public function createDataSource(): DataSource
    {
        return new SQLDataSource(__DIR__ . '/EnumBasicGridControl.sql');
    }


    public function columns(ColumnManager $cm): void
    {
        $cm->add('name', 'Název');

        // Klíčem je název case (to, co je v databázi), popiskem jeho backed hodnota.
        $cm->addEnum('category', 'Kategorie', PlainCategory::class);

        // Tentýž sloupec bez enumu – v buňce zůstane hodnota z databáze a filtr je textový.
        $cm->add('category_raw', 'Kategorie přes add()');

        // U posledních kusů vrací dotaz „last_pieces“, což žádný case není: hodnota projde jako text.
        $cm->addEnum('category_mixed', 'Kategorie s výjimkou', PlainCategory::class);

        $cm->addNumber('quantity', 'Skladem', 0);
    }


    public function buttons(ButtonManager $bm): void
    {
    }


    public function rows(Row $row): void
    {
    }


    public function render(): void
    {
        $this->template->render(__DIR__ . '/EnumBasicGridControl.latte');
    }
}

php app/Modules/AdminModule/Components/Docs/Columns/EnumBasicGridControl/PlainCategory.php

<?php

declare(strict_types=1);

namespace App\Components\Docs\Columns\EnumBasicGridControl;

/**
 * Kategorie produktu jako holý string-backed enum – bez jediného prezentačního rozhraní
 * (ta jsou v kapitole 8.2). Název case odpovídá hodnotě v databázi, backed hodnota je popisek.
 *
 * Aplikace sandboxu má tutéž kategorii i s prezentací ({@see \App\Enum\ProductCategory}); tady
 * schválně není, aby bylo vidět, jak vypadá addEnum() sám o sobě.
 */
enum PlainCategory: string
{
    case electronics = 'Elektronika';
    case clothing = 'Oblečení';
    case books = 'Knihy';
    case home = 'Dům a zahrada';
    case toys = 'Hračky';
}

sql app/Modules/AdminModule/Components/Docs/Columns/EnumBasicGridControl/EnumBasicGridControl.sql

SELECT
    p.id,
    p.name,
    p.category,
    p.category AS category_raw,
    IF(p.quantity < 20, 'last_pieces', p.category) AS category_mixed,
    p.quantity
FROM `product` p

Jak se enum mapuje na sloupec

enum PlainCategory: string
{
	case electronics = 'Elektronika';   // klíč = electronics, popisek = Elektronika
	…
}

V databázi je electronics, v buňce Elektronika. Nabídka filtru vznikne z cases() v pořadí, v jakém jsou case zapsané – a protože klíčem je název case, musí být zapsaný přesně tak, jak je hodnota uložená. Enum musí být string-backed; int-backed grid nepřijme.

Hodnota, kterou enum nezná

Nespadne nic – hodnota projde do buňky jako prostý text, tak jak přišla z databáze (v ukázce sloupec Kategorie s výjimkou). Tak se chovají staré záznamy po zúžení číselníku i data, která do enumu nikdy nepatřila. Ve filtru taková hodnota není – nabídka zná jen case; dopsat si ji uživatel může jedině s $custom = true (kapitola 8.4).

Kdy enum a kdy addSelect

Enum, když číselník žije v kódu – popisky se pak nepíšou dvakrát a nabídku nejde rozejít s daty.
addSelect(), když nabídka vzniká za běhu (z tabulky, z API, podle práv uživatele) – kapitola 7.
Enum navíc umí prezentaci case: ikonu, barvu, pilulku a zkratku. O tom je kapitola 8.2 – enum v téhle ukázce schválně žádnou nemá.