README.md

IDLES - a PHP functional library

A PHP functional utility library, port of Javascript Lodash/Fp and Ramda libraries to PHP.

All functions are side-effect free and automatically curried, data is immutable.

The iterable collection parameter is usually supplied last to make currying convenient.

Lazy / delayed evaluation is supported in functional pipelines.

Go to https://idlephp.tech for more details, documentation and examples.

Requirements

PHP 7.4 or higher

Installation

composer require miroshnikov/idles

Roadmap

Note

Idles is currently under active development. Roadmap is to add all methods from Lodash and Ramda libraries and some functional tools.

Documentation

Array

concat

concat(?iterable $array, $value): iterable

Concatinates $array with additional iterables/values

count

count(callable $predicate, ?iterable $collection): int

Counts the number of items in $collection matching the $predicate

countBy

countBy(callable $iteratee, ?iterable $collection): array

Returns an array: [$iteratee($value) => number of times the $iteratee($value) was found in $collection]

drop

drop(int $n, ?iterable $collection): iterable

Skips the first $n elemens and returns the rest of the iterable

dropRight

dropRight(int $n, ?iterable $collection): iterable

Skips the last $n elements

findIndex

findIndex(callable $predicate, ?iterable $collection): int

Like find but returns the index of the first element predicate returns truthy for, -1 if not found

findLastIndex

findLastIndex(callable $predicate, ?iterable $collection): int

Like find but returns the index of the last element predicate returns truthy for, -1 if not found

flatten

flatten(?iterable $collection): iterable

Flattens iterable a single level deep.

flattenDeep

flattenDeep(?iterable $collection): iterable

Recursively flattens iterable.

flattenDepth

flattenDepth(int $depth, ?iterable $collection): iterable

Recursively flatten array up to depth times.

fromPairs

fromPairs(?iterable $collection): array

Creates a new record from a list key-value pairs. The inverse of toPairs.

head

head(?iterable $collecton)

Gets the first element of iterable

indexOf

indexOf($value, ?iterable $collection): int

Returns the index of the first occurrence of $value in $collection, else -1.

intersection

intersection(?iterable $record1, ?iterable $record2): array

Returns unique values that are included in both records

intersectionBy

intersectionBy(callable $iteratee, ?iterable $record1, ?iterable $record2): array

Like intersection but invokes $iteratee for each element before comparison.

intersectionWith

intersectionWith(callable $comparator, ?iterable $record1, ?iterable $record2): array

Like intersection but invokes $comparator to compare elements.

join

join(string $separator, ?iterable $collection): string

Joins iterable elements separated by $separator

last

last(?iterable $collecton)

Gets the last element of iterable

nth

nth(int $offset, ?iterable $collection)

Returns the $offset element. If $offset is negative the element at index length + $offset is returned.

remove

remove(int $start, int $count, ?iterable $iterable): array

Removes items from $iterable starting at $start and containing $count elements.

slice

slice(int $start, int ?$end, ?iterable $collection): iterable

Retruns a slice of $iterable from $start up to, but not including, $end.

take

take(int $n, ?iterable $collection): iterable

Takes n first elements from iterable

takeRight

takeRight(int $n, ?iterable $collection): array

Returns a slice of iterable with n elements taken from the end.

uniq

uniq(?iterable $collection): array

Removes duplicates using ===

uniqueBy

uniqBy(callable $iteratee, ?iterable $collection): array

Like uniq but apply $iteratee fist

uniqWith

uniqWith(callable $predicate, ?iterable $collection): array

Like uniq but uses $predicate to compare elements

without

without(array $values, ?iterable $collection): iterable

Returns $iterable without $values

zip

zip(iterable $a, iterable $b): iterable

Creates an iterable of grouped elements, the first of which contains the first elements of the given iterables, the second of which contains the second elements, and so on.

zipWith

zipWith(callable $iteratee, iterable $a, iterable $b): iterable

Like zip except that it accepts $iteratee to specify how grouped values should be combined.

Collection

all

