magdicom / type-guard Goto Github PK

This library is a work in progress. Please, do not use it in production.

Type Guard module is part of the Another Library, and allows you to narrow down the type of a variable to a more specific type. Using the type function, you can perform specific checks to determine the type of an object and then use that object in a way that is type-safe according to the PHPStan and Psalm static analyzers.

Here is an example, where we use the type function to narrow down the type of a variable that previously had a mixed type:

function config(): mixed;

// At compile time, the type of $apiKey is `mixed`:
$apiKey = config('api_key');

// We instruct the static analyzer that $apiKey is a `string`:
$apiKey = type($apiKey)->asString();

Here is another example, where we use the type function to narrow down the type of a variable that previously could be null. In the process, zero type information is lost:

/** @var array<int, User>|null $users */
$users = getUsers();

// Narrows down the type to `array<int, User>`
$users = type($users)->not()->null();

And one more example, where we narrow down the type of a variable to a Collection without loosing the type information:

/** @var Collection<int, User>|null $users */
$users = getUsers();

// Narrows down the type to `Collection<int, User>`
$users = type($users)->as(Collection::class);

Requires PHP 8.2+

You may use Composer to install Type Guard into your PHP project:

composer require std-library/type-guard

• as
• asInt()
• asFloat()
• asString()
• asBool()
• asNull()
• asCallable()
• not()->null()
• asArray()

Asserts and narrows down the type of the given variable to a more specific type.

$variable = type($variable)->as(User::class);

Asserts and narrows down the type of the given variable to an integer.

$variable = type($variable)->asInt();

Asserts and narrows down the type of the given variable to a float.

$variable = type($variable)->asFloat();

Asserts and narrows down the type of the given variable to a string.

$variable = type($variable)->asString();

Asserts and narrows down the type of the given variable to a boolean.

$variable = type($variable)->asBool();

Asserts and narrows down the type of the given variable to a null.

$variable = type($variable)->asNull();

Asserts and narrows down the type of the given variable to a callable.

$variable = type($variable)->asCallable();

Asserts and narrows down the type of the given variable to a non-null value.

$variable = type($variable)->not()->null();

Asserts and narrows down the type of the given variable to an array.

$variable = type($variable)->asArray();

Type Guard is part of the Another Library project. It was created by Nuno Maduro and open-sourced under the MIT license.