Typer les valeurs échangées par l’application

Une valeur incohérente peut traverser plusieurs fichiers avant de provoquer une erreur : un identifiant reçu comme texte, ou un courriel absent traité comme une chaîne obligatoire. En précisant les types échangés, vous rendez les attentes visibles et permettez à PHP de détecter plus tôt certaines erreurs. Vous allez appliquer cette discipline aux données du carnet sans encore créer sa classe métier.

Le périmètre et les contraintes des contacts ont été fixés dans la première leçon : le nom est obligatoire, tandis que le courriel et le téléphone sont facultatifs. Dans le projet, les mêmes données doivent pouvoir être transmises entre une fonction, le modèle et les gabarits sans changer de sens. Les types rendent ce contrat plus explicite.

Typer les paramètres et les retours

PHP 8 permet de déclarer un type pour les paramètres d’une fonction et pour sa valeur de retour. Les types scalaires courants sont int, float, string et bool. Utilisez aussi void lorsqu’une fonction ne renvoie aucune valeur ; ne confondez pas ce cas avec une valeur vide, comme ''.

<?php

declare(strict_types=1);

function normaliserNom(string $nom): string
{
    return trim($nom);
}

function nomEstPresent(string $nom): bool
{
    return normaliserNom($nom) !== '';
}

function afficherNombreContacts(int $nombre): void
{
    echo "Nombre de contacts : {$nombre}";
}

$nom = normaliserNom('  Samira Benali  ');
$present = nomEstPresent($nom);

if ($present) {
    afficherNombreContacts(1);
}

Nombre de contacts : 1

Ici, normaliserNom() reçoit une chaîne et en renvoie une autre. nomEstPresent() renvoie un booléen, tandis que afficherNombreContacts() ne renvoie rien et reçoit un entier. Avec declare(strict_types=1), déjà utilisé dans vos fichiers, PHP ne convertit pas silencieusement les arguments scalaires lorsqu’un appel fournit un type incompatible : l’erreur apparaît au point d’appel.

Distinguer valeur obligatoire et valeur nullable

Le nom est toujours présent dans une fiche valide ; le courriel et le téléphone peuvent être absents. Le type nullable s’écrit en préfixant un type par ? : ?string accepte soit une chaîne, soit null. Il ne signifie pas qu’une chaîne vide est automatiquement transformée en null : ces deux valeurs restent distinctes.

Avant la création de la classe Contact, vous pouvez déjà représenter une fiche par un tableau associatif. L’annotation PHPDoc @phpstan-type décrit ici la forme attendue pour les outils d’analyse statique ; ce n’est pas une déclaration de type native comprise par PHP à l’exécution. Les types natifs restent donc ceux des paramètres et du retour de la fonction.

<?php

declare(strict_types=1);

/**
 * @phpstan-type ContactDonnees array{
 *     id: int,
 *     nom: string,
 *     courriel: string|null,
 *     telephone: string|null
 * }
 */

/**
 * @param array<string, int|string|null> $donnees
 * @return array{ id: int, nom: string, courriel: ?string, telephone: ?string }
 */
function creerDonneesContact(array $donnees): array
{
    return [
        'id' => (int) ($donnees['id'] ?? 0),
        'nom' => (string) ($donnees['nom'] ?? ''),
        'courriel' => isset($donnees['courriel'])
            ? (string) $donnees['courriel']
            : null,
        'telephone' => isset($donnees['telephone'])
            ? (string) $donnees['telephone']
            : null,
    ];
}

$contact = creerDonneesContact([
    'id' => 7,
    'nom' => 'Samira Benali',
    'courriel' => '[email protected]',
]);

var_export($contact);

array (
  'id' => 7,
  'nom' => 'Samira Benali',
  'courriel' => '[email protected]',
  'telephone' => NULL,
)

La fonction renvoie toujours les quatre clés attendues ; les champs facultatifs prennent la valeur null lorsqu’ils ne sont pas fournis. Dans cet exemple pédagogique, les conversions rendent la sortie prévisible, mais elles ne remplacent pas une validation : convertir un texte arbitraire en entier peut masquer une entrée incorrecte. Les contrôles adaptés seront réalisés lorsque le traitement des formulaires et les règles du modèle seront abordés.

Préparer les propriétés typées

Quand les données seront portées par la classe Contact, leurs propriétés pourront recevoir des types natifs. Une propriété obligatoire peut être déclarée public string $nom; et une propriété facultative public ?string $courriel;. Ces déclarations indiquent les valeurs admises, mais ne précisent pas encore comment initialiser ni protéger les données ; la prochaine leçon introduira la classe et son constructeur.

À retenir

• Déclarez les types des paramètres et des retours pour expliciter les échanges entre fonctions.
• Utilisez `?string` quand une donnée peut être une chaîne ou `null` ; une chaîne vide reste une autre valeur.
• Documentez la forme des tableaux associatifs, sans confondre une annotation PHPDoc avec un type natif à l’exécution.
• Les propriétés typées préciseront les données de Contact ; leur initialisation et leur protection seront étudiées dans la prochaine leçon.

Vous allez maintenant créer la classe Contact et donner une structure durable aux données que vous avez typées ici.