nur-sery/src/schema/README.md

# nulib\schema

objet: s'assurer que des données soit dans un type particulier, en les
convertissant si nécessaire. la source de ces données peut-être diverse:
formulaire web, résultat d'une requête SQL, flux CSV, etc.

les données dont on peut modéliser le schéma sont de 3 types:
* scalaire
* tableau associatif
* liste (tableau séquentiel ou associatif d'éléments du même type)

chaque type de données a une syntaxe spécifique pour la définition du schéma.

## Nature de schéma

Un schéma se présente sous la forme d'un tableau associatif avec des clés qui
dépendent de la nature du schéma. La nature du schéma est indiquée avec la clé
`""` (chaine vide), e.g
~~~php
const SCHEMA = [
  "" => NATURE,
];
~~~

La nature indique le type de données représenté par le schéma.
* nature scalaire: modélise une donnée scalaire
  ~~~php
  const SCALAR_SCHEMA = [
    $type, [$default, $title, ...]
    "" => "scalar",
  ];
  ~~~
  Si le type est "array" ou "?array", on peut préciser le schéma de la donnée
  ~~~php
  const SCALAR_SCHEMA = [
    "?array", [$default, $title, ...]
    "" => "scalar",
    "schema" => NAKED_SCHEMA,
  ];
  ~~~
* nature tableau associatif: modélise un tableau associatif (le tableau peut
  avoir des clés numériques ou chaines --> seules les clés décrites par le
  schéma sont validées)
  ~~~php
  const ASSOC_SCHEMA = [
    KEY => VALUE_SCHEMA,
    ...
    "" => "assoc",
  ];
  // strictement équivalent à
  const ASSOC_SCHEMA = [
    "?array", [$default, $title, ...]
    "" => "scalar",
    "schema" => [
      KEY => VALUE_SCHEMA,
      ...
    ],
  ];
  ~~~
* nature liste: modélise une liste de valeurs du même type (le tableau peut
  avoir des clés numériques ou chaines --> on ne modélise ni le type ni la
  valeur des clés)
  ~~~php
  const LIST_SCHEMA = [
    "?array", [$default, $title, ...]
    "" => "list",
    "schema" => ITEM_SCHEMA,
  ];
  ~~~

## Schéma d'une valeur scalaire

Dans sa forme normalisée, une valeur scalaire est généralement modélisée de
cette manière:
~~~php
const SCALAR_SCHEMA = [
  "type" => "types autorisés de la valeur",
  "default" => "valeur par défaut si la valeur n'existe pas",
  "title" => "libellé de la valeur, utilisable par exemple dans un formulaire",
  "required" => "la valeur est-elle requise? si oui, elle doit exister",
  "nullable" => "si la valeur existe, peut-elle être nulle?",
  "desc" => "description de la valeur",
  "checker_func" => "une fonction qui vérifie une valeur et la classifie",
  "parser_func" => "une fonction qui analyse une chaine pour produire la valeur",
  "messages" => "messages à afficher en cas d'erreur d'analyse",
  "formatter_func" => "une fonction qui formatte la valeur pour affichage",
  "format" => "format à utiliser pour l'affichage",
  "" => "scalar",
  "schema" => "schéma de la valeur si le type est array ou ?array, null sinon",
];
~~~

L'ordre des clés du schéma ci-dessus indique la clé associé à une valeur si elle
est fournie dans un tableau séquentiel. Par exemple, les deux schéma suivants
sont équivalents:
~~~php
const SCALAR_SCHEMA1 = [
  "string", null, "une valeur chaine",
];
const SCALAR_SCHEMA2 = [
  "type" => "string",
  "default" => null,
  "title" => "une valeur chaine",
  "" => "scalar",
];
~~~

Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de
nature scalaire si:
* c'est une chaine, qui représente alors le type, e.g `"string"`
* c'est un tableau avec un unique élément à l'index 0 de type chaine, qui est
  aussi le type, e.g `["string"]`
* c'est un tableau avec un élément à l'index 0, ainsi que d'autres éléments,
  e.g `["string", null, "required" => true]`

message indique les messages à afficher en cas d'erreur d'analyse. les clés sont
normalisées et correspondent à différents états de la valeur tels qu'analysés
par `checker_func`
~~~php
const MESSAGE_SCHEMA = [
  "missing" => "message si la valeur n'existe pas dans la source et qu'elle est requise",
  "unavailable" => "message si la valeur vaut false dans la source et qu'elle est requise",
  "null" => "message si la valeur est nulle et qu'elle n'est pas nullable",
  "empty" => "message si la valeur est une chaine vide et que ce n'est pas autorisé",
  "invalid" => "message si la valeur est invalide",
];
~~~

## Schéma d'un tableau associatif

Dans sa forme *non normalisée*, un tableau associatif est généralement modélisé
de cette manière:
~~~php
const ASSOC_SCHEMA = [
  KEY => VALUE_SCHEMA,
  ...
  "" => "assoc",
];
~~~
où chaque occurrence de `KEY => VALUE_SCHEMA` définit le schéma de la valeur
dont la clé est `KEY`

Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de
nature associative si:
* c'est un tableau uniquement associatif avec aucun élément séquentiel, e.g
  `["name" => "string", "age" => "int"]`

VALUE_SCHEMA peut-être n'importe quel schéma valide, qui sera analysé
récursivement, avec cependant l'ajout de quelques clés supplémentaires:
* description de la valeur dans le contexte du tableau
  ~~~php
  VALUE_SCHEMA = [
    ...
    "name" => "identifiant de la valeur",
    "pkey" => "chemin de clé de la valeur dans le tableau associatif",
  ];
  ~~~
* s'il s'agit d'une valeur scalaire simple autre que array
  ~~~php
  VALUE_SCHEMA = [
    ...
    "header" => "nom de l'en-tête s'il faut présenter cette donnée dans un tableau",
    "composite" => "ce champ fait-il partie d'une valeur composite?",
  ];
  ~~~

## Schéma d'une liste (tableau séquentiel ou associatif d'éléments du même type)

Dans sa forme *non normalisée*, une liste est généralement modélisée de cette
manière:
~~~php
const LIST_SCHEMA = [ITEM_SCHEMA];
~~~
où ITEM_SCHEMA est le schéma des éléments de la liste

Pour information, la forme normalisée est plutôt de la forme
~~~php
const LIST_SCHEMA = [
  "?array", "schema" => ITEM_SCHEMA,
  "" => "list",
];
~~~
le type "?array" ou "array" indique si la liste est nullable ou non. la valeur
par défaut est "?array"

Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de
nature liste si:
* c'est un tableau avec un unique élément de type tableau à l'index 0, e.g
  `[["string", null, "required" => true]]`

-*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary