maciejczyzewski/bottomline

A full-on PHP manipulation utility-belt that provides support for the usual functional.

0.1.1 2018-01-12 14:42 UTC

README

Bottomline logo

bottomline

Build Status PHP version

Table of Contents:

Requirements

; php.ini
extension=php_mbstring.dll

Introduction

bottomline is a PHP utility library, similar to Underscore/Lodash, that utilizes namespaces and dynamic autoloading to improve performance.

NOTE: bottomline is not currently in feature parity with Underscore/Lodash. Review the contributing section for more information.

Benchmarks

screenshot-2.png

Installation

Install bottomline as described in the methods below:

via Composer and packagist

Packagist repo

Put the require statement in your composer.json file and run composer install:

{
    "require": {
        "maciejczyzewski/bottomline": "*"
    }
}

via File Include

Put the require statement in your code:

require 'bottomline/bottomline.php';

Usage

Arrays

__::append
__::append([1, 2, 3], 4);
// >> [1, 2, 3, 4]
__::chunk

Creates an array of elements split into groups the length of size. If an array can't be split evenly, the final chunk will be the remaining elements.

__::chunk([1, 2, 3, 4, 5], 3);
// >> [[1, 2, 3], [4, 5]]
__::compact

Returns a copy of the array with falsy values removed.

__::compact([0, 1, false, 2, '', 3]);
// >> [1, 2, 3]
__::drop

Creates a slice of array with n elements dropped from the beginning.

__::drop([1, 2, 3], 2);
// >> [3]
__::flatten

Flattens a multidimensional array. If you pass shallow, the array will only be flattened a single level.

__::flatten([1, 2, [3, [4]]], true);
// >> [1, 2, 3, 4]
__::patch

Patches array with list of xpath-value pairs.

__::patch(['addr' => ['country' => 'US', 'zip' => 12345]], ['/addr/country' => 'CA', '/addr/zip' => 54321]);
// >> ['addr' => ['country' => 'CA', 'zip' => 54321]]
__::prepend
__::prepend([1, 2, 3], 4);
// >> [4, 1, 2, 3]
__::randomize

Returns shuffled array ensuring no item remains in the same position.

__::randomize(1, 2, 3, 4);
// >> [4, 3, 1, 2]
__::range

Returns an array of integers from start to stop (exclusive) by step.

__::range(1, 10, 2);
// >> [1, 3, 5, 7, 9]
__::repeat
__::repeat('foo', 3);
// >> ['foo', 'foo', 'foo']

Sequences

__::chain

__::chain([1, 2, 3, 0, null])
    ->compact()
    ->prepend(4)
    ->reduce(function($sum, $number) {
        return $sum + $number;
    }, 0)
    ->value();
// >> 10

Collections

__::assign

Combines and merge collections provided with each others. If the collections have common keys, then the last passed keys override the previous. If numerical indexes are passed, then last passed indexes override the previous.

For a recursive merge, see __::merge.

__::assign(['color' => ['favorite' => 'red', 5], 3], [10, 'color' => ['favorite' => 'green', 'blue']]);
// >> ['color' => ['favorite' => 'green', 'blue'], 10]
__::concat

Combines and concat collections provided with each others. If the collections have common keys, then the values are appended in an array. If numerical indexes are passed, then values are appended.

For a recursive concat, see __::concatDeep.

__::concat(['color' => ['favorite' => 'red', 5], 3], [10, 'color' => ['favorite' => 'green', 'blue']]);
// >> ['color' => ['favorite' => ['green'], 5, 'blue'], 3, 10]
__::concatDeep

Recursively combines and concat collections provided with each others. If the collections have common keys, then the values are appended in an array. If numerical indexes are passed, then values are appended.

For a non-recursive concat, see __::concat.

__::concatDeep(['color' => ['favorite' => 'red', 5], 3], [10, 'color' => ['favorite' => 'green', 'blue']]);
// >> ['color' => ['favorite' => ['red', 'green'], 5, 'blue'], 3, 10]
__::ease

Flattens a complex collection by mapping each ending leafs value to a key consisting of all previous indexes.

__::ease(['foo' => ['bar' => 'ter'], 'baz' => ['b', 'z']]);
// >> '['foo.bar' => 'ter', 'baz.0' => 'b', , 'baz.1' => 'z']'
__::filter

Returns the values in the collection that pass the truth test.

