Type PHP

Nette\Utils\Type représente un type de données PHP. Elle sert à analyser, comparer et manipuler les types, qu'ils proviennent d'une chaîne ou de la réflexion.

PHP possède aujourd'hui un système de types très riche : des types scalaires (int, string) aux objets et interfaces, en passant par les types complexes (union A|B, intersection A&B ou formes normales disjonctives (A&B)|D). S'y ajoutent des types particuliers comme void, never, mixed, ou les types relatifs self et static.

Travailler nativement avec ces types, en particulier via ReflectionType, est souvent laborieux, car il faut distinguer récursivement ReflectionNamedType, ReflectionUnionType et d'autres objets. La classe Nette\Utils\Type encapsule tout cela et fournit une API unifiée et intuitive pour travailler avec n'importe quel type pris en charge par PHP.

Elle vous permet par exemple de vérifier facilement si un type en accepte un autre (compatibilité), d'étendre des types ou de convertir des réflexions en une notation lisible.

Installation :

composer require nette/utils

Tous les exemples supposent qu'un alias a été créé :

use Nette\Utils\Type;

fromReflection ($reflection): ?Type

Cette méthode statique crée un objet Type à partir de la réflexion. Le paramètre peut être un objet ReflectionMethod ou ReflectionFunction (elle renvoie alors le type de la valeur de retour), ou un objet ReflectionParameter ou ReflectionProperty. Elle résout self, static et parent en nom de classe réel. Si le sujet n'a pas de type, elle renvoie null.

class DemoClass
{
	public self $foo;
}

$prop = new ReflectionProperty(DemoClass::class, 'foo');
echo Type::fromReflection($prop); // 'DemoClass'

fromString (string $type): Type

Cette méthode statique crée un objet Type à partir de sa représentation textuelle.

$type = Type::fromString('Foo|Bar');
echo $type;      // 'Foo|Bar'

fromValue (mixed $value): Type

Méthode statique qui crée un objet Type d'après le type de la valeur passée.

$type = Type::fromValue('hello'); // 'string'
$type = Type::fromValue(123);     // 'int'
$type = Type::fromValue(new stdClass); // 'stdClass'

Pour les ressources, elle retourne mixed, PHP ne connaissant pas le type resource. Pour les classes anonymes, elle retourne le nom de l'ancêtre le plus proche, ou object.

$obj = new class extends Foo { };
$type = Type::fromValue($obj);    // 'Foo'

getNames (): (string|array)[]

Renvoie un tableau de chaînes représentant les sous-types qui composent un type composé. Pour les types intersection, elle renvoie un tableau de tableaux.

$type = Type::fromString('string|null'); // ou '?string'
$type->getNames();  // ['string', 'null']

$type = Type::fromString('(Foo&Bar)|string');
$type->getNames();  // [['Foo', 'Bar'], 'string']

getTypes(): Type[]

Renvoie un tableau d'objets Type représentant les sous-types qui composent un type composé :

$type = Type::fromString('string|null'); // ou '?string'
$type->getTypes();  // [Type::fromString('string'), Type::fromString('null')]

$type = Type::fromString('(Foo&Bar)|string');
$type->getTypes();  // [Type::fromString('Foo&Bar'), Type::fromString('string')]

$type = Type::fromString('Foo&Bar');
$type->getTypes();  // [Type::fromString('Foo'), Type::fromString('Bar')]

getSingleName(): ?string

Pour les types simples (y compris les types nullable simples comme ?string), elle renvoie le nom du type. Sinon, elle renvoie null.

$type = Type::fromString('string|null');
echo $type;                       // '?string'
echo $type->getSingleName();      // 'string'

$type = Type::fromString('?Foo');
echo $type;                       // '?Foo'
echo $type->getSingleName();      // 'Foo'

$type = Type::fromString('Foo|Bar');
echo $type;                       // 'Foo|Bar'
echo $type->getSingleName();      // null

isSimple(): bool

Indique s'il s'agit d'un type simple. Les types nullable simples (par ex. ?string, ?Foo) comptent aussi comme des types simples :

$type = Type::fromString('string');
$type->isSimple();       // true
$type->isUnion();        // false

$type = Type::fromString('?Foo'); // ou 'Foo|null'
$type->isSimple();       // true
$type->isUnion();        // true

isUnion(): bool

Indique s'il s'agit d'un type union (il contient |).

$type = Type::fromString('string|int');
$type->isUnion();        // true

isIntersection(): bool

Indique s'il s'agit d'un type intersection (il contient &).

$type = Type::fromString('Foo&Bar');
$type->isIntersection(); // true

isBuiltin(): bool

Indique si le type est simple et en même temps un type natif de PHP (comme string, int, array, callable, etc.).

$type = Type::fromString('string');
$type->isBuiltin(); // true

$type = Type::fromString('string|int');
$type->isBuiltin(); // false

$type = Type::fromString('Foo');
$type->isBuiltin(); // false

isClass(): bool

Indique si le type est simple et en même temps un nom de classe (et non un type natif comme string ou int).

$type = Type::fromString('string');
$type->isClass();   // false

$type = Type::fromString('Foo|null');
$type->isClass();   // true

$type = Type::fromString('Foo|Bar');
$type->isClass();   // false

isClassKeyword(): bool

Retourne si le type est l'un des types internes self, parent, static.

$type = Type::fromString('self');
$type->isClassKeyword();   // true

$type = Type::fromString('Foo');
$type->isClassKeyword();   // false

allows (string|Type $type): bool

La méthode allows() vérifie la compatibilité des types. Elle permet par exemple de déterminer si une valeur d'un certain type pourrait être passée comme paramètre à une fonction attendant ce type.

$type = Type::fromString('string|null');
$type->allows('string'); // true
$type->allows('null');   // true
$type->allows('Foo');    // false

$type = Type::fromString('mixed');
$type->allows('null');   // true

with (string|Type $type): Type

Retourne un objet Type qui accepte à la fois le type d'origine et celui qu'on lui ajoute. Elle crée un type union.

La méthode est astucieuse et ne duplique pas inutilement les types. Si vous ajoutez un type déjà présent, ou un type qui englobe le type courant (par exemple mixed ajouté à string), le résultat est simplifié.

$type = Type::fromString('string');

// Extension à un string nullable
echo $type->with('null'); // '?string'

// Création d'un type union
echo $type->with('int');  // 'string|int'

// Ajout d'un type qui englobe tout
echo $type->with('mixed'); // 'mixed'