all(?callable $predicate, ?iterable $collection): bool

Checks if $predicate returns truthy for all elements of $collection. Stop once it returns falsey

any

any(callable $predicate, ?iterable $collection): bool

Checks if $predicate returns truthy for any element of $collection. Stops on first found.

each

each(callable $iteratee, ?iterable $collection): iterable

Iterates over elements of $collection. Iteratee may exit iteration early by returning false.

filter

filter(callable $predicate, ?iterable $collection): iterable

Returns elements $predicate returns truthy for.

find

find(?callable $predicate, ?iterable $collection)

Returns the first element $predicate returns truthy for.

flatMap

flatMap(callable $iteratee, ?iterable $collection): iterable

Maps then flatten

flatMapDeep

flatMapDeep(callable $iteratee, ?iterable $collection): iterable

Like flatMap but recursively flattens the results.

flatMapDepth

flatMapDepth(callable $iteratee, int $depth, ?iterable $collection): iterable

Like flatMap but flattens the mapped results up to $depth times

groupBy

groupBy(callable $iteratee, ?iterable $collection): array

Creates an array composed of keys generated from running each value through $iteratee.

includes

includes($value, ?iterable $collection): bool

Checks if $value is in $collection.

indexBy

indexBy(callable $iteratee, ?iterable $collection): iterable

Creates a record composed of keys generated from the results of running each element of $collection through $iteratee.

map

map(callable $iteratee, ?iterable $collection)

Run each element in $collection through $iteratee.

orderBy

orderBy(array $iteratees, array $orders, ?iterable $collection)

Like sortBy but allows specifying the sort orders

partition

partition(callable $predicate, ?iterable $collection): array

Split $collection into two groups, the first of which contains elements $predicate returns truthy for, the second of which contains elements $predicate returns falsey for.

reduce

reduce(callable $iteratee, $accumulator, ?iterable $collection)

Reduces $collection to a value which is the accumulated result of running each element in collection through $iteratee

resolve

resolve(array $resolvers, array $record): array

Adds new properties to $record using $resolvers.

sort

sort(array $comparator, ?iterable $collection): array

Sorts $collection using $comparator comparison ($a <=> $b) function

sortBy

sortBy(array $comparators, ?iterable $collection): array

Sorts $collection in ascending order according to $comparators.

sortWith

sortWith(array $comparators, ?iterable $collection): array

Sorts a $collection according to an array of comparison ($a <=> $b) functions

values

values(?iterable $collection): iterable

Returns an indexed iterable of values in $collection.

Function

always

always($value)

Returns a function that always returns the given value.

applyTo

applyTo($value, callable $interceptor)

Returns $interceptor($value).

ary

ary(int $n, callable $fn): callable

Creates a function that invokes $fn, with up to $n arguments, ignoring any additional arguments.

ascend

ascend(callable $func, $a, $b): callable

Makes an ascending comparator function out of a function that returns a value that can be compared with <=>

attempt

attempt(callable $fn)

Calls $fn, returning either the result or the caught exception.

compose

compose(callable ...$funcs): callable

Like pipe but invokes the functions from right to left.

curry

curry(callable $f): callable

\Idles\_ const may be used as a placeholder.

curryRight

curryRight(callable $f): callable

Like curry but arguments are prepended.

descend

descend(callable $func, $a, $b): callable

Makes an descending comparator function out of a function that returns a value that can be compared with <=>

flip

flip(callable $fn): callable

Returns a new curried function with the first two arguments reversed

juxt

juxt(array $funcs): callable

Applies a list of functions to a list of values.

memoize

memoize(callable $func): callable

Creates a function that memoizes the result of $func. $resolver returns map cache key, args[0] by default.

negate

negate(callable $predicate): callable

Creates a function that negates the result of the $predicate function.

once

once(callable $fn): callable

$fn is only called once, the first value is returned in subsequent invocations.

partial

partial(callable $fn, array $partials): callable

Creates a function that invokes $fn with $partials prepended to the arguments. \Idles\_ const may be used as a placeholder.

