Download the PHP package mlg/shovel without Composer
On this page you can find all versions of the php package mlg/shovel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package shovel
Short Description A PHP library for manipulating Arrays, Strings and Objects - inspired by ramda.js
License GPL-3.0-or-later
Informations about the package shovel
Shovel
A PHP library for manipulating Arrays, Strings and Objects - inspired by ramda.js
Requirements
PHP 7.2
Install
Example
API
Array
A::of
Concatenates every argument into an array as is
See also: A::concat()
A::isArray
checks whether the given parameter is an array (returns true for both numeric and associative)
A::isAssoc
checks whether the given parameter is an associative array. empty arrays are treated as normal arrays and the function will return false for them
The method is based on this solution: https://stackoverflow.com/a/173479/1806628
A::reduce
Calls $fn with each element from left to right in the array and passes the returned value to the subsequent $fn calls
See also: A::reduceRight()
A::reverse
Flips the order of values around in an array
A::reduceRight
Calls $fn with each element from right to left in the array and passes the returned value to the subsequent $fn calls
See also: A::reduce()
A::sum
adds up the numbers in the given array and returns the sum
A::map
Calls $fn with all the elements and return the results in an array
A::keys
returns the indices of an array
See also: O::keys()
A::values
returns the values of an array
See also: O::values()
A::equals
Compares two numeric arrays and returns true when their content is the same
A::length
Returns the size of an array
A::isEmpty
Returns true when the given array has no elements inside
See also: A::isNotEmpty()
A::isNotEmpty
Returns true when the given array has elements inside
See also: A::isEmpty()
A::ensureArray
Wraps the given value into an array (even associative arrays) unless it already is
A::append
A::prepend
A::pluck
A::uniq
A::uniqByKey
A::sortBy
A::sortByKey
A::unnest
A::forEach
A::head
returns the first element of an array, or null, if empty
A::first
alias for A::head()
See also: A::head()
A::last
returns the last element of an array, or null, if empty
A::init
returns a copy of a given array without the last element
A::tail
returns a copy of a given array without the first element
A::filter
calls the given function on the elements of an array and returns every value where the function gave truthy value
A::reject
calls the given function on the elements of an array and removes every value where the function gave truthy value
A::find
calls the given function on the elements of an array and returns the value for the first match. if there's no match, it will return null
A::findLast
calls the given function on the elements of an array and returns the value for the last match. if there's no match, it will return null
A::findIndex
calls the given function on the elements of an array and returns the key for the first match. if there's no match it will return null
A::findLastIndex
calls the given function on the elements of an array and returns the key for the last match. if there's no match it will return null
A::any
calls the given predicate function on the elements in the given array and returns true if for at least one of them the predicate returns true
A::none
A::all
A::includes
A::contains
A::slice
Returns the elements of the given list from fromIndex (inclusive) to toIndex (exclusive)
A::join
A::pickRandom
selects a random item from the given array
A::concat
concatenates every argument into an array. if any of the arguments are numeric arrays, then those will get unnested
See also: A::of()
A::zipObj
A::without
removes items from the second array by values in the first array. if first value is not an array, then it is transformed into one
String
Most string operations come with an optional 3rd parameter called $caseSensitivity, which can be either
S::CASE_SENSITIVE
(default) orS::CASE_INSENSITIVE
.All string operations are multibyte safe!
S::isString
checks whether given argument is a string
S::length
counts the number of characters in the given parameter
S::isEmpty
checks whether the given string has no characters
S::isNotEmpty
checks whether the given string contains any characters
S::toLower
converts every character in a string to lowercase
S::toUpper
converts every character in a string to uppercase
S::includes
checks, if the string given as the 1st parameter is a substring of the 2nd parameter string
S::contains
alias for S::includes()
See also: S::includes
S::split
splits a string into multiple parts at points matching another string
S::splitAt
splits a string into 2 at a given position
S::equals
compares two strings together to see if they match
S::slice
copies a substring between starting(inclusive) and ending(exclusive) positions
S::startsWith
checks if the second parameter starts with the first
S::endsWith
checks if the second parameter ends with the first
S::trim
removes leading and trailing whitespaces from a string
S::replace
replaces substring with another
Object
O::isObject
check whether the passed in argument is an object
O::toPairs
gets all keys and values of an array or object and returns it as array of key-value pairs
O::pick
O::assoc
assigns value to an object via a given key. already existing keys will get overwritten
Does not work on arrays with numeric keys!
O::dissoc
removes a key from an object
Does not work on arrays with numeric keys!
O::has
checks presence of a key inside an object and an associative array
uses array_key_exists()
internally
O::keys
O::values
O::prop
Reads the given value for the given key from objects and associative arrays. If not found, then returns null.
Functions
F::complement
Wraps the passed in function in a way that when called it inverts it's returning value
Concepts
Every method is abide to the following rules ( or at least they should. if they don't, then 1) PRs are welcome, 2) Issues are welcome ):
stateless
each method should get all the necessary info from the parameters and should not rely on any external parameters or state
static
since every method is stateless, there is no need to create class instances
pure
not using anything apart from the passed in parameters
immutable
not going to change any of the parameters, no & references or stuff like that
the last parameter should be the input data you are working on...
like in Lodash FP or Ramda
except if the argument list has optional parameters!
suggestions are welcome on where to place optional parameters
not doing any validation on the parameters
if you are using a method from A
, then you better be sending it an array. PHP is a loosely typed language and you could spend all day validating input parameters.
not casting any of the input parameters
it's the same as for the validation, you should check the data you pass to the function beforehand
does only a single, well defined thing
small is beautiful, and maintainable - and probably easier to test later on when I'll get the willpower to write tests for this lib
null return values on error
when an error happens and the underlying php function returns false (eg. end or strpos), then it's being normalized to null
camelCase naming
Plain numeric arrays are handled best via the methods in A, while associative arrays and objects are handled via the methods in O.
Future plans
I keep adding methods as I come across the need for them, so if you're missing a method you'd use, then 1) PRs are welcome, 2) Issues are welcome.
If the methods are all static and stateless, then why not just write simple functions?
There are multiple functions, which have the same parameter signature, but operate with different parameter types. To avoid having to type check the parameters at every function call I've chose to namespace the functions based on the types they work on into static methods.
For example take a look at includes for both Arrays and Strings. Their implementation is relative simple, because their types are expected to be arrays and strings respectively (type hinting will come soon).
If I were to have a single, combined includes
function, then I would have to do type checking every time and it would make the code unnecessarily noisy.
Plus, sometimes the function name I would like to use is already taken by PHP, like in the case of S::split
Credits
https://www.geeksforgeeks.org/php-startswith-and-endswith-functions/ - used for S::startsWith() and S::endsWith()
https://stackoverflow.com/a/173479/1806628 - used for A::isAssoc()
https://www.php.net/manual/en/function.array-unique.php#116302 - used for A::uniqByKey()