diff --git a/src/schema/README.md b/src/schema/README.md index b908a2b..9e4251f 100644 --- a/src/schema/README.md +++ b/src/schema/README.md @@ -2,14 +2,12 @@ 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. mais en définitive, -les données qui sont traitées par du code PHP sont du bon type et au bon -format, ou une erreur est levée. +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 -* liste (tableau séquentiel) * 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. @@ -28,41 +26,57 @@ 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 = [ - "" => ["scalar"], - ... + $type, [$default, $title, ...] + "" => "scalar", ]; ~~~ -* nature liste: modélise une liste de valeurs du même type + Si le type est "array" ou "?array", on peut préciser le schéma de la donnée ~~~php - const LIST_SCHEMA = [ - "" => ["list", - "title" => "libellé de la valeur", - "required" => false, - "nullable" => true, - "desc" => "description de la valeur", - "name" => "identifiant de la valeur", - ], - ITEM_SCHEMA, + const SCALAR_SCHEMA = [ + "?array", [$default, $title, ...] + "" => "scalar", + "schema" => NAKED_SCHEMA, ]; ~~~ -* nature tableau associatif: modélise un tableau associatif +* 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 = [ - "" => ["assoc", - "title" => "libellé de la valeur", - "required" => false, - "nullable" => true, - "desc" => "description de la valeur", - "name" => "identifiant de la valeur", - ], KEY => VALUE_SCHEMA, ... + "" => "assoc", + ]; + ~~~ + la nature "tableau associatif" est du sucre syntaxique pour une valeur + scalaire de type "?array" dont on précise le schéma + ~~~php + // la valeur ci-dessus est strictement équivalent à + const ASSOC_SCHEMA = [ + "?array", + "" => "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 -Une valeur scalaire est modélisée de cette manière: +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", @@ -76,13 +90,14 @@ const SCALAR_SCHEMA = [ "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"], - "name" => "identifiant de la valeur", + "" => "scalar", + "schema" => "schéma de la valeur si le type est array ou ?array, null sinon", ]; ~~~ -L'ordre des clés du schéma indique la clé associé à une valeur si elle fournie -dans un tableau séquentiel. Par exemple, les deux schéma suivants sont équivalents: +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", @@ -91,7 +106,7 @@ const SCALAR_SCHEMA2 = [ "type" => "string", "default" => null, "title" => "une valeur chaine", - "" => ["scalar"], + "" => "scalar", ]; ~~~ @@ -116,71 +131,67 @@ const MESSAGE_SCHEMA = [ ]; ~~~ -## Schéma d'une liste (tableau séquentiel) - -Une liste est modélisée de cette manière: -~~~php -const LIST_SCHEMA = [ - ITEM_SCHEMA, - "" => ["list"], -]; -~~~ -où ITEM_SCHEMA est le schéma des éléments de la liste - -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]]` - ## Schéma d'un tableau associatif -Un tableau associatif est modélisée de cette manière: +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"], + "" => "assoc", ]; ~~~ -où l'ensemble des occurrences de `KEY => VALUE_SCHEMA` définit le schéma de la -valeur dont la clé est `KEY` +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 un schéma de nature scalaire, liste ou associative. - -S'il s'agit d'une valeur scalaire, il y a quelques clés de définitions -supplémentaires: -~~~php -const VALUE_SCHEMA = [ - ... - "pkey" => "chemin de clé de la valeur dans le tableau associatif", - "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?", -]; -~~~ - -Pour une liste, il y a quelques clés de définitions supplémentaires: -~~~php -const VALUE_SCHEMA = [ - "" => ["list", +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", - ], -]; -~~~ - -Pour une tableau associatif, il y a quelques clés de définitions supplémentaires: -~~~php -const VALUE_SCHEMA = [ - "" => ["assoc", + ]; + ~~~ +* s'il s'agit d'une valeur scalaire simple autre que array + ~~~php + VALUE_SCHEMA = [ ... - "pkey" => "chemin de clé de la valeur dans le tableau associatif", - ], + "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", + "" => "list", + "schema" => ITEM_SCHEMA, ]; ~~~ +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 \ No newline at end of file