<?php
/**
 * ASPIC — consignes_fonctions.php
 *
 * Bibliothèque des fonctions du catalogue ASP_Fonctions (chantier des
 * consignes, 6 septembre 2026 — voir Réflexions stratégiques). Chaque
 * fonction ci-dessous porte le nom exact enregistré dans
 * ASP_Fonctions.FON_NomPHP, et est appelée dynamiquement par le moteur
 * générique (voir moteur_consignes.php) — plus aucun appel en dur dans
 * contacts.php depuis la version du 6 septembre 2026 (soir).
 *
 * Convention pour écrire une nouvelle fonction ici :
 * - Traitement : signature (string $valeur): string — reçoit la valeur
 *   actuelle du champ, retourne la valeur transformée.
 * - Test : signature (string $valeur): bool — retourne vrai si la valeur
 *   respecte la consigne, faux sinon (le message affiché à l'échec vient de
 *   CNS_MessageErreur en base, jamais de cette fonction).
 * Fichier volontairement sans aucune dépendance (pas de session, pas de
 * base de données) : chaque fonction ne fait que transformer ou tester une
 * valeur qu'on lui passe.
 */

// ASP_Fonctions.FON_Nom = 'MAJUSCULE' (Nature=Traitement)
// Met en majuscules la valeur d'un champ, en respectant les caractères
// accentués français (mb_strtoupper avec encodage explicite : un simple
// strtoupper() laisserait "é"/"è"/... inchangés selon la locale du serveur).
function consigne_majuscule(string $valeur): string
{
    return mb_strtoupper($valeur, 'UTF-8');
}

// ASP_Fonctions.FON_Nom = 'NON_VIDE' (Nature=Test)
// Vrai si la valeur n'est pas vide une fois débarrassée des espaces
// superflus en début/fin (une chaîne de simples espaces est considérée vide).
function consigne_non_vide(string $valeur): bool
{
    return trim($valeur) !== '';
}

// ASP_Fonctions.FON_Nom = 'PREMIERE_LETTRE_MAJUSCULE' (Nature=Traitement)
// "georges" -> "Georges", "JOSEPH" -> "Joseph", "jean-marc" -> "Jean-Marc".
// Tout le reste en minuscules, une majuscule après le début de la chaîne et
// après chaque tiret ou espace (pour les prénoms composés). Volontairement
// pas de ucwords() : cette fonction native de PHP n'est pas fiable en UTF-8
// (elle raisonne en octets, pas en caractères — un prénom commençant par une
// lettre accentuée type "Éric" serait corrompu).
function consigne_premiere_lettre_majuscule(string $valeur): string
{
    $valeur = mb_strtolower($valeur, 'UTF-8');
    return (string)preg_replace_callback(
        '/(^|[\s\-])(\p{L})/u',
        function (array $m): string {
            return $m[1] . mb_strtoupper($m[2], 'UTF-8');
        },
        $valeur
    );
}