partialRight

partialRight(callable $fn, array $partials): callable

Like partial but $partials are appended.

pipe

pipe(callable ...$funcs): callable

Left-to-right function composition. The first argument may have any arity; the remaining arguments must be unary.

tap

tap(callable $interceptor, $value)

Calls $interceptor($value) then returns the original $value

times

times(callable $iteratee, int $n): array

Calls the iteratee $n times, returning an array of the results of each invocation.

tryCatch

tryCatch(callable $tryer, callable $catcher, $value)

Calls $tryer, if it throws, calls $catcher

unary

unary(callable $fn): callable

ary(1, $fn)

Logic

allPass

allPass(array $predicates): callable

Returns a function that checks if its arguments pass all $predicates.

anyPass

anyPass(array $predicates): callable

Returns a function that checks if its arguments pass any of the $predicates.

both

both(callable $func1, callable $func2): callable

Resulting function returns $func1(...$args) if it is falsy or $func2(...$args) otherwise, short-circuited

cond

cond(array $pairs): callable

Iterates over $pairs and invokes the corresponding function of the first predicate to return truthy.

defaultTo

defaultTo($default)($value)

Returns $value ?? $default

either

either(callable $func1, callable $func2): callable

Resulting function returns $func1(...$args) if it is truthy or $func2(...$args) otherwise, short-circuited.

ifElse

ifElse(callable $predicate, callable $onTrue, callable $onFalse): callable

Resulting function returns $onTrue(...$args) if $predicate(...$args) is truthy or $onFalse(...$args) otherwise.

not

not($a): bool

returns !$a

unless

unless(callable $predicate, callable $whenFalse, mixed $value)

Returns $predicate($value) ? $value : $whenFalse($value)

when

when(callable $predicate, callable $whenTrue, mixed $value)

Returns $predicate($value) ? $whenTrue($value) : $value

Math

add

add(int|float $a, int|float $b): int|float

$a + $b

dec

dec(int $number): int

Returns $number - 1

divide

divide(int|float $a, int|float $b): int|float

$a / $b

gt

gt($a, $b): bool

$a > $b

gte

gte($a, $b): bool

$a >= $b

inc

inc(int $number): int

Returns $number + 1

lt

lt($a, $b): bool

$a < $b

lte

lte($a, $b): bool

$a <= $b

modulo

modulo(int|float $a, int|float $b): int

$a % $b

multiply

multiply(int|float $a, int|float $b): int|float

$a * $b

round

round(int $precision, int|float $number): float

Rounds $numberto specified $precision

subtract

subtract(int|float $a, int|float $b): int|float

$a - $b

sum

sum(?iterable $collection): int|float

Sums elements in iterable

sumBy

sumBy(?callable $iteratee, ?iterable $collection): int|float

Like sum but $iteratee is invoked for each element in iterable to generate the value to be summed.

Record

assignDeep

assignDeep(array $iterables): array

Merges properties recursively, numeric keys are overwritten.

defaults

defaults(?iterable $record1, ?iterable $record2): array

Merges properties from right to left, numeric keys are overwritten.

evolve

evolve(array $transformations, ?iterable $record): array

Creates a new record by recursively calling transformation functions with $record properties.

extend

extend(?iterable $source1, ?iterable $source2): array

Merges properties, numeric keys are overwritten.

has

has(string|int $key, ?iterable $record): bool

Checks if $record has $key

hasPath

hasPath(string|int|array $path, ?iterable $record): bool

Checks if $path exists in $record

invert

invert(?iterable $collection): array

Replaces keys with values. Duplicate keys are overwritten.

keys

keys(?iterable $record): iterable

Returns an indexed iterable of keys in $record.

merge

merge(?iterable $source1, ?iterable $source2): array

Merges properties, numeric keys are appended.

mergeDeep

mergeDeep(array $iterables): array

Merges properties recursively, numeric keys are appended.

mergeLeft

mergeLeft(?iterable $left, ?iterable $right): array

