<?php
/**
 * Registry Class
 *
 * @todo        Es muss noch ein Weg gefunden werden wie Links in Abhängigkeit von User-Berechtigungen
 *              aus der Liste entfernt werden können.
 *              Problem dabei:
 *              Die Registrierung von Links erfolgt im ServiceProvider, da ist der aktuelle User noch
 *              nicht initialisiert.
 *              Also muss die Prüfung der Berechtigungen im Nachgang erfolgen. Das geht nur in dem
 *              Moment in dem die Liste abgerufen wird, also in der all-und in der get-Methode.
 *              Lösungsansatz:
 *              Die Register-Methode erhält die Rollen in Form eines Arrays übergeben. In der all-Methode
 *              wird für jeden Link geprüft ob der User über die erforderliche Berechtigung verfügt. Am
 *              Ende wird dann eine bereinigte Liste zurückgegeben.
 *              Umgesetzt werden sollte diese Funktionalität erst wenn das Rollen-/Berechtigungssystem
 *              überarbeitet wurde. Dazu müsste dann hier auch noch die get-Methode implementiert werden.
 *
 * @version     1.0.$Revision:$
 * @version     SVN: $Id:$
 * @package     bplan-base/globals
 * @subpackage  Registries
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025, 2026 Wassilios Meletiadis <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Registries;


use BadMethodCallException;


/**
 * Registry Class
 *
 * @version     1.3.0 / 2026-05-09
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
class QuickLinkRegistry extends Registry
{


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


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


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


    /**
     * @var     string
     */
    private static string $_registrykey = 'quick-links';


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


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


    /**
     *
     * @return      array
     *
     * @version     1.1.0 / 2026-03-11
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function all(): array
    {
        return parent::get(self::$_registrykey);

    } // all()


    /**
     * Leert die Liste der Quick-Links und gibt den vollständigen, ursprünglichen Inhalt zurück
     *
     * @return      array
     *
     * @version     1.1.0 / 2026-03-11
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function flush(): array
    {
        $return = self::get(self::$_registrykey);

        parent::forget(self::$_registrykey, true);

        return $return;

    } // flush()


    /**
     * Schlüssel und zugehörigen Wert löschen
     *
     * @param       string $key
     *
     * @param       bool $force
     *
     * @throws      RuntimeException
     *
     * @return      mixed Der vorherige Wert oder NULL
     *
     * @version     1.1.0 / 2026-03-11
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function forget(string $key, bool $force = false): mixed
    {
        $value = parent::get(self::$_registrykey.'.'.$key, null);

        parent::forget(self::$_registrykey.'.'.$key, $force);

        return $value;

    } // forget()


    /**
     *
     * @return      bool
     *
     * @version     1.1.0 / 2026-03-11
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function has(string $key, mixed $default = null): bool
    {
        return parent::has(self::$_registrykey.'.'.$key);

    } // has()


    /**
     * Wert(e) setzen
     *
     * @param       string $key
     *
     * @param       mixed $value
     *
     * @param       bool $readonly
     *
     * @throws      BadMethodCallException
     *
     * @return      void
     *
     * @version     1.0.0 / 2026-03-06
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function put(string $key, mixed $value, bool $readonly = false): void
    {
        throw new BadMethodCallException('Use '.__CLASS__.'::register() to register quick links.');

    } // put()


    /**
     *
     * @param       string $key
     *
     * @param       string $localeKey
     *
     * @param       string $route
     *
     * @param       null|string $icon
     *
     * @param       null|array $params
     *
     * @param       null|array $roles
     *
     * @return      void
     *
     * @version     3.0.0 / 2026-05-09
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public static function register(string $key, string $localeKey, string $route, null|string $icon = null, array|null $params = null, array|null $roles = null): void
    {
        parent::put(self::$_registrykey.'.'.$key, [
            'icon'       => $icon,
            'locale-key' => $localeKey,
            'params'     => $params,
            'roles'      => $roles,
            'route'      => $route,
        ]);
    } // register()


} // class QuickLinkRegistry extends Registry {}
