nur-ture/src/schema/README.md

# nulib\schema

les classes de ce package permettent de 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 ou liste. la nature du schéma (la valeur de la clé `"""`) indique le
type de donnée modélisée
* donnée scalaire

  forme courante:
  ~~~php
  const SCALAR_SCHEMA = [
    $type, [$default, $title, ...]
  ];
  ~~~
  forme normalisée:
  ~~~php
  const SCALAR_SCHEMA = [
    $type, [$default, $title, ...]
    "" => "scalar",
  ];
  ~~~
* tableau associatif
  le tableau modélisé peut avoir des clés numériques ou chaines --> seules les
  clés décrites par le schéma sont validées

  forme courante:
  ~~~php
  const ASSOC_SCHEMA = [
    KEY => VALUE_SCHEMA,
    ...
  ];
  ~~~
  forme normalisée:
  ~~~php
  const ASSOC_SCHEMA = [
    "?array", [$default, $title, ...]
    "" => "assoc",
    "schema" => [
      KEY => VALUE_SCHEMA,
      ...
    ],
  ];
  ~~~
* liste (tableau d'éléments du même type)
  le tableau modélisé peut avoir des clés numériques ou chaines --> on ne
  modélise ni le type ni la valeur des clés

  forme courante:
  ~~~php
  const LIST_SCHEMA = [[
    ITEM_SCHEMA,
  ]];
  ~~~
  forme normalisée:
  ~~~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",
  "analyzer_func" => "XXX",
  "extractor_func" => "XXX",
  "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]`

`messages` 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 `analyzer_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 la forme courante, 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"]`

La forme normalisée est
~~~php
const ASSOC_SCHEMA = [
  "?array",
  "" => "assoc",
  "schema" => [
    KEY => VALUE_SCHEMA,
    ...
  ],
];
~~~
le type "?array" ou "array" indique si la liste est nullable ou non. la valeur
par défaut est "?array"

chaque occurrence de `KEY => VALUE_SCHEMA` définit le schéma de la valeur dont
la clé est `KEY`

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 la forme courante, 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]]`

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

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