calls merge($right, $left)

mergeWith

mergeWith(callable $customizer, ?iterable $left, ?iterable $right): array

Like merge but if a key exists in both records, $customizer is called to the values associated with the key

modifyPath

modifyPath(array|string|int $path, callable $updater, ?iterable $record)

Creates new record by applying an $updater function to the value at the given $path.

objOf

objOf(string $key, $value): array

Creates an array containing a single key => value pair.

omit

omit(array $keys, ?iterable $collection): iterable

The opposite of pick. Returns record without $keys.

omitBy

omitBy(callable $predicate, ?iterable $record): iterable

The opposite of pickBy. Returns properties of $record that $predicate returns falsey for.

path

path(array|string $path, ?iterable $collection)

Retrieve the value at a given path.

paths

paths(array $paths, ?iterable $collection): array

Keys in, values out. Order is preserved.

pick

pick(array $keys, ?iterable $collection): iterable

Returns record containing only $keys

pickBy

pickBy(callable $predicate, ?iterable $record): iterable

Returns record containing only keys $predicate returns truthy for.

pluck

pluck(string|int $key, ?iterable $collection)

Returns a new array by plucking the same named property off all records in the array supplied.

prop

prop(string|int $key, ?iterable $record)

Return the specified property.

propEq

propEq(string|int $key, $value, ?iterable $record): bool

Returns $record[$key] == $value

setPath

setPath($path, $value, ?iterable $record)

Return copy $record with $path set with $value

toPairs

toPairs(?iterable $record): iterable

Converts a record into an array of [$key, $value]

where

where(array $spec, ?iterable $record): bool

Checks if $record satisfies the spec by invoking the $spec properties with the corresponding properties of $record.

whereAny

whereAny(array $spec, ?iterable $record): bool

Checks if $record satisfies the spec by invoking the $spec properties with the corresponding properties of $record. Returns true if at least one of the predicates returns true.

whereEq

whereEq(array $spec, ?iterable $test): bool

Check if the $test satisfies the $spec

String

escape

escape(string $s): string

Converts the characters "&", "<", ">", '"', and "'" to their corresponding HTML entities.

escapeRegExp

escapeRegExp(string $regexp): string

Escapes regular expression

split

split(string $separator, string $s): array

Splits string by $separator.

startsWith

startsWith(string $target, string $s): bool

If string starts with $target.

toLower

toLower(string $s): string

Converts string to lower case

toUpper

toUpper(string $s): string

Converts string to upper case

words

words(string $pattern, string $string): array

Splits string into an array of its words.

Util

collect

collect(?iterable $iterable): array

Collects any iterable into array

eq

eq($a, $b): bool

$a == $b

equals

equals($a, $b): bool

$a === $b

F

F(...$args): bool

Always returns false

identity

identity($value)

Returns the first argument it receives.

iterate

iterate(callable $f, $value): iterable

Returns a generator of $value, $f($value), $f($f($value)) etc.

just

just($value): Optional

Returns an Optional with the specified non-null value

nothing

nothing(): Optional

Returns an empty Optional

now

now(): int

Returns the timestamp of the number of seconds

Optional

just(mixed $value): Optional

Maybe/Option monad (container) which may or may not contain a non-null value. Has methods:

isPresent(): bool - true if not empty
isEmpty(): bool - true if empty
get(): mixed - returns value, throw exception if empty
orElse(mixed $default): mixed - returns the contained value if the optional is nonempty or $default
orElseThrow(Exception $e) - returns the contained value, if present, otherwise throw an exception
map(callable $f): Optional - If a value is present, apply the $f to it, and if the result is non-null, return an Optional describing the result
flatMap(callable $f): Optional - use instead of map if $f returns Optional
filter(callable $predicate): Optional - if a value is present and matches the $predicate, return an Optional with the value, otherwise an empty Optional.

size

size(array|Countable|object|string|callable $value): int

Returns size of a countable, number of parameters of a function, lenght of string or number of properties of an object

T

T(...$args): bool

Always returns true