smpita/typeas

Guaranteed type control for PHP

v4.0.1 2025-12-02 16:48 UTC

Requires

• php: ^8.1

Requires (Dev)

• fakerphp/faker: 1.24
• laravel/pint: ^1.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.3|^11.0|^10.5.32

MIT

• Sean Pearce

• laravel
• smpita
• typeas

README

Guaranteed type control for PHP

Easily type your mixed signatures. Perfect for static analysis!

Table of Contents

• Quick Start
  • Installation
  • Resolving Types
  • Caveats
  • Custom Resolvers
  • Helpers
• Deprecations
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Quick Start

Installation

Install the package via composer:

composer require smpita/typeas

See SIGNATURES for the full list of methods and signatures.

Resolving types

SIGNATURES#resolving

Pass a mixed variable to get a typed variable.

use Smpita\TypeAs\TypeAs;

// Throws \Smpita\TypeAs\TypeAsResolutionException if $mixed can't resolve to the type.
$array = TypeAs::array($mixed);
$bool = TypeAs::bool($mixed);
$class = TypeAs::class(Expected::class, $mixed);
$float = TypeAs::float($mixed);
$int = TypeAs::int($mixed);
$string = TypeAs::string($mixed);

// Returns null if $mixed can't resolve to the type.
$nullableArray = TypeAs::nullableArray($mixed);
$nullableBool = TypeAs::nullableBool($mixed);
$nullableClass = TypeAs::nullableClass(Expected::class, $mixed);
$nullableFloat = TypeAs::nullableFloat($mixed);
$nullableInt = TypeAs::nullableInt($mixed);
$nullableString = TypeAs::nullableString($mixed);

To suppress throwing exceptions, provide a default.

use Smpita\TypeAs\TypeAs;

// Returns the default if passed null, or if $mixed can't resolve to the type.
$array = TypeAs::array($mixed, []);
$bool = TypeAs::bool($mixed, false);
$class = TypeAs::class(Expected::class, $mixed, new StdClass());
$float = TypeAs::float($mixed, 0.0);
$int = TypeAs::int($mixed, 0);
$string = TypeAs::string($mixed, '');

// Nullable types can specify defaults.
$nullableArray = TypeAs::nullableArray($mixed, []);
$nullableBool = TypeAs::nullableBool($mixed, false);
$nullableClass = TypeAs::nullableClass(Expected::class, $mixed, new StdClass());
$nullableFloat = TypeAs::nullableFloat($mixed, 0.0);
$nullableInt = TypeAs::nullableInt($mixed, 0);
$nullableString = TypeAs::nullableString($mixed, '');

Caveats

SIGNATURES#array

By default, array() will wrap non-iterables similar to (array) $mixed instead of throwing exceptions.

use Smpita\TypeAs\TypeAs;

TypeAs::array('example'); // returns ['example']
TypeAs::array(['example']); // returns ['example']

// Disable wrapping to get exceptions.
TypeAs::array('', wrap: false); // throws \Smpita\TypeAs\TypeAsResolutionException
TypeAs::array('', null, null, false); // throws \Smpita\TypeAs\TypeAsResolutionException

Custom Resolvers

SIGNATURES#resolver-registration

Starting in v2.4.0 you can specify your own custom resolvers.

Each type has an associated interface located in Smpita\TypeAs\Contracts which you can implement to make your own resolvers.

Simply implement the interface, then either register the resolver or use it in the resolver method.

Interfaces

• Smpita\TypeAs\Contracts\ArrayResolver
• Smpita\TypeAs\Contracts\BoolResolver
• Smpita\TypeAs\Contracts\ClassResolver
• Smpita\TypeAs\Contracts\FloatResolver
• Smpita\TypeAs\Contracts\IntResolver
• Smpita\TypeAs\Contracts\StringResolver
• Smpita\TypeAs\Contracts\NullableArrayResolver
• Smpita\TypeAs\Contracts\NullableClassResolver
• Smpita\TypeAs\Contracts\NullableFloatResolver
• Smpita\TypeAs\Contracts\NullableIntResolver
• Smpita\TypeAs\Contracts\NullableStringResolver

Creating Custom Resolvers

