nur-sery/src/db/CapacitorChannel.php

<?php
namespace nur\sery\db;

use nur\sery\cl;
use nur\sery\str;

/**
 * Class CapacitorChannel: un canal d'une instance de {@link ICapacitor}
 */
class CapacitorChannel {
  const NAME = null;

  const TABLE_NAME = null;

  const KEY_DEFINITIONS = null;

  const PRIMARY_KEYS = null;

  const EACH_COMMIT_THRESHOLD = 100;

  static function verifix_name(?string $name): string {
    if ($name === null) $name = "default";
    return strtolower($name);
  }

  function __construct(?string $name=null, ?int $eachCommitThreshold=null) {
    $this->name = self::verifix_name($name ?? static::NAME);
    $this->eachCommitThreshold = $eachCommitThreshold ?? static::EACH_COMMIT_THRESHOLD;
    $this->created = false;
    $keyDefinitions = cl::withn(static::KEY_DEFINITIONS);
    $primaryKeys = cl::withn(static::PRIMARY_KEYS);
    if ($primaryKeys === null && $keyDefinitions !== null) {
      $index = 0;
      foreach ($keyDefinitions as $col => $def) {
        if ($col == $index) {
          $index++;
          if (preg_match('/\bprimary\s+key\s+\((.+)\)/i', $def, $ms)) {
            $primaryKeys = preg_split('/\s*,\s*/', trim($ms[1]));
          }
        } else {
          if (preg_match('/\bprimary\s+key\b/i', $def)) {
            $primaryKeys[] = $col;
          }
        }
      }
    }
    $this->keyDefinitions = $keyDefinitions;
    $this->primaryKeys = $primaryKeys;
  }

  /** @var string */
  protected $name;

  function getName(): string {
    return $this->name;
  }

  function getTableName(): string {
    return static::TABLE_NAME ?? ($this->name."_channel");
  }

  /**
   * @var ?int nombre maximum de modifications dans une transaction avant un
   * commit automatique dans {@link Capacitor::each()}. Utiliser null pour
   * désactiver la fonctionnalité.
   */
  protected $eachCommitThreshold;

  function getEachCommitThreshold(): ?int {
    return $this->eachCommitThreshold;
  }

  protected $created;

  function isCreated(): bool {
    return $this->created;
  }

  function setCreated(bool $created=true): void {
    $this->created = $created;
  }

  protected ?array $keyDefinitions;

  /**
   * retourner un ensemble de définitions pour des colonnes supplémentaires à
   * insérer lors du chargement d'une valeur
   *
   * la clé primaire "id_" a pour définition "integer primary key autoincrement".
   * elle peut être redéfinie, et dans ce cas la valeur à utiliser doit être
   * retournée par {@link getKeyValues()}
   *
   * la colonne "item__" contient la valeur sérialisée de l'élément chargé. bien
   * que ce soit possible techniquement, cette colonne n'a pas à être redéfinie
   *
   * les colonnes dont le nom se termine par "_" sont réservées.
   * les colonnes dont le nom se termine par "__" sont automatiquement sérialisées
   * lors de l'insertion dans la base de données, et automatiquement désérialisées
   * avant d'être retournées à l'utilisateur (sans le suffixe "__")
   */
  function getKeyDefinitions(): ?array {
    return $this->keyDefinitions;
  }

  protected ?array $primaryKeys;

  function getPrimaryKeys(): ?array {
    return $this->primaryKeys;
  }

  /**
   * calculer les valeurs des colonnes supplémentaires à insérer pour le
   * chargement de $item
   *
   * Cette méthode est utilisée par {@link Capacitor::charge()}. Si une valeur
   * "id_" est retourné, la ligne correspondate existante est mise à jour
   */
  function getKeyValues($item): ?array {
    return null;
  }

  /**
   * Avant d'utiliser un id pour rechercher dans la base de donnée, corriger sa
   * valeur le cas échéant.
   */
  function verifixId(string &$id): void {
  }

  /**
   * méthode appelée lors du chargement d'un élément avec
   * {@link Capacitor::charge()}
   *
   * @param mixed $item l'élément à charger
   * @param array $updates les valeurs calculées par {@link getKeyValues()}
   * @param ?array $row la ligne à mettre à jour. vaut null s'il faut insérer
   * une nouvelle ligne
   * @return ?array le cas échéant, un tableau non null à merger dans $updates
   * et utilisé pour provisionner la ligne nouvellement créée, ou mettre à jour
   * la ligne existante
   *
   * Si $item est modifié dans cette méthode, il est possible de le retourner
   * avec la clé "item" pour mettre à jour la ligne correspondante.
   * La colonne "id_" ne peut pas être modifiée: si "id_" est retourné, il est
   * ignoré
   */
  function onCharge($item, array $updates, ?array $row): ?array {
    return null;
  }

  /**
   * méthode appelée lors du parcours des éléments avec
   * {@link Capacitor::each()}
   *
   * @param mixed $item l'élément courant
   * @param ?array $row la ligne à mettre à jour.
   * @return ?array le cas échéant, un tableau non null utilisé pour mettre à
   * jour la ligne courante
   *
   * Si $item est modifié dans cette méthode, il est possible de le retourner
   * avec la clé "item" pour mettre à jour la ligne correspondante
   * La colonne "id_" ne peut pas être modifiée: si "id_" est retourné, il est
   * ignoré
   */
  function onEach($item, array $row): ?array {
    return null;
  }
}