README

Do you fight mixed signatures when performing static analysis?

Smpita/TypeAs will give you easy control of your typing.

Installation

You can install the package via composer:

composer require smpita/typeas

Usage

Please see SIGNATURES for the list of current methods and signatures.

General Usage

SIGNATURES#resolving

Pass a $mixed and it will throw a TypeAsResolutionException if the $mixed can't be cast.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::string($mixed);

If you want to suppress throwing exceptions, provide a default.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::string($mixed, '');

The Class Method

SIGNATURES#class

class() has a slightly different signature because you need to specify the class you are expecting.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::class(Target::class, $mixed);

You can still provide a default.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::class(Target::class, $mixed, new \StdClass);

Note: In versions prior to v2.0.0 the signature had a different order.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::class($mixed, Target::class, $default);

The Array Method

SIGNATURES#array

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

use Smpita\TypeAs\TypeAs;

TypeAs::array('example') === ['example'];

That might not always be appropriate, so you can turn wrapping off to get exceptions.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::array($mixed, false);

Or you may supply a default.

use Smpita\TypeAs\TypeAs;

$typed = TypeAs::array($mixed, []);

Nullables

Starting in v2.3.0 if you would prefer to receive null instead of having an exception thrown, each type method has a nullable counterpart.

use Smpita\TypeAs\TypeAs;

TypeAs::nullableString(new \stdClass) === null

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\NullableArrayResolver
Smpita\TypeAs\Contracts\NullableClassResolver
Smpita\TypeAs\Contracts\NullableFloatResolver
Smpita\TypeAs\Contracts\NullableIntResolver
Smpita\TypeAs\Contracts\NullableStringResolver
Smpita\TypeAs\Contracts\StringResolver

Creating Custom Resolvers

use Smpita\TypeAs\Contracts\StringResolver;

class CustomStringResolver implements StringResolver
{
    /**
     * @throws \UnexpectedValueException
     */
    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.

TypeAs::setStringResolver(new CustomStringResolver);

Single use

$typed = Smpita\TypeAs::string($mixed, null, new CustomStringResolver);

Unregistering Custom Resolvers

To return to default, simply set the resolver to null.

TypeAs::setStringResolver(null);

To return all resolvers to default, you can leverage the useDefaultResolvers().

TypeAs::useDefaultResolvers();

If you registered a custom resolver and want to use the default resolver on a single use basis, passing null to the resolver method will not work. You must pass the default resolver.

$typed = Smpita\TypeAs::string($mixed, null, new \Smpita\TypeAs\Resolvers\AsString);

Helpers

SIGNATURES#helpers

Starting in v2.5.0 resolver methods have an associated helper method located in the Smpita\TypeAs namespace. The helper method names follow the TypeAs method names, but are prepended by as and are camelCased.

use function Smpita\TypeAs\asString;

$typed = asString($mixed);

Deprecations

SIGNATURES#deprecations

Testing

composer test

Changelog

Please see CHANGELOG 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

License

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

smpita / typeas

Maintainers

Details