Typy PHP

Nette\Utils\Type reprezentuje typ danych PHP. Służy do analizowania, porównywania i manipulowania typami, niezależnie od tego, czy pochodzą ze stringa, czy z refleksji.

PHP ma obecnie bardzo bogaty system typów: od typów skalarnych (int, string), przez obiekty i interfejsy, po typy złożone (sumaryczny A|B, przecięciowy A&B albo dysjunkcyjne postacie normalne (A&B)|D). Do tego dochodzą typy specjalne, takie jak void, never, mixed, oraz typy względne self i static.

Praca z tymi typami natywnie, zwłaszcza przez ReflectionType, bywa uciążliwa, bo trzeba rekurencyjnie rozróżniać ReflectionNamedType, ReflectionUnionType i inne obiekty. Klasa Nette\Utils\Type to wszystko zamyka i udostępnia jednolite, intuicyjne API do pracy z dowolnym typem obsługiwanym przez PHP.

Pozwala na przykład łatwo sprawdzić, czy jeden typ akceptuje inny (zgodność), rozszerzyć typy albo przekształcić refleksję w czytelny zapis.

Instalacja:

composer require nette/utils

Wszystkie przykłady zakładają, że zdefiniowany jest następujący alias klasy:

use Nette\Utils\Type;

fromReflection ($reflection): ?Type

Ta metoda statyczna tworzy obiekt Type na podstawie refleksji. Parametrem może być obiekt ReflectionMethod albo ReflectionFunction (zwraca typ wartości zwracanej) albo obiekt ReflectionParameter czy ReflectionProperty. Rozwiązuje self, static i parent do rzeczywistej nazwy klasy. Jeśli obiekt nie ma typu, zwraca null.

class DemoClass
{
	public self $foo;
}

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

fromString (string $type): Type

Ta metoda statyczna tworzy obiekt Type z jego reprezentacji tekstowej.

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

fromValue (mixed $value): Type

Metoda statyczna tworząca obiekt Type na podstawie typu przekazanej wartości.

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

Dla zasobów zwraca mixed, bo PHP nie obsługuje typu resource. Dla klas anonimowych zwraca nazwę najbliższego przodka albo object.

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

getNames (): (string|array)[]

Zwraca tablicę stringów reprezentujących podtypy składające się na typ złożony. Dla typów przecięciowych zwraca tablicę tablic.

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

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

getTypes(): Type[]

Zwraca tablicę obiektów Type reprezentujących podtypy składające się na typ złożony:

$type = Type::fromString('string|null'); // albo '?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

Dla typów prostych (w tym prostych typów nullable, jak ?string) zwraca nazwę typu. W przeciwnym razie zwraca 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 (to typ sumaryczny)

isSimple(): bool

Zwraca, czy jest to typ prosty. Do typów prostych zaliczają się również proste typy nullable (np. ?string, ?Foo):

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

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

isUnion(): bool

Zwraca, czy jest to typ sumaryczny (zawiera |).

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

isIntersection(): bool

Zwraca, czy jest to typ przecięciowy (zawiera &).

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

isBuiltin(): bool

Zwraca, czy typ jest prosty i jednocześnie wbudowany w PHP (jak string, int, array, callable itd.).

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

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

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

isClass(): bool

Zwraca, czy typ jest prosty i jednocześnie jest nazwą klasy (a nie typem wbudowanym, jak string czy 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

Zwraca, czy typ jest jednym z wewnętrznych słów kluczowych self, parent albo static.

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

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

allows (string|Type $type): bool

Metoda allows() sprawdza zgodność typów. Może na przykład ustalić, czy wartość określonego typu dałoby się przekazać jako parametr do funkcji oczekującej tego typu.

$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

Zwraca obiekt Type akceptujący zarówno pierwotny typ, jak i ten dodawany. Tworzy tzw. typ sumaryczny.

Metoda jest sprytna i nie duplikuje typów bez potrzeby. Jeśli dodasz typ, który już występuje albo jest nadzbiorem bieżącego typu (np. dodanie mixed do string), wynik zostanie uproszczony.

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

// rozszerzenie do nullable string
echo $type->with('null'); // '?string'

// utworzenie typu sumarycznego
echo $type->with('int');  // 'string|int'

// dodanie typu, który przesłania wszystko
echo $type->with('mixed'); // 'mixed'