<?php
/**
 * Registry Class
 *
 * @version     1.0.0
 * @package     bplan-base/globals
 * @subpackage  Registries
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025, 2026 bplan-solutions GmbH & Co. KG <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Registries;


/**
 * Registry Class
 *
 * Verwaltet die Liste der Modell-Felder, die über den Dynamic Form Designer
 * geladen und gespeichert werden können.
 *
 * Jedes Paket registriert seine eigenen Felder im ServiceProvider:
 *
 *      DynamicFormRegistry::register(
 *          PrinterType::class,
 *          'config_template',
 *          'label'
 *      );
 *
 * @version     1.0.0 / 2026-05-24
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
class DynamicFormRegistry
{


/* +++ TRAITS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS CONSTANTS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ OBJECT MEMBERS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS MEMBERS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * @var     array<string, array{modelClass: string, field: string, labelColumn: string, displayName: string}>
     */
    protected static array $_sources = [];


/* +++ OBJECT METHODS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS METHODS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * Gibt alle registrierten Quellen zurück.
     *
     * @return      array<string, array{modelClass: string, field: string, labelColumn: string, displayName: string}>
     *
     * @version     1.0.0 / 2026-05-24
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function all(): array
    {
        return static::$_sources;

    } // all()


    /**
     * Gibt den Registry-Schlüssel für eine Modell-Feld-Kombination zurück.
     *
     * @param       string $modelClass
     * @param       string $field
     *
     * @return      string
     *
     * @version     1.0.0 / 2026-05-24
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function key(string $modelClass, string $field): string
    {
        return $modelClass . '::' . $field;

    } // key()


    /**
     * Gibt eine registrierte Quelle anhand ihres Schlüssels zurück.
     *
     * @param       string $key
     *
     * @return      array{modelClass: string, field: string, labelColumn: string, displayName: string}|null
     *
     * @version     1.0.0 / 2026-05-24
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function get(string $key): ?array
    {
        return static::$_sources[$key] ?? null;

    } // get()


    /**
     * Registriert ein Modell-Feld als Dynamic-Form-Quelle.
     *
     * @param       string $modelClass
     *              Vollständiger Klassenname des Eloquent-Modells.
     *
     * @param       string $field
     *              Name des JSON-Feldes das das config_template enthält.
     *
     * @param       string $labelColumn
     *              Spaltenname der für die Anzeige im Datensatz-Dropdown verwendet wird.
     *
     * @param       string $displayName
     *              Anzeigename im Quellen-Dropdown. Wird aus Klasse + Feld abgeleitet wenn leer.
     *
     * @return      void
     *
     * @version     1.0.0 / 2026-05-24
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function register(
        string $modelClass,
        string $field,
        string $labelColumn,
        string $displayName = ''
    ): void
    {
        $key = static::key($modelClass, $field);

        static::$_sources[$key] = [
            'modelClass'  => $modelClass,
            'field'       => $field,
            'labelColumn' => $labelColumn,
            'displayName' => $displayName !== '' ? $displayName : class_basename($modelClass) . ' → ' . $field,
        ];

    } // register()


} // class DynamicFormRegistry {}
