ashallendesign / type-safe
A package for ensuring variable types in PHP
Fund package maintenance!
ash-jc-allen
Requires
- php: ^8.0
Requires (Dev)
- mockery/mockery: ^1.0
- phpunit/phpunit: ^9.0
- symfony/var-dumper: ^5.3
This package is auto-updated.
Last update: 2024-03-19 11:16:34 UTC
README
Table of Contents
Overview
Type Safe is a lightweight package that you can use in your PHP projects to ensure your variables' types.
If you're interested in reading about why I made this package, check out this blog post.
Installation
You can install the package via Composer:
composer require ashallendesign/type-safe
The package has been developed and tested to work with the following minimum requirements:
- PHP 8.0
Usage
Simple Checks
Validating that a property is an integer:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::INT);
Validating that a property is a string:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::STRING);
Validating that a property is a boolean:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::BOOLEAN);
Validating that a property is a closure:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::CLOSURE);
Validating that a property is an object:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::OBJECT);
Validating that a property is an array:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::ARRAY);
Validating that a property is an associative array:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::ASSOC_ARRAY);
Advanced Checks
Validating that a property is an object of a specific class:
use App\Models\User; use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::object(User::class));
Validating that a property is an array containing specific fields:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::arrayOf(Type::INT));
Validating that a property is an associative array containing specific fields:
use AshAllenDesign\TypeSafe\Type; $validatedField = safe($field, Type::assocArrayOf(Type::STRING, Type::STRING));
Custom Checks
You might want to use your own custom checks that aren't provided in the package by default. To do this, you can create your own class that implements the AshAllenDesign\TypeSafe\Check
interface.
The interface enforces two methods: passes()
and message()
. The passes()
method is used to define your logic that determines if the field is the correct type. The message()
method is used to return the message that will be passed to the thrown exception if the validation fails.
For example, if we wanted to create a custom check to assert that our field was a Laravel Collection
that only contained User
models, it might look something like this:
use App\Models\User; use AshAllenDesign\TypeSafe\Check; use Illuminate\Support\Collection; class LaravelUserCollection implements Check { public function passes(mixed $prop): bool { if (!$prop instanceof Collection) { return false; } return $prop->whereInstanceOf(User::class)->count() === $prop->count(); } public function message(mixed $prop): string { return 'One of the items is not a User model.'; } }
We could then use that check like so:
$collection = collect([new User(), new TestCase()]); safe($collection, new LaravelUserCollection());
Skipping Checks
There may be times when you don't want to run the type checks. For example, you might want to disable them in production environments and only run them in local, testing and staging environments. To skip the checks, you can simply use the skipChecks
like shown in the example below:
use AshAllenDesign\TypeSafe\Type; use AshAllenDesign\TypeSafe\TypeSafe; TypeSafe::skipChecks(); $validatedField = safe($field, Type::ASSOC_ARRAY);
Helpers Methods
There are three different ways that you can use the package to add type safe checks to your code.
The first method is by using the TypeSafe
object itself like so:
use AshAllenDesign\TypeSafe\TypeSafe; $validatedField = (new TypeSafe())->safe($field, Type::INT);
Alternatively, you can use the safe()
helper function that achieves the same thing as the code above. You can use the helper function like so:
$validatedField = safe($field, Type::INT);
The TypeSafe
also includes helper methods that you can use for all the simple checks. The example shows how you can validate an integer field:
use AshAllenDesign\TypeSafe\TypeSafe; $validatedField = TypeSafe::int($field);
Testing
To run the tests for the package, you can use the following command:
composer test
Security
If you find any security related issues, please contact me directly at mail@ashallendesign.co.uk to report it.
Contribution
If you wish to make any changes or improvements to the package, feel free to make a pull request.
To contribute to this library, please use the following guidelines before submitting your pull request:
- Write tests for any new functions that are added. If you are updating existing code, make sure that the existing tests pass and write more if needed.
- Follow PSR-12 coding standards.
- Make all pull requests to the
master
branch.
Credits
Changelog
Check the CHANGELOG to get more information about the latest changes.
License
The MIT License (MIT). Please see License File for more information.