Encase Functional Library

• Encase Functional Library
• Overview
• Installation
• Examples - Functional functions & OOP Methods - Method chaining - Non-mutability
• String Treatment - Encoding
• Boxing
• Types - BoxIterator - Example - Collection - Func - InvalidTypeError - Number - Str - Value - Methods
• Functions - apply - Behavioural difference with PHP internal functions - assertType - box - concat - each - find - first - isType - Types checked - join - last - map - pop - shift - size - slice - split - type - values

Overview

This library draws inspiration from others such as lodash, underscore.php and Laravel, providing various functional programming features combined with OOP-style interfaces for type abstractions. This allows functional functions to be called as if they were methods of those objects, with chainability as a sweet bonus.

There are several other features included to provide additional support for programming functionally in PHP as comfortably as in JavaScript, while taking advantage of PHP's features, including "boxing" so POD types can be easily and safely wrapped up in objects and managed with greater flexibility.

The following Functional types exist: * Collection for arrays. * Func for functions (any callable - this helps disambiguate callable strings and arrays) * Number for integers and floats. * Str for strings. Value forany* type, including objects.

All non-Value types inherit from Value.

Installation

Install using composer:

composer require encase/functional

Examples

Functional functions & OOP Methods

All Functional functions and OOP objects are under the Encase\Functional namespace. Types begin with an upper-case character whereas functions begin with a lowercase, as is conventional. Any function in Encase\Functional can be called as a method on a Functional type without importing the function.

use Encase\Functional\Str;
use function Encase\Functional\split;

$array = split('foo');        // returns: ['f', 'o', 'o']

$str = Str::make('foo');      // or: new Str('foo')
$array = $str->split();       // returns: new Collection(['f', 'o', 'o'])
$newStr = $str->join(',');    // returns: new Str('f,o,o')

As you may notice, the two methods had a significant difference when calling split(): the function call returned a plain array while the method proxy call returned a Collection instance for chainability. This is true even if you pass an object to a function - in this example, a plain array is returned rather than a Collection instance:

split(Str::make('foo'));      // returns: ['f', 'o', 'o']

If you require minimal overhead speed you may prefer the functions and dealing with POD types over the object-oriented methods. No Functional function will ever return a Functional OOP object. However, the niceties of OOP and method chaining have their benefits for more writing more presentable and less verbose code.

Method chaining

While Functional object methods mostly just proxy calls to Functional functions, they also handle any necessary type conversions to and from Functional objects where appropriate to allow for intuitive chaining:

Str::make('a.b.c.d')->split('.')->join(',');   // returns: new Str('a,b,c,d')

Non-mutability

Functional aims to reduce mutability. This means the majority of Functional functions and methods do not mutate their subject, but rather return a new value with mutations applied.

In this example, the map() function is used to return a new object with elements replaced depending on the result of a function call - leaving $array untouched in the process:

$array = new Collection('f', 'o', 'o');

// Assigns new Collection(['b', 'a', 'a']) to $newArray:
$newArray = $array->map(function ($char) {
  return $char === 'f' ? 'b' : 'a';
});

$foo = $array->join('.');      // returns: new Str('f.o.o')
$baa = $newArray->join('.');   // returns: new Str('b.a.a')

String Treatment

Functions in this library like to treat strings as arrays of unicode characters. Thus, many functions you may know from other languages to only work on arrays will work on strings just as well. For example, a substr/substring function is not necessary, as slice works just as well on strings as arrays.

// forget that slice and split exist for a second...
$string = Str::make('he?ll?o');
$array = [];

$string->each(function ($char) {
  if ($char === '?') return;
  $array[] = $char;
  if ($char === '?') return false;
});

// $array === ['h' ,'e', 'l', 'l', '?']

Encoding

UTF-8 is the most supported encoding for strings. However, as most Functional functions make use of PHP's mb_* functions, the encoding used for many is based on your PHP configuration. There is no way to override the encoding on a per-function basis.

Boxing

This library provide support for boxing#Boxing) various PHP types into fitting Functional object types. For example, a string can be easily boxed into a Encase\Functional\Str object without even specifying the type using the box static method of the Encase\Functional\Value class:

$str = Value::box('hello');   // returns: new Str('hello')
$str = box('hello');          // convenience function
$str->split();                // etc...

This is an example of implicit boxing. Values can also be boxed explicitly, which allows for conversion from a given type:

$str = Str::box(123);         // returns: new Str('123')
$value = $str->get();         // returns: '123'

See the information in the sub-sections of Types for documentation of which Functional types box which native types and the conversions that are accepted.

The box method automatically prevents double-boxing, so you will never end up with box-ception.

Types

Most types provided in this library are designed to be used as objects with functional methods, similarly to the core objects in JavaScript.

BoxIterator

An array iterator which boxes elements appropriately upon accessing them. For example, a string element is boxed into a Str instance upon accessing, and an array to a Collection instance:

Example

$iterator = new BoxIterator(['--hello--', '--world--']);

foreach ($iterator as $str) {
  echo $str->apply(new Func('trim'), '-'), ' ';
}

// Output: hello world 

Collection

Extends: Value Boxes: array

Similar to Laravel collections, a value wrapper which can be used to manage PHP arrays in a functional way.

If a string is passed to its constructor, the string is split up into an array of unicode characters.

Func

Extends: Value Boxes: callable

This is merely used as a wrapper around function objects in order to disambiguate PHP callables, which can be strings and arrays which may be called as functions.

It's worth noting that since Func implements the __invoke magic method, it is considered callable by PHP, thus it passes type hints.

Methods Func provides an interface to features provided by PHP's Reflection classes. The first call to any method requiring Reflection will instantiate a new ReflectionMethod or ReflectionFunction object appropriately and store it internally for future calls. This object can be retrieved with the getReflection method.

* isClosure(): bool - Check if the function is a closure. * isMethod(): bool - Check if the function is a method. * isInternal(): bool - Check if the function is a PHP internal function. * isVariadic(): bool - Check if the function is variadic. * getNumberOfParameters(): int - Get the number of parameters. * getNumberOfRequiredParameters(): int - Get the number of required parameters. * getReflection(): ReflectionFunctionAbstract - Get the reflection object.

InvalidTypeError

Extends: InvalidArgumentException

Represents an invalid argument, but is made to be more like the TypeError which PHP raises with static typehints when invalid arguments are passed. The error message is more helpful, following the format: Argument $arg of $func expects $type, $givenType given, called in $file on line $line

Reflection is used to automatically determine the parameter index of $arg and the $func name, as well as the file and line it was called on.

Can be created using the static method make.

Static Methods InvalidTypeError::make(string|string[] $type, mixed $value, string $paramName, int $depth = 1): InvalidTypeError

Returns a new instance of InvalidTypeError, with the error message generated using the provided parameters. $type should be an accepted type, or array of accepted types. $value is used to determine the given type. $paramName should be the name of the variable passed to $value and is displayed with a $ prepended and used to determine the argument index. $depth can be used to specify how many levels the errors originating file/line should be traced back to.

Number

Extends: Value Boxes: int, float, bool (converts: string)

Similar to the Number class in JavaScript, this is a value wrapper which can be used to manage integer and float values in a functional way.

Str

Extends: Value Boxes: string (converts: int, float, bool)

A value wrapper for PHP strings which can be used to manage integer and float values in a functional way.

Value

Implements: ArrayAccess, Countable, IteratorAggregate, JsonSerializable Boxes: object

A value wrapper for any type which can be used to handle any type of value in a functional way. This is the basis for all other value wrappers, which are mostly designed to refine the behaviour of this class, do type assertions and allow for better type identification. This class uses the Encase\Functional\Functional trait to allow proxying of method calls to Functional function calls.

As well as the interface classes this class implements, it provides the magic methods for converting the contained value to a string and invoking the contained value as a function. Obviously, the contained value must actually support these operations itself.

Methods

* boxIt(): BoxIterator - convenient shorthand alias for getBoxIterator() * count(): int - calls [size]() for the contained value. * equals($value): bool - check if the contained value is loosely equal to $value * get($key = null, $default = null) - get the contained value ($key and $default are ignored for this class, but may be used by child classes) * getBoxIterator(): BoxIterator - get a BoxIterator for the contained value. This is only valid for iterable types. * getIterator(): \Iterator - get an \Iterator for the contained value. * is($value): bool - check if the contained value is strictly equal to $value * isEmpty(): bool - check if the contained value is empty() * isNull(): bool - check if the contained value === null * make(...$value): Value - create an instance of Value (or child class) - if another Value instance is passed and is the only argument, a clone of it is returned - all provided arguments are passed on to the constructor

Functions

This is a list of the functions provided by the library. Most of these are common in many functional languages and libraries although there may be some differences and additional features. Unless otherwise stated, none of these functions modify any arguments passed to them.

All functions try to make maximum use of native PHP features as well as possible and aim to be flexible in their usability. One example of this is how many functions expecting array-like subjects will accept strings and treat them as arrays of unicode characers.

REMEMBER: Most of these functions can be called as methods on any Value-derived type (or user class using the Encase\Functional\Functional trait). When called as methods, the contained value is always passed to the function as the first argument.

apply

apply(mixed $subject, callable $func, mixed ...$args): mixed

Calls $func, passing $subject as the first argument (or a clone if $subject is an object). Optionally, more arguments ($args) may be passed which are also passed to $func after $subject. The result of $func is then returned from this function. Using this will not mutate $subject.

Behavioural difference with PHP internal functions

If $func is not an instance of Func, then PHP Reflection is used to determine if the function is built-in and not variadic, and the number of required arguments. If the function is built-in and not variadic, then $func is called using only the number of required arguments, no matter how many are passed to apply().

Why? Why required arguments only?

Other Functional functions, such as map(), use apply() to carry out callback operations while ensuring that $subject is not mutated. map() passes extra arguments to the callback which may be ignored by the function. So this would result in an error due to more arguments being passed than expected (and those arguments being of the wrong type for optional parameters):

// Hypothetical code demonstrating what would happen if apply didn't change behaviour for internal PHP functions:
$array = ['this ', ' cannot ', ' work'];
map($array, 'trim');   // causes error: trim() expects at most 2 parameters, 3 given

Rather than require passing a Closure, which then calls the intended function with the right number of arguments, apply() will carry out the steps explained above to only pass required arguments, allowing PHP internals that operate on a single subject to work predictably, meaning the above code will work without any extra effort.

So, what if you want to manually pass to an optional parameter of an internal function using apply()? Simply wrap 'trim' up in a Func:

apply('*success', new Func('trim'), '');  // result: 'success'

assertType

assertType(mixed $value, string|string[] $types, string $paramName)

Asserts that the type of $value is one of those given in $types. See isType for more details. This is designed to be used in cases where static type hinting falls short, such as allowing more than one possible type to be passed or allowing types or combinations of types that cannot be represented as type-hints.

If $value does not match any of the given types, an Encase\Functional\Exceptions\InvalidTypeError exception is thrown using $types, $value, $paramName for construction. See InvalidTypeError for more details.

This function cannot be called as a method.

box

box(mixed $value): Collection|Func|Number|Str|Value

Alias for Value::box, which takes the $value and wraps it in a fitting Functional object instance. See Boxing for details on this concept.

This function cannot be called as a method. There would be no point, since this is just an alias for a static Value method. You can however pass the Value object to it in order to promote a Value to something more fitting.

concat

concat(iterable|string $container, mixed ...$values): iterable|string

Concat appends a value onto $container, such as a string or array (or other iterable). Supports multiple arguments, each of which are concatenated in succession.

Example

concat('hello', ' world');      // returns: 'hello world'
concat([1, 2], 3, 4, 5);        // returns: [1, 2, 3, 4, 5]
$str = box('Functional');
$array = [' is', ' neat'];
$str->concat(...$array);
$str->get();                    // returns: 'Functional is neat'

each

each(iterable|stdClass|string|null $iterable, callable $func): mixed

Iterates over an iterable, string (see String Treatment) or stdClass, and calls the provided function for each element, passing the value as the first argument, the index/key as the second argument, and the subject as the third argument.

Supports early exit by returning any non-null value. Returns null, or value returned by $func in the case of early exit.

Note: $subject may be modified if $func takes a reference and modifies it.

Example with associative array

$array = [
    'apples' => 'green',
    'tomatoes' => 'red',
    'lemons' => 'yellow'
];

each($array, function ($value, $key) {
    echo $key, ' are ', $value, "\n";
});

/* Output:
  apples are green
  tomatoes are red
  lemons are yellow
*/

Example with string

$str = 'find ? the ? ticks';
$result = [];

each($str, function ($value, $index, $str) use (&$result) {
    if ($value === '?') {
        $result[$index] = \mb_substr($str, $index);
    }
});

// $result === ['? the ? ticks', '? ticks']

Example with early exit

$array = '?????';

$result = each($array, $index, function ($value) {
  if ($value === '?') {
    return 'error: '.$index;
  }
  return;
});

// $result === 'error: 3'

find

find(array|iterable|stdClass|string $value, mixed|\Closure|\Encase\Functional\Func $pred = null, int $offset = 0): array|bool

Searches forward through the container for a given value or predicate match. Returns an array like [$foundIndex, $foundValue] where $foundIndex is the index/key where the match was found, and $foundValue is the actual value that was found. If $pred is a function (see isType), it is called with each value and index/key and matches when it returns true. If $pred is null, then the first truthy value is matched. Otherwise, $pred is treated as a value and the following predicate is used:

function ($value) use ($pred) {
  return $value === $pred;
};

$offset can be used to begin the search at a certain index. If $offset is negative, the search begins that far from the end of the container. While this works fine with non-sequentially indexed arrays and associative arrays, it is always treated as an index rather than a key.

Example with array & value

$array = ['a' => false, 'b' => 1, 'c' => '1', 'd' => true, 'e' => false];
$match = find($array, true);  // returns: ['d', true]

Example with string & PHP internal function

$string = 'ábcdefg';
$match = find($string, function ($value, $index) {
  return $value === 'e' && $index === 4;
});  // returns: [4, 'e']

Example with unicode string & predicate

$string = 'ábcdefg';
$match = find($string, function ($value, $index) {
  return $value === 'e' && $index === 4;
});  // returns: [4, 'e']

Example with PHP internal function as predicate Remember to use Func to wrap string or array values, otherwise they will be treated as values to find rather than predicate functions. Only the value will be passed to PHP internal functions, meaning various PHP functions can be used with little extra effort:

$string = 'ABCdEFG';
find($string, new Func('ctype_lower'));   // returns: [3, 'd']
find($string, 'ctype_lower');             // returns: FALSE

first

first(\Traversable|iterable|string|stdClass|null $iterable): mixed|null

Gets the value of the first element in $iterable. Returns null if $iterable is empty.

$string = first('§abc');    // returns: §
$int = first([1, 2, 3]);    // returns: 1

isType

isType(mixed $value, string|string[] $types): string|FALSE

Determines if $value is any one of the given $types. Returns a string representing the name of the first type that qualifies the $value, otherwise FALSE.

The type names can be anything usable as a static type hint in PHP, those accepted by PHP's internal is_* functions or a class name which is checked with instanceof. Additionally, it can be function, which passes for a closure or Encase\Functional\Func instance (this is to allow disambiguation from strings and arrays which may be callable).

Example

isType(3.14, ['int', 'float']);           // returns: 'float'
isType(123, 'string');                    // returns: FALSE
isType('hi', 'scalar');                   // returns: 'scalar'
isType('print', ['callable', 'string']);  // returns: 'callable'
isType('print', ['function', 'string']);  // returns: 'string'
isType(new Func('print'), 'function');    // returns: 'function'
$str = new Str('print');
$str->isType(['callable']);               // returns: 'callable'

Types checked

array* - is_array() bool* - is_bool() callable* - is_callable() countable* - is_array() or instanceof \Countable (is_countable() polyfilled for PHP <7.3) double/float/real* - is_float() function* - instanceof \Closure or instanceof \Encase\Functional\Func int/integer/long* - is_int() null* - is_null() numeric* - is_numeric() object* - is_object() resource* - is_resource() scalar* - is_scalar() string* - is_string()

Any other value is treated as a class name and checked using the instanceof operator.

join

join(iterable|stdClass|array $iterable, ?string $separator = ',', string $lastSeparator = null): string

Joins all values in the $iterable into one string, separated by $separator. If $lastSeparator is provided, the last two elements are separated by that rather than $separator - if there are only two elements, only $lastSeparator is used. If null is specified for $separator, it defaults back to ','.

$array = ['you', 'me', 'them'];
join($array);                   // returns: 'you,me,them'
join($array, ', ', ' and ');    // returns: 'you, me and them'

last

last(\Traversable|iterable|string|stdClass|null $iterable): mixed|null

Gets the value of the last element in $iterable. Returns null if $iterable is empty.

$collection = Collection::make(1, 2, 3);
$object = (object)['a' => 1, 'b' => 2, 'c' => 3];
last($collection);                    // returns: 3
last($collection->getIterator());     // returns: 3
last($object);                        // returns: 3
last('ábc§');                         // returns: '§'

map

