README

Guaranteed type control for PHP

Easily type your mixed signatures. Perfect for static analysis!

Table of Contents

• Quick Start
  • Installation
  • Resolving Types
  • Fluent Syntax
  • Array Wrapping
  • Official Extensions
  • Custom Resolvers
  • Helpers
• Upgrade Guide
• 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);

Defaults

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, '');

// As a named parameter
$array = TypeAs::array(value: $mixed, default: []);

Array Wrapping

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 array wrapping to get exceptions.
 * These throw \Smpita\TypeAs\TypeAsResolutionException
 */
TypeAs::array('example', wrap: false);
TypeAs::array('example', null, null, false);

Fluent Syntax

As a convenience, TypeAs supports fluent syntax. The NonNullable and Nullable fluent classes wrap the base TypeAs methods. In performance critical environments, the standard methods are recommended.

Basic Usage

use Smpita\TypeAs\TypeAs;

$array = TypeAs::type($mixed)->asArray();
$bool = TypeAs::type($mixed)->asBool();
$filterBool = TypeAs::type($mixed)->asFilterBool()
$class = TypeAs::type($mixed)->asClass(Expected::class);
$float = TypeAs::type($mixed)->asFloat();
$int = TypeAs::type($mixed)->asInt();
$string = TypeAs::type($mixed)->asString();

Nullable

Chain nullable() for nullable returns.

Note: Moving between NonNullable and Nullable returns a new instance of the associated class.

use Smpita\TypeAs\TypeAs;

$nullableArray = TypeAs::type($mixed)
    ->nullable()
    ->asArray();

use Smpita\TypeAs\TypeAs;

$array = $typeAsNullableInstance
    ->nonNullable()
    ->asArray();

Custom Resolver

Chain using() to resolve using a Custom Resolver.

use Smpita\TypeAs\TypeAs;

$array = TypeAs::type($mixed)
    ->using(new CustomArrayResolver())
    ->asArray();

Defaults

Chain default() to specify a default.

use Smpita\TypeAs\TypeAs;

$array = TypeAs::type($mixed)
    ->default([])
    ->asArray();

Wrapping

TypeAs::type('')->noWrap()->asArray();
TypeAs::type('')->wrap(false)->asArray();

Copying

use Smpita\TypeAs\TypeAs;

$instance = TypeAs::type($mixed);

$assignment = $instance; // $assignment mutates when $instance changes.
$copy = $instance->copy(); // $copy is unaffected by changes to $instance.
$clone = clone $instance; // $clone is unaffected by changes to $instance.

Accessing the config

use Smpita\TypeAs\Fluent\Nullable;
use Smpita\TypeAs\Fluent\NonNullable;

// Returns \Smpita\TypeAs\Fluent\TypeConfig
$config = NonNullable::make()->config();
$config = Nullable::make()->config();

Importing a config

use Smpita\TypeAs\Fluent\Nullable;
use Smpita\TypeAs\Fluent\NonNullable;
use Smpita\TypeAs\Fluent\TypeConfig;

$config = new TypeConfig(
    fromValue: $mixed,
    defaultTo: $default,
    resolveUsing: $resolver,
    arrayWrap: null,
);

$nonNullable = NonNullable::make($config);
$nonNullable = (new NonNullable())->import($config);

$nullable = Nullable::make($config);
$nullable = (new Nullable())->import($config);

Extensions

Extensions are created by passing a custom resolver to a function.

Official Extensions

 /**
  * @see \Smpita\TypeAs\Resolvers\Extensions\AsNullableFilterBool
  *
  * Uses FILTER_VALIDATE_BOOL
  * https://www.php.net/manual/en/filter.constants.php#constant.filter-validate-bool
  *
  * Returns true  on 1 1.0 "1" "true"  "yes" "on"
  * Returns false on 0 0.0 "0" "false" "no" "off" ""
  */

$filterBool = TypeAs::filterBool($mixed, $default);
$nullableFilterBool = TypeAs::nullableFilterBool($mixed, $default);

Custom Resolvers

SIGNATURES#resolver-registration

Each base 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
         *
         * Note:
         * The resolver is responsible for returning $default when appropriate.
         * See \Smpita\TypeAs\Resolvers for examples.
         */
    }
}

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

Global

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

// Fluent Helpers
$type = type($mixed);

Local

Each global helper has a local counterpart you can import if the global helper collides with another global method.

use function Smpita\TypeAs\asArray as TypeAsArray;
use function Smpita\TypeAs\asBool as TypeAsBool;
use function Smpita\TypeAs\asFilterBool as TypeAsFilterBool;
use function Smpita\TypeAs\asClass as TypeAsClass;
use function Smpita\TypeAs\asFloat as TypeAsFloat
use function Smpita\TypeAs\asInt as TypeAsInt;
use function Smpita\TypeAs\asString as TypeAsString;
use function Smpita\TypeAs\asNullableArray as TypeAsNullableArray;
use function Smpita\TypeAs\asNullableBool as TypeAsNullableBool;
use function Smpita\TypeAs\asNullableFilterBool as TypeAsNullableFilterBool;
use function Smpita\TypeAs\asNullableClass as TypeAsNullableClass;
use function Smpita\TypeAs\asNullableFloat as TypeAsNullableFloat;
use function Smpita\TypeAs\asNullableInt as TypeAsNullableInt;
use function Smpita\TypeAs\asNullableString as TypeAsNullableString;
use function Smpita\TypeAs\type as TypeAsType;

Deprecations

Please see the Upgrade Guide and 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.