README

Functional Programming utilities for PHP 5.4+

Installation
- Using composer
- Manually
License
Contributing
Further reading & suggested viewing
- Simon Holywell's Functional PHP talk at PHP Hampshire Feb 2014
A note for PHP 5.6+ users
Features
Release History

Installation

Using composer

Put the require statement for functional-programming-utils in your composer.json file and run composer install or php composer.phar install:

{
    "require": {
        "daveross/functional-programming-utils": "~4.0"
    }
}

Manually

Include all the files in the src directory, or individual files as needed:

<?php
include 'path/to/functional-programming-utils/src/compose.php';
include 'path/to/functional-programming-utils/src/curry.php';
include 'path/to/functional-programming-utils/src/math.php';
include 'path/to/functional-programming-utils/src/memoize.php';
include 'path/to/functional-programming-utils/src/prop.php';
include 'path/to/functional-programming-utils/src/Monads/Monad.php';
include 'path/to/functional-programming-utils/src/Monads/Just.php';
include 'path/to/functional-programming-utils/src/Monads/Maybe.php';
include 'path/to/functional-programming-utils/src/Monads/Either.php';
include 'path/to/functional-programming-utils/src/Monads/Left.php';
include 'path/to/functional-programming-utils/src/Monads/Right.php';

License

MIT

See why I contribute to open source software.

Buy me a coffee

Contributing

Pull requests are welcome. Unit tests are encouraged but not required.

A note for PHP 5.6+ users

Starting in PHP 5.6, you can use function at the top of a file to reference that function without typing its whole name, including the namespace. I encourage you to try it.

use function DaveRoss\FunctionalProgrammingUtils\add as add;
$x = add( 5, 5 ); // 10

Features

Mathematical functions

add

Adds two values

$x = DaveRoss\FunctionalProgrammingUtils\add( 5, 5 ); // 10

subtract

Subtracts two values

$x = DaveRoss\FunctionalProgrammingUtils\subtract( 10, 5 ); // 5

multiply

Multiplies two numbers

$x = DaveRoss\FunctionalProgrammingUtils\multiply( 5, 5 ); // 25

divide

Divides two numbers

$x = DaveRoss\FunctionalProgrammingUtils\divide( 25, 5 ); // 5

modulus

Computes the remainder after division

$x = DaveRoss\FunctionalProgrammingUtils\modulus( 13, 5 ); // 3

inverse

Inverts a number

$x = DaveRoss\FunctionalProgrammingUtils\inverse( 5 ); // -5

truthy

Checks if a value evaluates to true using standard PHP rules

$x = DaveRoss\FunctionalProgrammingUtils\truthy( 5 ); // true
$x = DaveRoss\FunctionalProgrammingUtils\truthy( 0 ); // false

true

Checks if a value is boolean true

$x = DaveRoss\FunctionalProgrammingUtils\true( true ); // true
$x = DaveRoss\FunctionalProgrammingUtils\true( 5 ); // false

falsy

Checks if a value evaluates to false using standard PHP rules

$x = DaveRoss\FunctionalProgrammingUtils\falsy( 0 ); // true
$x = DaveRoss\FunctionalProgrammingUtils\falsy( 5 ); // false

false

Checks if a value is boolean false

$x = DaveRoss\FunctionalProgrammingUtils\false( false ); // true
$x = DaveRoss\FunctionalProgrammingUtils\false( 0 ); // false

default_value

Returns a value, or a default if the value is null

$x = DaveRoss\FunctionalProgrammingUtils\default_value( 5, 10); // 10
$x = DaveRoss\FunctionalProgrammingUtils\default_value( 5, null); // 5

Property Access

array_prop

Returns a value from an array given the corresponding key, or null if the key doesn't exist in the array

$a = array( 'hello' => 'world', 'a' => 'b' );
$x = DaveRoss\FunctionalProgrammingUtils\array_prop( $a, 'hello'); // 'world'
$x = DaveRoss\FunctionalProgrammingUtils\array_prop( $a, 'test'); // null

object_prop

Returns a value from an object given the corresponding property name, or null if the property doesn't exist in the object

$o = new stdClass();
$o->hello = 'world';
$o->a = 'b';
$x = DaveRoss\FunctionalProgrammingUtils\object_prop( $o, 'hello'); // 'world'
$x = DaveRoss\FunctionalProgrammingUtils\object_prop( $o, 'test'); // null

prop

Calls array_prop or object_prop as appropriate

$a = array( 'hello' => 'world', 'a' => 'b' );

$x = DaveRoss\FunctionalProgrammingUtils\prop( $a, 'hello'); // 'world'
$x = DaveRoss\FunctionalProgrammingUtils\prop( $a, 'test'); // null

