Download the PHP package serenitylabs/phatcats without Composer
On this page you can find all versions of the php package serenitylabs/phatcats. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download serenitylabs/phatcats
More information about serenitylabs/phatcats
Files in serenitylabs/phatcats
Package phatcats
Short Description A functional programming library that brings Haskell and Scala Cats like features to PHP.
License
Informations about the package phatcats
Functional PHP
Contents
- About
- Running Tests
- Type Classes
- Types
- LinkedList
- Maybe
- Accessing the Value
- Maybe as Functor
- Maybe as Monad
- Maybe as Monoid
- Converting
- Either
- MaybeT
- Validation
- AssociativeArray
About
This library is designed to give PHP developers some Category-Theory-like facilities available in a language like Haskell.
Running Tests
Natively
This project uses Composer for dependency management and PHPUnit for unit testing. First, install the dependencies (including dev dependencies):
$ composer install --dev
PHPUnit requires access to autoloading and the autoloading files must first be generated by composer with the following command:
$ composer dump-autoload
Then, run the unit tests with
$ ./vendor/bin/phpunit
Using Docker
If you have docker installed you can run tests with:
$ make test
Type Classes
The following type classes are supported:
SemiGroup
Monoid
Functor
Monad
Applicative
Note that not all types support all type classes. For more information on type classes check out the wikipedia page.
A Tale of Two Types of Type Class
The Typeclass
directory contains the type classes that this
library implements. They are implemented as interfaces that contain the methods
of the type class. For example this is the SemiGroup
type class:
The above interface can be implemented to combine two objects of any type. For
example, here's an implementation for the Maybe
type (this gives the same
behavior as the Haskell instance):
But you may also notice the ObjectTypeclass
directory. This directory contains a set of traits that
mirror the type class interfaces. It turns out that in a majority of cases type
class functions can be implemented as methods on the target type. Therefore,
most of the type classes have counterparts in the ObjectTypeclass
directory directory. These object type classes are
prefixed with Object
. For example, here's ObjectSemiGroup
, the object
version of the SemiGroup
type class:
The first argument is a value whose type should be the same as the type of
this
and will be appended to it. Also note the second SemiGroup
parameter. This is used to combine the values contained within the objects that
are being appended. This is the same value that was passed as a constructor
argument in the implementation of the MaybeSemiGroup
class above.
One example of a type class function that cannot be implemented as a target
object method is pure
from the Applicative
type class. This is the main
reason that the type classes in the Typeclass
directory
exist; otherwise, they might not be needed!
Types
This library supports the following types:
AssociativeArray
Attempt
Either
LinkedList
Maybe
MaybeT
Validation
Note that not all of these types have instances of the above type classes.
Likewise there are instances of type classes that do not have a corresponding
type (e.g., there are instances of Monoid
for both int
s and string
s but no
corresponding library types).
LinkedList
The LinkedList
type is an abstract data type implementing a typical linked list data structure.
Creating
LinkedList
's should be created using an instance of the LinkedListFactory
class. For example, you can create an empty list:
You can create a LinkedList
from a PHP array like so:
You can also easily create a range of values. This works exactly the same as the standard library function range.
LinkedList Monoid
LinkedList
s can be append
ed:
LinkedList Functor
As expected, LinkedList
s are functors. Simply pass a function of one
argument to the map
method:
LinkedList Monad
They are also monads:
LinkedList Applicative
The list applicative may be a little unintuitive if you've never seen it before. It allows you to apply each function in a list of functions to each of a list of arguments. An example may make it a bit clearer.
The __invoke
magic method can also be used to achieve the same result:
You can even call a LinkedList
of no-argument functions:
LinkedList Traversable
The traverse
method of the Traversable
type class is another method that at
first may seem a little strange but is actually quite useful. traverse
takes
as its first argument a function that takes an element of the LinkedList
and
returns some monad. As its second argument it takes an instance of that same
monad. The return value of traverse
is an instance of the monad wrapping a
LinkedList
containing the values that were wrapped in monads returned by the
passed-in function. That was a mouthful but it's more intuitive when seen in an
example. First, let's define a function that returns a Maybe
:
Then we'll traverse a list of integers with that function:
traverse
is useful for when you want to map over a LinkedList
but the result
of doing so would give you a LinkedList
of some monad. Using traverse
inverts the LinkedList
and the monad.
But note what happens in this example if one of the calls to $divideTwelveBy
returns Nothing
:
The Traversable
type class also has a method sequence
that is useful for the
situation when you already have a LinkedList
of some monad:
LinkedList Foldable
LinkedList
s can also be folded in various ways. Here's the classic example of
summing a list of integers:
Or multiplying the elements of the same list:
There's also foldRight
which can be used, among other things, to concatenate
two LinkedList
s:
Then there's fold
which takes some monoid as it's argument. The idea with
fold
is that it presumes that the elements are all some monoid and combines
each of them by append
ing them all together. The monoid argument is needed in
the case that the LinkedList
is empty.
foldMap
is similar to fold
but takes as a second parameter a function that
converts each element to a monoid and then append
s them. Here we have a
LinkedList
of strings; not a LinkedList
of Maybe
strings as above. The
$toMonoid
function converts them before append
ing them.
LinkedList Collection
LinkedList
also implements the Collection
trait. All operations work as
expected and we will not describe them in detail except to give an example of
filtering a LinkedList
.
Maybe
Maybe
is intended to be used to represent the situation where there is the
possibility of having an absense of a value. Typically, you would use Maybe
when you might ordinarily return a null value from a function. Sometimes
Maybe
is also used to represent an error condition.
Maybe
is impelemented as an abstract class with two concrete sub-classes:
Just
and Nothing
. But you cannot instantiate these sub-classes directly;
you must use static creation methods defined in the Maybe
class. If you want
to put a regular value in a Maybe
context, use the fromValue()
static method
like so:
After the above code executes, $maybeInt
will be an instance of Just
,
unless $myInt
was null in which case $maybeInt
will be an instance of
Nothing
. If you want to represent the absence of value, use the nothing()
static method:
Accessing the Wrapped Value
You may want to get direct access to the value wrapped in a Maybe
. This only
makes sense if you have a default value that can be used in the case that your
Maybe
is Nothing
. In Haskell you would use the fromMaybe
function
to do this. Here, you do this by calling the getOrElse
method like so:
Maybe as Functor
Another common desire is to simply apply a regular function to the value wrapped
in the Maybe
and to have the returned value wrapped back up in another
Maybe
. A datatype used in this manner is known as a Functor
.
The following code shows how you could convert the string "apples" to uppercase
while it's contained in a Maybe
:
But if $a
had been an instance of Nothing
, then the result would have been
Nothing()
and the strtoupper
function would never have been run. You can
also chain map
s:
There are a couple of things to note here. First, map
takes a callable
. In
PHP callable
s take several forms but one of them is a string and in the first
call to map
, we passed in the string version of a built-in PHP function. In
the second case we pass in an anonymous function, also a callable
. See PHP's
documentation on
callable
for more
info. If calling a function using a string seems strange, good; it is strange!
:)
Second, callable
s passed into map
must be functions of one argument and
that argument will be the value wrapped in the Maybe
. Third, the value
returned by this function will automatically be wrapped back up in a Maybe
.
So the result of calling map
on a Maybe
is again a Maybe
which is what
allows us to chain calls to map
this way.
Maybe as Monad
It's not uncommon that the function you want to apply to the value wrapped in
the Maybe
itself returns a Maybe
. You can't simply use the map
method
in this case. To demonstrate why, let's first create a function that returns
Maybe
. A classic example is the function head()
which returns the first
element of an array. Strangely, PHP does not have such a function and the
recommended approach is not straitforward as evidenced by this StackOverflow
answer: http://stackoverflow.com/a/3771228. But even if you use the convoluted
solution described there, you still have to deal with a possible NULL
value
being returned in the case of an empty array.
The following function hides the complexity of getting the first element of an
array and returns a Maybe
type so that we don't need to deal with NULL
s:
When given a non-empty array, the above function will return Just($v)
where
$v
is the first value of the array argument. It will return Nothing
in all
other cases. See this file for examples of using this
function.
To see why we can't use this function with map()
let's expand on the example
we used above but instead of starting off with a string wrapped in a Maybe
, we
have an array of string:
As you can see we're left with a Just
inside of a Just
and this is almost
certainly not what you're going to want, in general. To fix this, we simple
need to use the flatMap
method instead:
A datatype used in this way is called a Monad
.
Maybe as Monoid
You may find yourself in a situation where you want to combine several Maybe
s
into one Maybe
. In Haskell you would do this the the mappend
function
or the (<>)
operator
Here, you can do this using the append
method. The following code shows how
this works.
Converting
It is extremely common to want to convert your Maybe
into some other type. In
Haskell you would use the maybe
function
to achieve this. This library does not have such a function but you can use
other techniques to achieve the same result. For example, you may want to
convert a Maybe
into an HTTP response. You could use PHP's instanceof
operator like so:
A slightly better but equivalent way is to use the provided isNothing()
method:
The recommended way to convert a Maybe
to something else is to use
the Visitor Pattern. You
create a Maybe
visitor by creating a class that implements the MaybeVisitor
interface like so:
And you do the conversion by creating an instance of this visitor and passing it
to the accept
method of the Maybe
:
And that's it!
Either
The Either
datatype is used to represent one of two possible values. Either
is very similar in functionality to Maybe
- So similar in fact that I'm not
going to go into detail on its use since it would be almost identical to what
was presented for Maybe
. But I will note the differences here.
Where Maybe
is used to signal a possible lack of a value, Either
is often
used to signal the possibility of an error (though it is more general than
that). The two sub-classes of the Either
abstract class are the rather
unintuitively named Left
and Right
. This is because the Either
type is
actually more general than simply indicating an error; it can be used to return
any two possibilities. We use Either
in this library for no other reason than
because it's what Haskell does.
The Right
subclass is used to signal a successful calculation. You create an
instance like so:
The Left
subclass is used to signal an error and you create an instance like
so:
Notice that we created a Left
by passing a string containing an error
message. This is a common way to use Either
for signalling error but Left
can contain any type and we could have just as correctly (and possibly more
clearly) passed in a custom error or exception class.
These are the only significant differences with Maybe
.
MaybeT
TBD
AssociativeArray
AssociativeArray
is a simple wrapper around PHP's native array so array/list
processing methods could be added to it. Currently it only contains an
implementation for the Traversable
trait.
To create an instance of an AssociativeArray
, one simply calls the
constructor:
AssociativeArray Traversable
There are two methods in the Traversable
trait: traverse()
and
sequence()
. sequence()
is the simpler of the two so we'll start with that.
In the case of Maybe
, sequence()
is most-commonly used to convert an array
of Maybe
to a Maybe
of array as follows:
Note that an instance of an Applicative
must be passed to the sequence()
method. This is an unfortunate consquence of dynamic typing where the type of
the objects contained in the array is not known in the case of an empty array.
The traverse()
method is similar except that it gives you the opportunity to
run a function on each value in the array. To demonstrate this, we first define
a function that returns an Either
type (see Either):
Then we use that function in a call to traverse()
:
Note that both sequence()
and traverse()
have the characteristic that if one
or more elements in the array is Nothing
(in the case of sequence()
) or if
the function passed in to traverse()
evaluates to Nothing
(in the case of
traverse()
), then the result is also Nothing
. Let's show this by looking at
a slightly modified version of the above sequence()
example: