Project Overview: Type Guard
Type Guard is a promising component of the Pinkary Project. Its purpose is to refine the type of a variable into a more specific type, ensuring that it can be used safely within PHP environments. The tool harnesses the capabilities of static analyzers like PHPStan and Psalm to enhance type safety, which is crucial for systematic code analysis and bug prevention.
Key Features
Safe Type Refinement: Type Guard allows developers to specify the exact type of a variable that might originally have a mixed type. By using the function type, programmers can streamline variable types, enhancing safety and precision in code. For instance:
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();
In this example, an initial mixed type is clarified to a string, aiding static analyzers in better understanding and checking the code.
Null Handling: Another practical feature is the capability to manage potentially null variables without losing any type information. This makes handling nullable paths in code much less prone to error:
/** @var array<int, User>|null $users */
$users = getUsers();
// Narrows down the type to `array<int, User>`
$users = type($users)->not()->null();
Handling Collections: Type Guard can determine and refine complex types like collections. This is particularly useful in advanced PHP applications dealing with datasets or collections:
/** @var Collection<int, User>|null $users */
$users = getUsers();
// Narrows down the type to `Collection<int, User>`
$users = type($users)->as(Collection::class);
Installation
For developers interested in integrating Type Guard into their PHP projects, the installation process relies on Composer, a standard tool in the PHP ecosystem. It is crucial to note that PHP 8.2 or later is required:
composer require pinkary-project/type-guard
Usage and Functions
Type Guard offers a range of functions designed to refine and assert variable types. These include:
- as: Converts a variable to a specific class type.
- asInt(): Ensures that a variable is an integer.
- asFloat(): Asserts that a variable is a float.
- asString(): Ensures the variable is a string.
- asBool(): Converts a variable to a boolean type.
- asNull(): Specifies the variable as null.
- asCallable(): Confirms the variable can be executed as a function.
- not()->null(): Ensures the variable is not null.
- asArray(): Converts a variable to an array.
- asIterable(): Ensures the variable is iterable.
Each function enhances type predictability, allowing developers to write robust and efficient code.
Background and Licensing
The Type Guard library is a creation of Nuno Maduro, renowned for contributing to open-source projects under the MIT license. The project aims to provide developers with innovative tools to bolster their coding standards and reliability.
Note: Since Type Guard is a work in progress, it is advisable to use it cautiously and avoid deploying it in production environments until it becomes more stable.