$o = new stdClass();
$o->hello = 'world';
$o->a = 'b';

$x = DaveRoss\FunctionalProgrammingUtils\prop( $o, 'hello'); // 'world'
$x = DaveRoss\FunctionalProgrammingUtils\prop( $o, 'test'); // null

Memoization

memoize

Wraps a function in a layer that stores the function's return value for every set of parameters it's called with, so the function doesn't need to be called again the next time it's called with the same parameters

$f = DaveRoss\FunctionalProgrammingUtils\memoize(function($a) { return $a; });
$x = $f(5); // 5
$x = $f(5); // 5 again, but the function didn't need to be called a second time

Currying

See Curry or Partial Application? The Difference Between Partial Application and Curry for details on how these functions differ.

partially_apply

Partially applies a function. Given a function that takes more than one parameter, returns a function that already knows the first parameter.

$add_five = DaveRoss\FunctionalProgrammingUtils\partially_apply( 'DaveRoss\FunctionalProgrammingUtils\add', 5 );
$x = $add_five( 5 ); // 10

partially_apply_right

Partially applies a function. Given a function that takes more than one parameter, returns a function that already knows the last parameter.

$divide_by_five = DaveRoss\FunctionalProgrammingUtils\partially_apply_right( 'DaveRoss\FunctionalProgrammingUtils\divide', 5 );
$x = $divide_by_five( 25 ); // 5

curry

Curries a function. Given a function that takes more than one parameter, applies a single parameter to it and returns a function that takes the next parameter until all required parameters are provided.

  function add_three_integers($a, $b, $c) {
  		return intval( $a ) + intval( $b ) + intval( $c );
  }

  $fn = DaveRoss\FunctionalProgrammingUtils\curry( 'add_three_integers' , 1 );
  $fn2 = $fn( 2 );
  $x = $fn2( 3 ); // 6

Composition

compose

Creates a new function consisting of a series of functions that each take one parameter. When the new function is called, that series of functions is called from right to left, processing the result of the previous function.

$backwards_and_uppercase = DaveRoss\FunctionalProgrammingUtils\compose( 'str_reverse', 'strtoupper' );
$x = $backwards_and_uppercase( 'dlrow olleh' ); // HELLO WORLD

Monads

Monad

Abstract parent class for Monads. A Monad is a class that wraps a single value and implements function map(callable $f). Monad::map() returns another Monad wrapping the function's return value. See the Just Monad.

Just

The Just Monad "just" wraps a value and maps functions to it.

$x = new Just( 5 );
$y = $x->map( function( $a ) { return $a * 5; } ); // Just(25)

Maybe

The Maybe Monad recognizes when it's holding a null value and returns Maybe( null ) when a function is mapped to it. Otherwise, it behaves like a Just Monad.

$x = new Maybe( 5 );
$y = $x->map( function( $a ) { return $a * 5; } ); // Maybe(25)

$a = new Maybe( null );
$b = $a->map( function( $a ) { return $a * 5; } ); // Maybe(null)

maybe function

May be used to extract the value from a Maybe Monad.

$x = new Maybe( 5 );
$y = maybe(null, function( $a ) { return $a * 5; }, $x); // 25

Either

To implement conditionals, a function can be defined as returning either one value or another. This is represented with the Either Monad and its children, Left and Right.

Left

The Left Monad wraps an error value from an unsuccessful function call.

$f = function($a) {
	return ( $a < 10 ) : Left::of( 'too low' ) : Right::of( $a + 1 );
}

$x = $f( 15 ); // Right( 16 )
$y = $f( 5 ); // Left( "too low" )

Right

The Right Monad wraps the result of a successful function call.

$f = function($a) {
	return ( $a < 10 ) : Left::of( 'too low' ) : Right::of( $a + 1 );
}

$x = $f( 15 ); // Right( 16 )
$y = $f( 5 ); // Left( "too low" )

either function

May be used to extract the value from either a Left Monad or a Right Monad.

$x = Left::of( 5 );
$y = Right::of( 7 );

$left_handler = function( $a ) { return $a * 2; };
$right_handler = function( $a ) { return $a * 3; };

$a = either($left_handler, $right_handler, $x); // 10
$b = either($left_handler, $right_handler, $y); // 21

Release History

2015-08-18 1.0.0 Initial release
2015-12-16 2.0.0 Fixes the semantics of currying vs partial application
2016-01-30 3.0.0 Changed "Functor" to "Monad", which is more accurate
2016-05-23 4.0.0 Scrutinizer CI integration, PSR-2 compliance

daveross / functional-programming-utils

Maintainers

Details