Bag

Constructor.

Creates a list from the arguments given.

Create a bag from a variety of collections.

Takes the items and recursively converts them to Bags.

Creates a bag by using one collection for keys and another for its values.

Returns the array of items.

Returns the items recursively converting them to arrays.

Creates a new instance from the specified items.

This method is provided for derived classes to specify how a new instance should be created when constructor semantics have changed.

Returns whether an item exists for the given key.

Returns whether a key exists using path syntax to check nested data.

Example:

$bag->hasPath('foo/bar/baz')
// => true

This method does not allow for keys that contain /.

Returns whether the item is in the bag.

This uses a strict check so types must much and objects must be the same instance to match.

Returns an item by its key.

Returns an item using path syntax to retrieve nested data.

Example:

// Get the bar key of a set of nested arrays.
// This is equivalent to $data['foo']['baz']['bar'] but won't
// throw warnings for missing keys.
$bag->getPath('foo/bar/baz');

This method does not allow for keys that contain /.

Returns the number of items in this bag.

Checks whether the bag is empty.

Returns the first item in the list or null if empty.

Returns the last item in the list or null if empty.

Joins the list to a string.

Returns the sum of the values in this list.

Returns the product of the values in this list.

Returns whether the items in this bag are key/value pairs.

Note: Empty bags are not.

Returns whether the items in this bag are zero indexed and sequential.

Note: Empty bags are.

Gets the first index/key of a given item.

This uses a strict check so types must much and objects must be the same instance to match.

Gets the last index/key of a given item.

This uses a strict check so types must much and objects must be the same instance to match.

Returns the first item that matches the $predicate or null.

Returns the last item that matches the $predicate or null.

Returns the first key that matches the $predicate or null.

Returns the last key that matches the $predicate or null.

Returns a random value.

Returns a random key.

Calls the $callable to modify the items.

This allows for chain-ability with custom functionality.

The $callable is given the bag's items (array) as the first parameter and should return an iterable which is then converted to a bag. Any extra parameters passed in to this method are passed to the $callable after the items parameter.

Example with closure:

Bag::from(['red', 'blue'])
    ->call(function (array $colors) {
        $colors[] = 'green';

        return $colors;
    })
    ->join(', ');
// => "red, blue, green"

Example with function name and args:

Bag::from(['red', 'blue'])
    ->call('array_pad', 4, ''); // Assuming bag doesn't have a pad method ;)
// => Bag of ['red', 'blue', '', '']

Returns a mutable bag with the items from this bag.

Returns an immutable bag with the items from this bag.

Returns a bag with all the keys of the items.

Returns a bag with all the values of the items.

Useful for reindexing a list.

Applies the $callable to each value in the bag and returns a new bag with the items returned by the function.

Note: This differs from array_map in that the callback is passed $key first, then $value.

Applies the given function to each key in the bag and returns a new bag with the keys returned by the function and their values.

Returns a bag with the items that satisfy the $predicate.

Keys are preserved, so lists could need to be re-indexed.

Note: This differs from array_filter in that the $predicate is passed $key first, then $value.

Returns a bag with the items that do not satisfy the $predicate. The opposite of filter.

Keys are preserved, so lists could need to be re-indexed.

Returns a bag with falsely values filtered out.

Replaces items in this bag from the $collection by comparing keys and returns the result.

Returns a bag with the items replaced recursively from the $collection.

This differs from array_replace_recursive in a couple ways:

• Lists (zero indexed and sequential items) from given collection completely replace lists in this Bag.

• Null values from given collection do not replace lists or associative arrays in this Bag (they do still replace scalar values).

Returns a bag with the items from the $collection added to the items in this bag if they do not already exist by comparing keys. The opposite of replace.

Example:

Bag::from(['foo' => 'bar'])
    ->defaults(['foo' => 'other', 'hello' => 'world']);
// => Bag of ['foo' => 'bar', 'hello' => 'world']

Returns a bag with the items from the $collection recursively added to the items in this bag if they do not already exist by comparing keys. The opposite of replaceRecursive.

Returns a bag with the items merged with the given list.

Note: This should only be used for lists (zero indexed and sequential items). For associative arrays, use replace instead.

Returns a bag with a slice of $length items starting at position $offset extracted from this bag.

Partitions the items into two bags according to the $predicate.

Keys are preserved in the resulting bags.

Example:

[$trueItems, $falseItems] = $bag->partition(function ($key, $item) {
    return true; // whatever logic
});

Returns a bag with the values from a single column, identified by the $columnKey.

Optionally, an $indexKey may be provided to index the values in the returned Bag by the values from the $indexKey column.

Example:

$bag = Bag::from([
    ['id' => 10, 'name' => 'Alice'],
    ['id' => 20, 'name' => 'Bob'],
    ['id' => 30, 'name' => 'Carson'],
]);

$bag->column('name');
// => Bag of ['Alice', 'Bob', 'Carson']

$bag->column('name', 'id');
// => Bag of [10 => 'Alice', 20 => 'Bob', 30 => 'Carson']

Returns a bag with all keys exchanged with their associated values.

If a value has several occurrences, the latest key will be used as its value, and all others will be lost.

Iteratively reduce the items to a single value using the $callback function.

Returns a bag with duplicate values removed.

Returns a bag with the items split into chunks.

The last chunk may contain less items.

Example:

Bag::from([1, 2, 3, 4, 5])
    ->chunk(2);
// => Bag of [Bag of [1, 2], Bag of [3, 4], Bag of [5]]

Returns a bag with the items padded to the $size with the $value.

If size is positive then the array is padded on the right. If it's negative then on the left.

Examples:

$bag = Bag::from([1, 2]);

$bag->pad(4, null);
// => Bag of [1, 2, null, null]

$bag->pad(-4, null);
// => Bag of [null, null, 1, 2]

$bag->pad(2, null);
// => Bag of [1, 2]

Returns a bag with values mapped to the number of times they are in the bag.

Example:

Bag::from(['hello', 'world', 'world'])
    ->countValues();
// => Bag of ['hello' => 1, 'world' => 2]

Returns a bag with the items flattened.

Example:

$bag = Bag::from([[1, 2], [[3]], 4])

// Flatten one level
$bag->flatten()
// => Bag of [1, 2, [3], 4]

// Flatten all levels
$bag->flatten(INF)
// => Bag of [1, 2, 3, 4]

Returns a bag with a random number of key/value pairs.

Returns a list with a random number of keys (as values).

Returns a bag with only $keys.

$keys should be passed in as multiple parameters if possible. But if you have a list of keys they can be passed in as the first parameter. Note that if you can use PHP 5.6+ syntax, you can do pick(...$keys) which is preferred.

Example:

Bag::from([
    'a' => 'red',
    'b' => 'blue',
    'c' => 'green',
])
    ->pick('a', 'c', 'd');
// => Bag of ['a' => 'red', 'c' => 'green']

Returns a bag without $keys.

$keys should be passed in as multiple parameters if possible. But if you have a list of keys they can be passed in as the first parameter. Note that if you can use PHP 5.6+ syntax, you can do omit(...$keys) which is preferred.

Example:

Bag::from([
    'a' => 'red',
    'b' => 'blue',
    'c' => 'green',
])
    ->omit('a', 'c', 'd');
// => Bag of ['b' => 'blue']

Returns a bag without the values that are also in $collection.

The order is determined by this bag.

Example:

Bag::from(['red', 'blue', 'green'])
    ->diff(['blue', 'black']);
// => Bag of ['red', 'green']

Keys are preserved, so lists could need to be re-indexed.

Returns a bag without the values that are also in $collection based on the $iteratee function.

Example:

$bag = Bag::from([
    ['name' => 'Alice'],
    ['name' => 'Bob'],
    ['name' => 'Carson'],
]);
$itemsToRemove = [
    ['name' => 'Bob'],
    ['name' => 'Carson'],
    ['name' => 'David'],
];

// Compare each value by its 'name' property
$bag->diffBy($itemsToRemove, function ($item) {
    return $item['name'];
});
// => Bag of [
//     ['name' => 'Alice']
// ]
// Both items with name 'Bob' and 'Carson' are removed since they are also in $itemsToRemove

Keys are preserved, so lists could need to be re-indexed.

Returns a bag without the keys that are also in $collection.

The order is determined by this bag.

Example:

Bag::from([
    'a' => 'red',
    'b' => 'blue',
    'c' => 'green',
])->diffKeys([
    'b' => 'value does not matter',
    'd' => 'something',
]);
// => Bag of ['a' => 'red', 'c' => 'green']

Returns a bag without the keys that are also in $collection based on the $iteratee function.

Example:

$bag = Bag::from([
    'a' => 'red',
    'B' => 'blue',
    'c' => 'green',
]);
$itemsToRemove = [
    'b' => null,
    'C' => null,
    'D' => null,
];

// Compare each key case-insensitively
$bag->diffKeysBy($itemsToRemove, 'strtolower');
// => Bag of ['a' => 'red']
// Keys 'B' and 'c' are removed since all keys are compared after
// being lower-cased and 'b' and 'C' are also in $itemsToRemove

Returns a bag with only the values that are also in $collection.

Example:

Bag::from(['red', 'blue', 'green'])
    ->intersect(['blue', 'black']);
// => Bag of ['blue']

Keys are preserved, so lists could need to be re-indexed.

Returns a bag with only the values that are also in $collection based on the $iteratee function.

Example:

$bag = Bag::from([
    ['name' => 'Alice'],
    ['name' => 'Bob'],
    ['name' => 'Carson'],
]);
$itemsToKeep = [
    ['name' => 'Bob'],
    ['name' => 'Carson'],
    ['name' => 'David'],
];

// Compare each value by its 'name' property
$bag->intersectBy($itemsToKeep, function ($item) {
    return $item['name'];
});
// => Bag of [
//     ['name' => 'Bob']
//     ['name' => 'Carson']
// ]
// Both items with name 'Bob' and 'Carson' are kept since they are also in $itemsToKeep

Keys are preserved, so lists could need to be re-indexed.

Returns a bag with only the keys that are also in $collection.

Example:

Bag::from([
    'a' => 'red',
    'b' => 'blue',
    'c' => 'green',
])->intersectKeys([
    'b' => 'value does not matter',
    'd' => 'something',
]);
// => Bag of ['b' => 'blue']

Returns a bag with only the keys that are also in $collection based on the $iteratee function.

Example:

$bag = Bag::from([
    'a' => 'red',
    'B' => 'blue',
    'c' => 'green',
]);
$itemsToKeep = [
    'b' => null,
    'C' => null,
    'D' => null,
];

// Compare each key case-insensitively
$bag->intersectKeysBy($itemsToKeep, 'strtolower');
// => Bag of ['B' => 'blue', 'c' => 'green']
// Keys 'B' and 'c' are kept since all keys are compared after
// being lower-cased and 'b' and 'C' are also in $itemsToKeep

Returns a bag with the values sorted.

Sorting flags:

Returns a bag with the values sorted based on the $iteratee function.

Example:

$bag = Bag::from([
    ['name' => 'Bob'],
    ['name' => 'Alice'],
]);

// Sort values by "name" property
$bag->sortBy(function ($item) {
    return $item['name'];
});
// => Bag of [
//     ['name' => 'Alice']
//     ['name' => 'Bob']
// ]

Returns a bag with the values sorted with the $comparator.

Returns a bag with the keys sorted.

Sorting flags:

Returns a bag with the keys sorted based on the $iteratee function.

Example:

$bag = Bag::from([
    'blue'  => 'a',
    'red'   => 'b',
    'black' => 'c',
]);

// Sort keys by first letter
$bag->sortKeysBy(function ($key) {
    return $key[0];
});
// Bag of ['blue' => 'a', 'black' => 'c', 'red' => 'b']

Returns a bag with the keys sorted with the $comparator.

Returns a bag with the items reversed.

Returns a bag with the items shuffled.

Adds an item to the end of this bag.

Adds an item to the beginning of this bag.

Sets a item by key.

Sets a value using path syntax to set nested data.

Inner arrays will be created as needed to set the value.

Example:

// Set an item at a nested structure
$bag->setPath('foo/bar', 'color');

// Append to a list in a nested structure
$bag->get($data, 'foo/baz');
// => null
$bag->setPath('foo/baz/[]', 'a');
$bag->setPath('foo/baz/[]', 'b');
$bag->getPath('foo/baz');
// => ['a', 'b']

This function does not support keys that contain / or [] characters because these are special tokens used when traversing the data structure. A value may be appended to an existing array by using [] as the final key of a path.

Note: To set values in arrays that are in ArrayAccess objects their offsetGet() method needs to be able to return arrays by reference. See MutableBag for an example of this.

Remove all items from bag.

Removes and returns the item at the specified $key from the bag.

Removes the given item from the bag if it is found.

Removes and returns the first item in the list.

Removes and returns the last item in the list.