map($iterable, callable|null $func = null, bool $preserveKeys = false)

Copies $iterable, replacing each element with the value returned by $func. $func is called via apply, which has some convenient exceptions for working with PHP internal functions, so see that function for details on the invokation. Aside from those exceptions, $func is called on each iteration with: the element value, the element index/key and the $iterable itself. By default, the resulting array is re-indexed - use $preserveKeys in order to have the resulting array use the same keys as the input.

Examples

Replace element values with their keys, resetting keys (essentially array_keys).

$values = ['a' => 1, 'b' => 2, 'c' => 3];

$result = map($values, function ($value, $key) {
    return $key;
});

// $result === ['a', 'b', 'c']

Multiply each element in the array by two, while preserving keys.

$values = [1 => 1, 2 => 2, 4 => 4, 8 => 8];

$result = map($values, function ($value, $key) {
    return $value * 2;
}, true);

// $result === [1 => 2, 2 => 4, 4 => 8, 8 => 16]

Trim whitespace from a whole array of strings.

$values = [' trim ', ' these ', ' strings'];
map($values, 'trim');     // returns: ['trim', 'these', 'strings']

pop

pop(array|string|\ArrayAccess|\Traversable|\stdClass &$arrayish): mixed

This function mutates its input.

Removes the last element from the $arrayish container and returns it. This function takes the input by reference and changes its length. Treats a string as an array of unicode characters.

Examples

Pop from array.

$array = [1, 2, 3];
pop($array);          // returns: 3
// $array === [1, 2]

Pop from string.

$string = '???';
pop($string);         // returns: ?
// $string === '??'

shift

shift(array|string|\ArrayAccess|\Traversable|\stdClass &$arrayish): mixed

This function mutates its input.

Removes the first element from the $arrayish container and returns it. This function takes the input by reference and changes its length. Treats a string as an array of unicode characters.

Examples

Shift from array.

$array = [1, 2, 3];
shift($array);        // returns: 1
// $array === [1 => 2, 2 => 3]

Shift from string.

$string = '???';
shift($string);       // returns: ?
// $string === '??'

size

size(iterable|string $value): int

Alias: count

Get the size of $value. For iterable, the size will be the number of elements. For string, the size will be the number of unicode characters. Returns 0 if $value is not an iterable or string.

slice

slice(iterable|\Traversable|string $value, ?int $start, int $end = null): iterable|\Traversable|string

Extract a portion of an array, string or \Traversable object. Sliced traversables are returned as arrays. Returns the portion found starting from $start up to (but not including) $end.

Note: Unlike PHP's internal functions, this uses start and end indices for determining the range, rather than a start index and a size.

Examples

Get a substring.

slice('Hello world', 0, 5);       // returns: 'Hello'
slice('Hello world', null, -6);   // returns: 'Hello'
slice('Hello world', 6);          // returns: 'world'
slice('Hello world', -5);         // returns: 'world'

Get an array slice.

$array = [
    'one' => 1,
    'two' => 2,
    'three' => 3,
    'four' => 4,
    'five' => 5,
];
$array = slice($array, 2, -1);
// $array === ['three' => 3, 'four' => 4]

split

split(string $string, string|\Encase\Regex\Regex $separator = '', int $limit = null): array

Splits $string up into an array of strings using $separator to separate them.

If $separator is an \Encase\Regex\Regex object from the Encase Regex library, then the contained regular expression is used to match the separator.

Examples

Splitting by comma.

split('1,2,3,4', ',');      // returns: ['1', '2', '3', '4']
split('1,2,3,4', ',', 3);   // returns: ['1', '2', '3,4']

Splitting by regex.

use \Encase\Regex\Regex;

$array = split('hel.lo|wor/ld', Regex::make('/[^\w]/'));

// $array === ['hel', 'lo', 'wor', 'ld']

type

type(mixed $value): string

Gets the type of the variable based on which of PHP's is_* checks returns true (rather than using gettype). Returns 'function' for closure objects but does not work with other callables as those are strings and arrays first.

Possible return values: array, bool, int, float, function, null, object, resource, string

values

values(\Traversable|iterable|stdClass|null $iterable): string

Re-index the traversable, array or object. Equivalent to calling map($iterable) or \array_values($iterable) on arrays.

Examples

$array = ['a' => 'apple', 'b' => 'ball', 'c' => 'cat'];
values($array);     // returns: ['apple', 'ball', 'cat']