$a = [
    ['name' => 'fred',   'age' => 32],
    ['name' => 'maciej', 'age' => 16]
];

__::filter($a, function($n) {
    return $n['age'] > 24;
});
// >> [['name' => 'fred', 'age' => 32]]
__::first

Gets the first element of an array. Passing n returns the first n elements.

__::first([1, 2, 3, 4, 5], 2);
// >> [1, 2]
__::doForEach

Iterate over elements of the collection and invokes iteratee for each element.

__::doForEach(
    [1, 2, 3],
    function ($n) {
        print_r($n)
    }
);
// (Side effect: print numbers)
// >> 1, 2, 3
__::doForEachRight

Iterate over elements of the collection, from right to left, and invokes iteratee for each element.

__::doForEachRight(
    [1, 2, 3],
    function ($n) {
        print_r($n)
    }
);
// (Side effect: print numbers)
// >> 3, 2, 1
__::every

Checks if predicate returns truthy for all elements of collection.

__::every([true, 1, null, 'yes'], function ($v) { return is_bool($v); })
// >> false
__::every([true, false], function ($v) { return is_bool($v); })
// >> true
__::get

Get item of an array by index, aceepting nested index

__::get(['foo' => ['bar' => 'ter']], 'foo.bar');
// >> 'ter'
__::groupBy

Group an array of objects or arrays based on a given key.

$a = [
    ['name' => 'maciej',    'continent' => 'Europe'],
    ['name' => 'yoan',      'continent' => 'Europe'],
    ['name' => 'brandtley', 'continent' => 'North America'],
];

__::groupBy($a, 'continent');
// >> [
//   'Europe' => [
//     ['name' => 'maciej', 'continent' => 'Europe'],
//     ['name' => 'yoan', 'continent' => 'Europe'],
//   ],
//   'North America' => [ ['name' => 'brandtley', 'continent' => 'North America'] ]
// ]
__::has

Returns true if the collection contains the requested key.

__::has(['foo' => ['bar' => 'num'], 'foz' => 'baz'], 'foo.bar');
// >> true
__::hasKeys

Returns if $input contains all requested $keys. If $strict is true it also checks if $input exclusively contains the given $keys.

__::hasKeys(['foo' => 'bar', 'foz' => 'baz'], ['foo', 'foz']);
// >> true
__::isEmpty

Check if value is an empty array or object.

__::isEmpty([]);
// >> true
__::isEmpty(new stdClass());
// >> true
__::last

Gets the last element of an array. Passing n returns the last n elements.

__::last([1, 2, 3, 4, 5], 2);
// >> [4, 5]
__::map

Returns an array of values by mapping each in collection through the iterator.

__::map([1, 2, 3], function($n) {
    return $n * 3;
});
// >> [3, 6, 9]
__::mapKeys

Transforms the keys in a collection by running each key through the iterator

__::mapKeys(['x' => 1], function($key, $value, $collection) {
    return "{$key}_{$value}";
});
// >> ['x_1' => 1]

__::mapKeys(['x' => 1], function($key) {
    return strtoupper($key);
});
// >> ['X' => 3]

__::mapKeys(['x' => 1])
// >> ['x' => 1]
__::mapValues

Transforms the values in a collection by running each value through the iterator

__::mapValues(['x' => 1], function($value, $key, $collection) {
    return "{$key}_{$value}";
});
// >> ['x' => 'x_1']

__::mapValues(['x' => 1], function($value) {
    return $value * 3;
});
// >> ['x' => 3]

__::mapValues(['x' => 1])
// >> ['x' => 1]
__::max

Returns the maximum value from the collection. If passed an iterator, max will return max value returned by the iterator.

__::max([1, 2, 3]);
// >> 3
__::merge

Recursively combines and merge collections provided with each others. If the collections have common keys, then the last passed keys override the previous. If numerical indexes are passed, then last passed indexes override the previous.

For a non-recursive merge, see __::assign.

__::merge(['color' => ['favorite' => 'red', 'model' => 3, 5], 3], [10, 'color' => ['favorite' => 'green', 'blue']]);
// >> ['color' => ['favorite' => 'green', 'model' => 3, 'blue'], 10]
__::min

Returns the minimum value from the collection. If passed an iterator, min will return min value returned by the iterator.

__::min([1, 2, 3]);
// >> 1
__::pluck