use Smpita\TypeAs\Contracts\StringResolver;

class CustomStringResolver implements StringResolver
{
    /**
     * @throws \Smpita\TypeAs\Exceptions\TypeAsResolutionException
     */
    public function resolve(mixed $value, string $default = null): string
    {
        // Your logic here
    }
}

Registering Custom Resolvers

Globally

To globally register a resolver, use the associated setter method. In Laravel, it's recommended to do this in the boot method of a ServiceProvider.

use Smpita\TypeAs\TypeAs;

TypeAs::setArrayResolver(new CustomArrayResolver());
TypeAs::setBoolResolver(new CustomBoolResolver());
TypeAs::setClassResolver(new CustomClassResolver());
TypeAs::setFloatResolver(new CustomFloatResolver());
TypeAs::setIntResolver(new CustomIntResolver());
TypeAs::setStringResolver(new CustomStringResolver());
TypeAs::setNullableArrayResolver(new CustomNullableArrayResolver());
TypeAs::setNullableBoolResolver(new CustomNullableBoolResolver());
TypeAs::setNullableClassResolver(new CustomNullableClassResolver());
TypeAs::setNullableFloatResolver(new CustomNullableFloatResolver());
TypeAs::setNullableIntResolver(new CustomIntNullableResolver());
TypeAs::setNullableStringResolver(new CustomNullableStringResolver());

Unregistering Custom Resolvers

To return to default, set the resolver to null.

use Smpita\TypeAs\TypeAs;

TypeAs::setArrayResolver(null);
TypeAs::setBoolResolver(null);
TypeAs::setClassResolver(null);
TypeAs::setFloatResolver(null);
TypeAs::setIntResolver(null);
TypeAs::setStringResolver(null);
TypeAs::setNullableArrayResolver(null);
TypeAs::setNullableBoolResolver(null);
TypeAs::setNullableClassResolver(null);
TypeAs::setNullableFloatResolver(null);
TypeAs::setNullableIntResolver(null);
TypeAs::setNullableStringResolver(null);

// Return all resolvers to default
TypeAs::useDefaultResolvers();

Single use

Inject a resolver to use it on a per call basis.

use Smpita\TypeAs\TypeAs;

$array = TypeAs::array($mixed, resolver: new CustomArrayResolver());
$bool = TypeAs::bool($mixed, resolver: new CustomBoolResolver());
$class = TypeAs::class(Expected::class, $mixed, resolver: new CustomClassResolver());
$float = TypeAs::float($mixed, resolver: new CustomFloatResolver());
$int = TypeAs::int($mixed, resolver: new CustomIntResolver());
$string = TypeAs::string($mixed, resolver: new CustomStringResolver());
$nullableArray = TypeAs::nullableArray($mixed, resolver: new CustomNullableArrayResolver());
$nullableBool = TypeAs::nullableBool($mixed, resolver: new CustomNullableBoolResolver());
$nullableClass = TypeAs::nullableClass(Expected::class, $mixed, resolver: new CustomNullableClassResolver());
$nullableFloat = TypeAs::nullableFloat($mixed, resolver: new CustomNullableFloatResolver());
$nullableInt = TypeAs::nullableInt($mixed, resolver: new CustomNullableIntResolver());
$nullableString = TypeAs::nullableString($mixed, resolver: new CustomNullableStringResolver());

// or

$array = TypeAs::array($mixed, null, new CustomArrayResolver());
$bool = TypeAs::bool($mixed, null, new CustomBoolResolver());
$class = TypeAs::class(Expected::class, $mixed, null, new CustomClassResolver());
$float = TypeAs::float($mixed, null, new CustomFloatResolver());
$int = TypeAs::int($mixed, null, new CustomIntResolver());
$string = TypeAs::string($mixed, null, new CustomStringResolver());
$nullableArray = TypeAs::nullableArray($mixed, null, new CustomNullableArrayResolver());
$nullableBool = TypeAs::nullableBool($mixed, null, new CustomNullableBoolResolver());
$nullableClass = TypeAs::nullableClass(Expected::class, $mixed, null, new CustomNullableClassResolver());
$nullableFloat = TypeAs::nullableFloat($mixed, null, new CustomNullableFloatResolver());
$nullableInt = TypeAs::nullableInt($mixed, null, new CustomNullableIntResolver());
$nullableStTypeAs::nullableString($mixed, null, new CustomNullableStringResolver());

If you registered a custom resolver then want to use a default resolver on a per call basis, you must pass a default resolver.

use Smpita\TypeAs\TypeAs;

$array = TypeAs::array($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsArray());
$bool = TypeAs::bool($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsBool());
$class = TypeAs::class(Expected::class, $mixed, resolver: \Smpita\TypeAs\Resolvers\AsClass());
$float = TypeAs::float($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsFloat());
$int = TypeAs::int($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsInt());
$string = TypeAs::string($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsString());
$nullableArray = TypeAs::nullableArray($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsNullableArray());
$nullableBool = TypeAs::nullableBool($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsNullableBool());
$nullableClass = TypeAs::nullableClass(Expected::class, $mixed, resolver: new \Smpita\TypeAs\Resolvers\AsNullableClass());
$nullableFloat = TypeAs::nullableFloat($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsNullableFloat());
$nullableInt = TypeAs::nullableInt($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsNullableInt());
$nullableString = TypeAs::nullableString($mixed, resolver: new \Smpita\TypeAs\Resolvers\AsNullableString());

// or

$array = TypeAs::array($mixed, null, new \Smpita\TypeAs\Resolvers\AsArray());
$bool = TypeAs::bool($mixed, null, new \Smpita\TypeAs\Resolvers\AsBool());
$class = TypeAs::class(Expected::class, $mixed, null, \Smpita\TypeAs\Resolvers\AsClass());
$float = TypeAs::float($mixed, null, new \Smpita\TypeAs\Resolvers\AsFloat());
$int = TypeAs::int($mixed, null, new \Smpita\TypeAs\Resolvers\AsInt());
$string = TypeAs::string($mixed, null, new \Smpita\TypeAs\Resolvers\AsString());
$nullableArray = TypeAs::nullableArray($mixed, null, new \Smpita\TypeAs\Resolvers\AsNullableArray());
$nullableBool = TypeAs::nullableBool($mixed, null, new \Smpita\TypeAs\Resolvers\AsNullableBool());
$nullableClass = TypeAs::nullableClass(Expected::class, $mixed, null, new \Smpita\TypeAs\Resolvers\AsNullableClass());
$nullableFloat = TypeAs::nullableFloat($mixed, null, new \Smpita\TypeAs\Resolvers\AsNullableFloat());
$nullableInt = TypeAs::nullableInt($mixed, null, new \Smpita\TypeAs\Resolvers\AsNullableInt());
$nullableString = TypeAs::nullableString($mixed, null, new \Smpita\TypeAs\Resolvers\AsNullableString());

Helpers

SIGNATURES#helpers

use function Smpita\TypeAs\asArray;
use function Smpita\TypeAs\asBool;
use function Smpita\TypeAs\asClass;
use function Smpita\TypeAs\asFloat;
use function Smpita\TypeAs\asInt;
use function Smpita\TypeAs\asString;
use function Smpita\TypeAs\asNullableArray;
use function Smpita\TypeAs\asNullableBool;
use function Smpita\TypeAs\asNullableClass;
use function Smpita\TypeAs\asNullableFloat;
use function Smpita\TypeAs\asNullableInt;
use function Smpita\TypeAs\asNullableString;

$array = asArray($mixed);
$bool = asBool($mixed);
$class = asClass(Target::class, $mixed);
$float = asFloat($mixed);
$int = asInt($mixed);
$string = asString($mixed);
$nullableArray = asNullableArray($mixed);
$nullableBool = asNullableBool($mixed);
$nullableClass = asNullableClass(Target::class, $mixed);
$nullableFloat = asNullableFloat($mixed);
$nullableInt = asNullableInt($mixed);
$nullableString = asNullableString($mixed);

Deprecations

Please see SIGNATURES#deprecations if you encounter a breaking change.

Testing

composer test

Changelog

Please see RELEASES for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Sean Pearce
• All Contributors

License

The MIT License (MIT). Please see License File for more information.