miroshnikov / idles
A PHP functional utility library, port of Lodash/Ramda with lazy (idle) evaluation
Requires
- php: >=7.4
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.14
- pestphp/pest: ^2.34
- squizlabs/php_codesniffer: ^3.7
README
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|string $collection): int
Returns the index of the first occurrence of $value in iterable or string, 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
lastIndexOf
lastIndexOf($value, ?iterable|string $collection): int
Returns the index of the last occurrence of $value in iterable or string, else -1.
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.
splitAt
splitAt(int $index, array|string $array): array
Splits a given array or string at a given index.
splitEvery
splitEvery(int $length, array|string $array): array
Splits an array or string into slices of the specified length
splitWhen
splitWhen(callable $predicate, array $array): array
Splits an array by predicate.
splitWhenever
splitWhenever(callable $predicate, array $array): array
Splits an array into slices on every occurrence of a value.
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.
apply
apply(callable $fn, ?iterable $args)
Calls $fn(...$args)
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.
nthArg
nthArg(int $n): callable
Returns a function which returns its $nth argument.
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.
rearg
rearg(array $indexes, callable $f): callable
Returns a function that invokes $f with arguments rearranged by props($indexes)
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
unapply
unapply(callable $fn)
Returns fn (...$args) => $fn($args)
unary
unary(callable $fn): callable
ary(1, $fn)
useWith
useWith(callable $fn, array $transformers)
Applies each transformer function to each argument.
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.
project
project(array $props, ?iterable $collection)
Like SQL select statement.
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
camelCase
camelCase(string $s): string
Converts string to camel case.
capitalize
capitalize(string $s): string
Converts the first character of string to upper case and the remaining to lower case.
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 regular expression.
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
trim
trim(string $characters, string $string): string
Strip characters from the beginning and end of a string.
trimEnd
trimEnd(string $characters, string $string): string
Strip characters from the end of a string.
trimStart
trimStart(string $characters, string $string): string
Strip characters from the beginning of a string.
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