[EN]
Home made OOP "Monad", for an easier management of hypothetical values.
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.
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.
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.
As Maybe constructor access is not available, 3 factory methods are provided :
$not = Maybe::not(); // Maybe<null>
$some = Maybe::some('my value'); // Maybe<string>
$someobj = Maybe::some(new MyOwnInstance()); // Maybe<MyOwnInstance>
$nullAnyway = Maybe::some(null); // Maybe<null>
$any = Maybe::of(new MyOwnStringOption('any string value')); // Maybe<string>
$anyobj = Maybe::of(new MyOwnOption(new MyOwnInstance())); // Maybe<MyOwnInstance>
$anyNullObj = Maybe::of(new MyOwnNullOption()); // Maybe<null>
// version 0.3.0
$truthy = Maybe::some(true); // this is a truthy "When" instance
$falsy = Maybe::some(false); // this is a falsy "When" instanceTo retrieve raw optionnal value from the "$some" Maybe instance of previous example :
echo $some->value(); // "my value"Pass an optionnal value through a function an get the result :
echo $some->apply(strtoupper(...)); // "MY VALUE"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 :
$pathToAboutPage = Maybe::some('/about');
echo $pathToAboutPage->apply(trim(...), '/'); // "about", without forward slash
$function = fn(string $value, string $separator, string $add)=> trim($value, $separator) . '-' . $add
echo $pathToAboutPage->apply($function, '/','page' ); //"about-page"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 :
$maybeThen = $some->then(strtoupper(...)); // retourne un nouveau Maybe contenant "MY VALUE"
echo $maybeThen->value(); // affiche "MY VALUE"As a new Maybe instance is returned, we can chain calls of this method :
echo $some->then(strtoupper(...)) // return a new Maybe containing "MY VALUE"
->then(fn(string $value) => $value.' is not null')
->value(); // "MY VALUE is not null"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 :
echo $not->value(); // prints nothing because null
echo $not->apply(strtoupper(...)); // null too, function is not applied
echo $not->then(strtoupper(...))->value(); // still nullMaybe provides a way to substitute an "invalid" instance to a valid one by using otherwise method :
$otherwise = $not->otherwise('nothing');
echo $otherwise->value(); // prints "nothing"
echo $otherwise->apply(strtoupper(...)); // prints "NOTHING"
echo $otherwise->then(strtoupper(...)) // // Maybe<'NOTHING'>
->value(); // "NOTHING" again.Some other examples chaining methods :
echo $not->then(strtoupper(...)) // run strtoupper with a Maybe<null> won't work
->otherwise('i replace null') // new Maybe<string> available after first then() call
->then(fn(string $value) => $value . ' for demonstration') // run the function with the new instance
->value(); // prints "i replace null for demonstration"
echo $not->otherwise('i replace null') // new Maybe<string> available
->then(strtoupper(...)) // now transform initial string to upper case
->then(fn(string $value) => $value . ' for demonstration') // and append another string to the previous value
->value(); // prints "I REPLACE NULL for demonstration"The otherwise method is only applied when the value is null. So :
echo $some->otherwise('my other value') // initial $some instance returned
->then(strtoupper(...))
->then(fn(string $value) => $value . ' for demonstration')
->value(); // prints "MY VALUE for demonstration"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() :
// with Some value
echo $some->either(toUpperCase(...))
->or(fn() => 'late value')
->value(); // prints "MY VALUE"
// with None value
echo $not->either(toUpperCase(...))
->or(fn() => 'late value')
->value(); // prints "late value"And to retrieve a new Hypothetik instance from Either :
// with Some value
echo $some->either(toUpperCase(...))
->or(fn() => 'late value')
->try() // returns a Maybe<string> from "$some" value
->then(fn(string $value) => $value . ' for demonstration')
->value(); // prints "MY VALUE for demonstration"
// with None value
echo $not->either(toUpperCase(...)) // won't run this function
->or(fn() => 'late value') // returns a new Either instance holding this new function
->try() // returns a Maybe<string> with "late value'
->then(fn(string $value) => $value . ' for demonstration') // append a string and return another Maybe with new complete string
->value(); // prints "late value for demonstration"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 :
$phrase = 'this is just a test';
$when = Maybe::some(str_contains($phrase, 'just')); // truthy When
echo $when->value() ? 'valid' : 'invalid'; // 'valid'
$whenNot = Maybe::some(str_contains($phrase, 'only')); // falsy When
echo $whenNot->value() ? 'valid' : 'invalid'; // 'invalid'When class has its own static factory method :
$when = When::ever(true); // or false...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 :
$truthyWhen = Maybe::some('/about') // instance of Maybe</about>
->then(fn (string $value) => str_starts_with($value, '/')) // instance of When<false>
->either(fn() => 'truthy result') // will be executed
->or(fn() => 'falsy result') // won't be executed
->try(); // Maybe<'truthy result'>
echo $when->value(); // 'truthy result'
$falsyWhen = Maybe::some('/about') // instance of Maybe</about>
->then(fn (string $value) => trim($value, '/')) // instance of Maybe<about>
->then(fn (string $value) => str_starts_with($value, '/')) // instance of When<false>
->either(fn() => 'truthy result') // won't be executed
->or(fn() => 'falsy result') // will be executed
->value(); // raw value
echo $when; // 'falsy result'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.
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.