pinkary-project/type-guard

Type Guard module is part of the Pinkary Project, and allows you to **narrow down the type** of a variable to a more specific type.

v0.1.0 2024-04-28 10:20 UTC

Requires

• php: ^8.2.0

Requires (Dev)

• laravel/pint: ^1.15.2
• pestphp/pest: ^3.0.0
• pestphp/pest-plugin-type-coverage: 3.x-dev
• phpstan/phpstan: ^1.10.67
• rector/rector: ^1.0.4
• symfony/var-dumper: ^6.4.0|^7.0.6

MIT

• Nuno Maduro

• php
• type
• assert
• narrow
• type-guard
• pinkary-project

README

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

Type Guard module is part of the Pinkary Project, 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 losing 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);

Installation

Requires PHP 8.2+

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

composer require pinkary-project/type-guard

Usage

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

as

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

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

asInt()

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

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

asFloat()

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

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

asString()

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

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

asBool()

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

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

asNull()

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

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

asCallable()

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

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

not()->null()

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

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

asArray()

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

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

asIterable()

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

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

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