Download the PHP package ascetik/hypothetik without Composer

Hypothetik

[EN]

Home made OOP "Monad", for an easier management of hypothetical values.

Release notes

Version 0.3.0 : still a draft version.

Php version : 8.2.14

• New Hypothetik interface, describing the behavior of a monad included in this package.
• Maybe class implements Hypothetik interface
• New When, Hypothetik implementation to handle booleans.

Descriptions

Interfaces

OptionnalValue is a general interface shared by both Hypothetik an Option instances.

• OptionnalValue::isValid(): bool : check validity of a value (!null & !false)
• OptionnalValue::value(): mixed : return Option raw value

The Hypothetik interface describes the way to handle a value which may be null or false using callables.

• Hypothetik::apply(callable, ...mixed): mixed : return the result of given callable using the Option value
• Hypothetik::either(callable, ...mixed): Either : return an Either instance according to an Option.
• Hypothetik::then(callable, ...mixed): Hypothetik : return a new Hypothetic instance with the result of given callable.
• Hypothetik::otherwise(mixed): Hypothetik : choose an alternative to return if the Option value is invalid.

The Option interface describes the behavior of an instance containing the exepcted value :

• Option::apply(callable, ?array): mixed : return the result of given function with Option value as first parameter
• Option::equals(Option): bool : Check equality with another Option
• Option::isValid(): bool : see OptionnalValue interface
• Option::value(): mixed : see OptionnalValue interface

This package includes 2 Option implementations : final class None and final class Some. Anyone can build another implementation of Option to replace Some class. That's why this interface is exposed here.

An Option is a simple ValueObject with simple behaviors, unuseful outside of an Hypothetik instance.

Available Implementations

final class Maybe : The Maybe class is the main tool of this package. It handles an Option which may contain a value, or may not, and drives different operations on this value, or not...

• Maybe::equals(Maybe): bool : check equality with another Maybe instance.
• Maybe::apply(callable, ...mixed): mixed : see Hypothetik interface
• Maybe::either(callable): Either : see Hypothetik interface
• Maybe::isValid(): bool : see OptionnalValue interface
• Maybe::otherwise(mixed): Hypothetik : see Hypothetik interface
• Maybe::then(callable, ...mixed): Hypothetik : see Hypothetik interface
• Maybe::value(): mixed : see OptionnalValue interface
• static Maybe::not(): Maybe : return a Maybe instance with a None option
• static Maybe::of(Option): Maybe : return a Maybe instance with given Option instance.
• static Maybe::some(mixed): Hypothetik : return a Hypothetik instance with given value

Maybe contructor is private. See examples below for instanciation.

final class When : (v.0.3.0) This implementation works almost like Maybe. The difference is that When contains an Option with a bool value and a falsy Option is considered as invalid.

• When::apply(callable, ...mixed): mixed : see Hypothetik interface
• When::either(callable): Either : see Hypothetik interface
• When::isValid(): bool : see OptionnalValue interface
• When::otherwise(mixed): Hypothetik : see Hypothetik interface
• When::then(callable, ...mixed): Hypothetik : see Hypothetik interface
• When::value(): mixed : see OptionnalValue interface
• static When::ever(bool): When : return a Maybe instance with given value

Private constructor. Use When::ever(bool) or Maybe::some(bool) methods to build an instance.

final class Either :

The Either class handles a function to execute according to a Maybe Option value.

• Either::or(callable, ...mixed): Either : return an new Either instance if maybe's value is null.
• Either::try(): Maybe : return a new Maybe instance with the result of current Either function.
• Either::value(): mixed : retourne la valeur contenue par le Maybe
• Either::static use(Maybe, callable, ...mixed): Either : récupération d'une instance de Either, constructeur privé

An Either instance is exposed by a Hypothetik implementation for usage, unuseful in any other context.

final class None is a "null value" Option. final class Some is a not null value Option.

Usage

Construction

As Maybe constructor access is not available, 3 factory methods are provided :

Valid value : mixed value not null

To retrieve raw optionnal value from the "$some" Maybe instance of previous example :

Pass an optionnal value through a function an get the result :

The Option value is always passed to the function as first parameter.

It is possible to add arguments, separated by comas. The order of the arguments is important.

Another example with some added arguments :

It is possible to get a new Hypothetik instance containing the result of a function. Once again, the Option value is always passed to the function as first parameter and arguments can be added :

As a new Maybe instance is returned, we can chain calls of this method :

Invalid value : null value

With a null value, things are slightly different. Both apply() and value() methods will return null again. The then() method returns a Maybe with a null Option value.

Take a look at the "$not" instance from the first example :

Maybe provides a way to substitute an "invalid" instance to a valid one by using otherwise method :

Some other examples chaining methods :

The otherwise method is only applied when the value is null. So :

Of course, we already know the content of the instances of the examples above. During runtime, we just can suppose that our value could be null. Sometimes, then() and otherwise() are not enough to make the job we want to. Another possibility is to use either() :

And to retrieve a new Hypothetik instance from Either :

Boolean value :

An hypothetik boolean value works a different way. It always holds an Option with a boolean value where false is the invalid one. The Hypothetik interface ensures a fully substitutionnable instance, providing the hability to chain methods from a Maybe to a When or reverse.

Here's a simple example :

When class has its own static factory method :

Methods apply() and then won't use the boolean value as first function parameter, this time. Additionnal rguments are allowed, separated by comas, just like Maybe.

Combining Maybe and When instance calls :

Notes

No dependency injection. User has to provide required instances if needed. A Maybe cannot carry another Hypothetik, an Option cannot carry another Option. Trying to do so will return the given instance as is.

Issues

I'm still not able to use Php Documentation properly in order to provide autocompletion from any IDE. Problems on generic types handling.

I still don't need any Hypothetik container to handle multiple Hypothetik instances. I'll think about this kind of implementation only if necessary...

Maybe some tests are still missing. I'm not sure to cover all possible use cases.