<?php

require_once __DIR__.'/utils.class.php';

/**
 * Interface d'implémentation d'un stockage de données « supplémentaires »
 */
abstract class extra_data_store_abs {

    /**
     * Initialisation d'une instance.
     *
     * @param  om_application  $framework  Une instance du framwork.
     *
     * @return extra_data_store_abs
     */
    public function __construct(application $framework) {
        $this->framework = $framework;
    }

    /**
     * Déclare une donnée « supplémentaire ».
     *
     * @param  string  $object_name  Nom de l'objet auquel est rattaché cette donnée
     * @param  string  $name         Nom de la donnée
     * @param  string  $type         Type de la donnée (int, str, json, blob, timestamp, etc)
     * @param     int  $length       Taille maximale de la donnée
     * @param  string  $libelle      Description de la donnée (dans les formulaires par ex.)
     * @param    bool  $list         'true' si le champ doit être montré dans les listing
     * @param    bool  $search       'true' si le champ doit être recherchable
     * @param  string  $alias        Alias de champ de fusion
     *
     * @return bool|string  'true' si l'opération s'est bien passé, sinon un message d'erreur
     */
    abstract public function setup_data(string $object_name, string $name, string $type, int $length, string $libelle, bool $list = false, bool $search = false, string $alias = '');

    /**
     * Enregistre une donnée « supplémentaire » en base de données.
     *
     * @param  string  $object_name  Le nom de l'objet (ou sa classe) correspondant à sa table en BDD
     * @param   array  $object_ids   La liste des identifiants des objets concernés
     * @param  string  $data_name    Le nom de la valeur stockée (nom du champ ou de la clé)
     * @param  string  $data_type    Le type de donnée à stocker (int, str, json, blob, timestamp, etc.)
     * @param   mixed  $data_value   La valeur à stocker
     *
     * @return extra_data_result|false
     * @return array  ([(<id objet>, <id donnée>), ...]|null, <message>|null)
     *                si l'opération a échouée le premier élément sera null,
     *                et un message d'erreur indiquera la raison de l'échec,
     *                sinon c'est l'inverse, le premier élément sera un tableau et il n'y
     *                aura aucun message (null).
     */
    abstract public function store_data(string $object_name, array $object_ids, string $data_name, string $data_type, $data_value);

    /**
     * Récupère une donnée « supplémentaire » en base de données.
     *
     * @param  string  $object_name  Le nom de l'objet (ou sa classe) correspondant à sa table en BDD
     * @param   array  $object_ids   La liste des identifiants des objets concernés
     * @param  string  $data_name    Le nom de la valeur stockée (nom du champ ou de la clé)
     * @param  string  $data_type    Le type de donnée à stocker (int, str, json, blob, timestamp, etc.)
     *
     * @return extra_data_result
     * @return array  ([(<id objet>, <id donnée>, <valeur>), ...]|null, <message>|null)
     *                si l'opération a échouée le premier élément sera null,
     *                et un message d'erreur indiquera la raison de l'échec,
     *                sinon c'est l'inverse, le premier élément sera un tableau et il n'y
     *                aura aucun message (null).
     */
    abstract public function get_data(string $object_name, array $object_ids, string $data_name, string $data_type);

    // TODO document
    abstract public function update_data(array $data_ids, string $data_type, $data_value);

    // TODO document
    abstract public function delete_data(array $data_ids, string $data_type);

    /**
     * Liste des données associées à un objet.
     *
     * @param  string  $object_name       Le nom de l'objet (ou sa classe) correspondant à sa table en BDD
     * @param  string  $mode              Si 'value' retourne les valeurs,
     *                                    si 'label' retourne les libellés,
     *                                    si 'type' retourne les types.
     * @param  string  $object_id         L'identifiant de l'objet concerné
     * @param    bool  $use_champ_fusion  Si 'true' utilise l'alias de champ de fusion à la place du nom de la donnée
     *
     * @return extra_data_result  Contenant la liste des nom des données ou bien clé/valeur pour chaque donnée
     * @return array  ([(<id objet>, <id donnée>, <valeur>), ...]|null, <message>|null)
     *                si l'opération a échouée le premier élément sera null,
     *                et un message d'erreur indiquera la raison de l'échec,
     *                sinon c'est l'inverse, le premier élément sera un tableau et il n'y
     *                aura aucun message (null).
     */
    abstract public function list_data(string $object_name, string $mode, string $object_id = '', bool $use_champ_fusion = false);

    /**
     * Log un message en lui ajoutant un préfixe.
     *
     * @param  string  $method   La méthode d'où provient le message (càd: __METHOD__)
     * @param  string  $message  Le message à écire dans le ficheir de logs
     * @param  string  $level    Le niveau de log
     *
     * @return void
     */
    protected function log(string $method, string $message, string $level = 'DEBUG') {

        $this->framework->log($method, $message, $level);
    }
}

/**
 * Représente un résultat d'un appel à l'une des méthodes store/get.
 */
class extra_data_result {
    public ?array $items = null;
    public ?string $error_message = null;

    public function __construct(?array $items, ?string $err_msg) {
        $this->items = $items;
        $this->error_message = $err_msg;
    }
}