Download the PHP package adhocore/underscore without Composer

adhocore/underscore

PHP underscore inspired &/or cloned from awesome _.js. A set of utilities and data manipulation helpers providing convenience functionalites to deal with array, list, hash, functions and so on in a neat elegant and OOP way. Guaranteed to save you tons of boiler plate codes when churning complex data collection.

• Zero dependency (no vendor bloat).

Installation

Requires PHP5.6 or later.

Usage and API

Although all of them are available with helper function underscore($data) or new Ahc\Underscore($data), the methods are grouped and organized in different heriarchy and classes according as their scope. This keeps it maintainable and saves from having a God class.

Contents

• Underscore
• UnderscoreFunction
• UnderscoreArray
• UnderscoreCollection
• UnderscoreBase
• HigherOrderMessage
• ArrayAccess
• Arrayizes

Underscore

constant(mixed $value): callable

Generates a function that always returns a constant value.

noop(): void

No operation!

random(int $min, int $max): int

Return a random integer between min and max (inclusive).

times(int $n, callable $fn): self

Run callable n times and create new collection.

uniqueId(string $prefix): string

Generate unique ID (unique for current go/session).

UnderscoreFunction

compose(callable $fn1, callable $fn2, ...callable|null $fn3): mixed

Returns a function that is the composition of a list of functions, each consuming the return value of the function that follows.

delay(callable $fn, int $wait): mixed

Cache the result of callback for given arguments and reuse that in subsequent call.

memoize(callable $fn): mixed

Returns a callable which when invoked caches the result for given arguments and reuses that result in subsequent calls.

throttle(callable $fn, int $wait): mixed

Returns a callable that wraps given callable which can be only invoked at most once per given $wait threshold.

UnderscoreArray

compact(): self

Get only the truthy items.

difference(array|mixed $data): self

Get the items whose value is not in given data.

findIndex(callable $fn): mixed|null

Find the first index that passes given truth test.

findLastIndex(callable $fn): mixed|null

Find the last index that passes given truth test.

first(int $n): array|mixed

Get the first n items.

flatten(): self

Gets the flattened version of multidimensional items.

indexOf(mixed $value): string|int|null

Find the first index of given value if available null otherwise.

intersection(array|mixed $data): self

Gets the items whose value is common with given data.

last(int $n): array|mixed

Get the last n items.

lastIndexOf(mixed $value): string|int|null

Find the last index of given value if available null otherwise.

object(string|null $className): self

Hydrate the items into given class or stdClass.

range(int $start, int $stop, int $step): self

Creates a new range from start to stop with given step.

sortedIndex(mixed $object, callable|string $fn): string|int|null

Gets the smallest index at which an object should be inserted so as to maintain order.

union(array|mixed $data): self

Get the union/merger of items with given data.

unique(callable|string $fn): self

Gets the unique items using the id resulted from callback.

zip(array|mixed $data): self

Group the values from data and items having same indexes together.

UnderscoreCollection

contains(mixed $item): bool

Check if the collection contains given item.

countBy(callable|string $fn): self

Count items in each group indexed by the result of callback.

each(callable $fn): self

Apply given callback to each of the items in collection.

every(callable $fn): bool

Tests if all the items pass given truth test.

filter(callable|string|null $fn): self

Find and return all the items that passes given truth test.

find(callable $fn, bool $useValue): mixed|null

Find the first item (or index) that passes given truth test.

findWhere(array $props): mixed

Get the first item that contains all the given props (matching both index and value).

groupBy(callable|string $fn): self

Group items by using the result of callback as index. The items in group will have original index intact.

indexBy(callable|string $fn): self

Reindex items by using the result of callback as new index.

invoke(callable $fn): mixed

Invoke a callback using all of the items as arguments.

map(callable $fn): self

Update the value of each items with the result of given callback.

max(callable|string|null $fn): mixed

Find the maximum value using given callback or just items.

min(callable|string|null $fn): mixed

Find the minimum value using given callback or just items.

partition(callable|string $fn): self

Separate the items into two groups: one passing given truth test and other failing.

pluck(string|int $columnKey, string|int $indexKey): self

Pluck given property from each of the items.

reduce(callable $fn, mixed $memo): mixed

Iteratively reduce the array to a single value using a callback function.

reduceRight(callable $fn, mixed $memo): mixed

Same as reduce but applies the callback from right most item first.

reject(callable $fn): self

Find and return all the items that fails given truth test.

sample(int $n): self

Get upto n items in random order.

shuffle(): self

Randomize the items keeping the indexes intact.

some(callable $fn): bool

Tests if some (at least one) of the items pass given truth test.

sortBy(callable $fn): self

Sort items by given callback and maintain indexes.

where(array $props): self

Filter only the items that contain all the given props (matching both index and value).

UnderscoreBase

_(array|mixed $data): self

A static shortcut to constructor.

__toString(): string

Stringify the underscore instance as json string.

asArray(mixed $data, bool $cast): array

Get data as array.

clon(): self

Creates a shallow copy of itself.

count(): int

Gets the count of items.

flat(array $array): array

Flatten a multi dimension array to 1 dimension.

get(string|int|null $index): mixed

Get the underlying array data by index.

getData(): array

Get data.

getIterator(): \ArrayIterator

Gets the iterator for looping.

invert(): self

Swap index and value of all the items. The values should be stringifiable.

jsonSerialize(): array

Gets the data for json serialization.

keys(): self

Get all the keys.

mixin(string $name, \Closure $fn): self

Adds a custom handler/method to instance. The handler is bound to this instance.

now(): float

The current time in millisec.

omit(array|...string|...int $index): self

Omit the items having one of the blacklisted indexes.

pairs(): self

Pair all items to use an array of index and value.

pick(array|...string|...int $index): self

Pick only the items having one of the whitelisted indexes.

tap(callable $fn): self

Invokes callback fn with clone and returns original self.

toArray(): array

Convert the data items to array.

valueOf(): string

Get string value (JSON representation) of this instance.

values(): self

Get all the values.

UnderscoreAliases

collect(callable $fn): self

Alias of map().

detect(callable $fn, bool $useValue): mixed|null

Alias of find().

drop(int $n): array|mixed

Alias of last().

foldl(callable $fn, mixed $memo): mixed

Alias of reduce().

foldr(callable $fn, mixed $memo): mixed

Alias of reduceRight().

head(int $n): array|mixed

Alias of first().

includes(): void

Alias of contains().

inject(callable $fn, mixed $memo): mixed

Alias of reduce().

select(callable|string|null $fn): self

Alias of filter().

size(): int

Alias of count().

tail(int $n): array|mixed

Alias of last().

take(int $n): array|mixed

Alias of first().

uniq(callable|string $fn): self

Alias of unique().

without(array|mixed $data): self

Alias of difference().

HigherOrderMessage

A syntatic sugar to use elegant shorthand oneliner for complex logic often wrapped in closures. See example below:

Without higher order messaging that would look like:

\ArrayAccess

Underscore instances can be treated as array:

Arrayizes

You can use this trait to arrayize all complex data.

License

MIT | © 2017-2018 | Jitendra Adhikari