dreamscapes/scalars

Scalar types in PHP defined as objects to allow more type safety

Scalars

, _(*1)

Scalar value typehinting in PHP, _(*2)

About

With this library, you can use function/method typehinting for scalar values just like you would use it with objects., _(*3)

Installation

Use Composer:, _(*4)

composer require dreamscapes/scalars:dev-master (visit Packagist for list of all available versions), _(*5)

Usage

The following scalar types are available as classes:, _(*6)

• Scalar - accepts any scalar value (bool, int, float, string)
• Number - accepts any numeric value (float, int)
• Int - accepts only integers
• Float - accepts only floating point numbers
• Bool - accepts only booleans
• String - accepts only strings

Any of these can be used in function / method signatures:, _(*7)

function takeString(String $str) { /* do stuff with $str */ }

To pass a string into such function, you have two, completely equivalent options:, _(*8)

takeString(String('my string'));
// or...
takeString(new String('my string'));

And, within the function itself, you can get to the actual value passed by doing one of the following:, _(*9)

function takeString(String $str)
{
    // $str is instance of String, but we need the actual string
    // to do something useful with it:
    $str = $str->val;
    // or...
    $str = $str();
}

What if I use incorrect scalar type?

Having type hints without type safety would be like having classes without instances. And so, if you attempt to do something like this, _(*10)

// WARNING - BAD!
$bool = Bool('but I am a string!');

You will trigger an error (E_USER_ERROR to be precise):, _(*11)

Invalid type supplied for Bool, string given, _(*12)

Note: Do not attempt to convert these to exceptions and catch them - these kinds of errors are programmers' errors and should be fixed immediately., _(*13)

Casting into different types

If you have a value and you want it to be treated as a particular scalar type (i.e. you have an integer and want it to be treated as boolean), you can use one of the following, completely equivalent options:, _(*14)

$bool = Bool((bool)'I will be truthy!');
// or...
$bool = Bool::cast('I will also be truthy!');

The Scalar::cast() method utilises PHP's internal scalar conversion mechanism using settype. Whether that is a good or a bad thing is left to your own discretion., _(*15)

Where are arrays?

Arrays are not a scalar type. And you can typehint arrays without any syntactic sugar., _(*16)

License

This software is licensed under the BSD (3-Clause) License. See the LICENSE file for more information., _(*17)