maciejczyzewski/bottomline

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

0.1.0 2017-09-23 18:35 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]
__::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']

Chaining

coming soon...

Collections

__::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]
__::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'] ]
// ]
__::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
__::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
__::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
__::set

Set item of an array by index to given value, accepting nested index

__::set(['foo' => ['bar' => 'ter']], 'foo.baz.ber', 'fer');
// >> ['foo' => ['bar' => 'ter', 'baz' => ['ber' => 'fer']]]
__::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

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'
__::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