Returns an array of values belonging to a given property of each item in a collection.

$a = [
    ['foo' => 'bar',  'bis' => 'ter' ],
    ['foo' => 'bar2', 'bis' => 'ter2'],
];

__::pluck($a, 'foo');
// >> ['bar', 'bar2']
__::reduce

Reduces a collection to a value which is the accumulator result of running each element in the collection thru an iteratee function, where each successive invocation is supplied the return value of the previous.

__::reduce([1, 2], function ($sum, $number) {
    return $sum + $number;
}, 0);
// >> 3
__::reduceRight

Reduces a collection to a value which is the accumulator result of running each element in the collection - from right to left - thru an iteratee function, where each successive invocation is supplied the return value of the previous.

__::reduceRight(['a', 'b', 'c'], function ($word, $char) {
    return $word . $char;
}, '');
// >> 'cba'
__::set

Return a new collection with the item set at index to given value. Index can be a path.

__::set(['foo' => ['bar' => 'ter']], 'foo.baz.ber', 'fer');
// >> ['foo' => ['bar' => 'ter', 'baz' => ['ber' => 'fer']]]
__::pick

Returns an array having only keys present in the given path list.

__::pick(['a' => 1, 'b' => ['c' => 3, 'd' => 4]], ['a', 'b.d']);
// → ['a' => 1, 'b' => ['d' => 4]]
__::unease

Builds a multidimensional collection out of a hash map using the key as indicator where to put the value.

__::unease(['foo.bar' => 'ter', 'baz.0' => 'b', , 'baz.1' => 'z']);
// >> ['foo' => ['bar' => 'ter'], 'baz' => ['b', 'z']]
__::where
$a = [
    ['name' => 'fred',   'age' => 32],
    ['name' => 'maciej', 'age' => 16]
];

__::where($a, ['age' => 16]);
// >> [['name' => 'maciej', 'age' => 16]]

Functions

__::slug
__::slug('Jakieś zdanie z dużą ilością obcych znaków!');
// >> 'jakies-zdanie-z-duza-iloscia-obcych-znakow'
__::truncate
$string = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque et mi orci.';
__::truncate($string);
// >> 'Lorem ipsum dolor sit amet, ...'
__::urlify
__::urlify('I love https://google.com');
// >> 'I love <a href="https://google.com">google.com</a>'

Objects

__::isArray
__::isArray([1, 2, 3]);
// >> true
__::isEmail
__::isEmail('test@test.com');
// >> true
__::isFunction
__::isFunction(function ($a) { return $a + 2; });
// >> true
__::isNull
__::isNull(null);
// >> true
__::isNumber
__::isNumber(123);
// >> true
__::isObject
__::isObject('fred');
// >> false
__::isString
__::isString('fred');
// >> true
__::isCollection

Returns true if the argument is a collection (that is an array or object).

__::isCollection([1, 2, 3]);
// >> true

Utilities

__::identity

Returns the first argument it receives

__::identity(1, 2, 3, 4)
// >> 1

__::identity()
// >> null

Strings

__::camelCase
__::camelCase('Foo Bar');
// >> 'fooBar'
__::capitalize
__::capitalize('FRED');
// >> 'Fred'
__::kebabCase
__::kebabCase('Foo Bar');
// >> 'foo-bar'
__::lowerCase
__::lowerCase('fooBar');
// >> 'foo bar'
__::lowerFirst
__::lowerFirst('Fred');
// >> 'fred'
__::snakeCase
__::snakeCase('Foo Bar');
// >> 'foo_bar'
__::split

Split a string by string.

__::split('github.com', '.');
// >> ['github', 'com']
__::startCase
__::startCase('fooBar');
// >> 'Foo Bar'
__::toLower
__::toLower('fooBar');
// >> 'foobar'
__::toUpper
__::toUpper('fooBar');
// >> 'FOOBAR'
__::upperCase
__::upperCase('fooBar');
// >> 'FOO BAR'
__::upperFirst
__::upperFirst('fred');
// >> 'Fred'
__::words
__::words('fred, barney, & pebbles');
// >> ['fred', 'barney', 'pebbles']

Contributing

Please feel free to contribute to this project! Pull requests and feature requests welcome! ✌️

To run the tests, install PHPUnit with make install-dev and run the tests with make test.

License

See LICENSE file in this repository.

Thanks