pulli/laravel-collection-macros

Package for some custom collection macros.

Maintainers

Details

github.com/the-pulli/laravel-collection-macros

Homepage

Source

Issues

Fund package maintenance!
the-pulli

Installs: 292

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/pulli/laravel-collection-macros

v1.4.0 2026-01-25 12:31 UTC

Requires

Requires (Dev)

MIT 9ef912628ea1971eb82d4cd77e80f3dd0968c0df

  • PuLLi <the.woop@pulli.dev>

laravelmacroscollection-macros

This package is auto-updated.

Last update: 2026-01-25 12:32:00 UTC

README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status PHPStan codecov Total Downloads

Contains some handy collection macros.

Installation

You can install the package via composer:

composer require pulli/laravel-collection-macros

You can publish the service provider via:

php artisan vendor:publish --tag="pulli-collection-macros-provider"

You can publish the config file with:

php artisan vendor:publish --tag="pulli-collection-macros-config"

This is the contents of the published config file:

return [
    'auto-update' => true,
];

Usage

Macros

compareCount

Compares the count of the collection with another countable and optionally zips them together. Throws an InvalidArgumentException if counts don't match.

compareCount(mixed $countable, bool $shouldZip = true): Collection
Parameter Type Default Description
$countable mixed required An array, Countable, or object with count() method
$shouldZip bool true When true, returns zipped collection; when false, returns original 
$collection = Collection::make(['a', 'b'])->compareCount([1, 2]);
// returns [['a', 1], ['b', 2]]

$collection = Collection::make(['a', 'b'])->compareCount([1, 2], shouldZip: false);
// returns ['a', 'b']

Collection::make(['a', 'b'])->compareCount([1, 2, 3]);
// throws InvalidArgumentException: Count of input mismatch with given collection.

even

Filters the collection to only integer values and returns the even ones.

even(bool $preserveKeys = false): Collection
Parameter Type Default Description
$preserveKeys bool false Whether to preserve original array keys 
$collection = Collection::range(0, 6)->even();
// returns [0, 2, 4, 6]

$collection = Collection::range(0, 6)->even(preserveKeys: true);
// returns [0 => 0, 2 => 2, 4 => 4, 6 => 6]

explode

Creates a collection from an exploded string. Uses the same signature as PHP's native explode() function.

Collection::explode(string $separator, string $string, int $limit = PHP_INT_MAX): Collection
Parameter Type Default Description
$separator string required The delimiter string
$string string required The input string to split
$limit int PHP_INT_MAX Maximum number of elements 
$collection = Collection::explode(';', 'Twenty;Banana;Boats');
// returns ['Twenty', 'Banana', 'Boats']

$collection = Collection::explode(';', 'Twenty;Banana;Boats', 2);
// returns ['Twenty', 'Banana;Boats']

$collection = Collection::explode(';', 'Twenty;Banana;Boats', -1);
// returns ['Twenty', 'Banana']

firstAndLast

Returns the first and last element of the collection as an array.

firstAndLast(
    ?callable $first = null,
    mixed $firstDefault = null,
    ?callable $last = null,
    mixed $lastDefault = null
): array
Parameter Type Default Description
$first callable|null null Optional callback to find the first element
$firstDefault mixed null Default value if first element not found
$last callable|null null Optional callback to find the last element
$lastDefault mixed null Default value if last element not found 
[$first, $last] = Collection::make(['Jane', 'John', 'Joe'])->firstAndLast();
// $first = 'Jane', $last = 'Joe'

[$first, $last] = Collection::range(0, 6)->firstAndLast(
    first: fn ($value) => $value > 0,
    last: fn ($value) => $value < 6,
);
// $first = 1, $last = 5

firstAndLastKey

Returns the first and last key of the collection as an array.

firstAndLastKey(
    ?callable $first = null,
    mixed $firstDefault = null,
    ?callable $last = null,
    mixed $lastDefault = null
): array
Parameter Type Default Description
$first callable|null null Optional callback to find the first key
$firstDefault mixed null Default value if first key not found
$last callable|null null Optional callback to find the last key
$lastDefault mixed null Default value if last key not found 
[$first, $last] = Collection::make(['Jane', 'John', 'Joe'])->firstAndLastKey();
// $first = 0, $last = 2

[$first, $last] = Collection::range(0, 6)->firstAndLastKey(
    first: fn ($value) => $value > 0,
    last: fn ($value) => $value < 6,
);
// $first = 1, $last = 5

implodeToStringable

Implodes the collection and returns it as a Stringable object.

implodeToStringable(callable|string|null $value, ?string $glue = null): Stringable
Parameter Type Default Description
$value callable|string|null required The key to implode or a callback
$glue string|null null The glue string between elements 
$stringable = Collection::make(['Jane', 'John'])->implodeToStringable(', ');
// Stringable of "Jane, John"

$stringable = Collection::make([
    ['name' => 'Jane'],
    ['name' => 'John'],
])->implodeToStringable('name', ', ');
// Stringable of "Jane, John"

joinToStringable

Joins the collection and returns it as a Stringable object.

joinToStringable(string $glue, string $finalGlue = ''): Stringable
Parameter Type Default Description
$glue string required The glue string between elements
$finalGlue string '' The glue string before the last element 
$stringable = Collection::make(['Jane', 'John', 'Jack'])->joinToStringable(', ');
// Stringable of "Jane, John, Jack"

$stringable = Collection::make(['Jane', 'John', 'Jack'])->joinToStringable(', ', ' and ');
// Stringable of "Jane, John and Jack"

mapToCollection

Recursively maps all arrays/objects to nested Collection objects.

mapToCollection(array $ary = [], bool $deep = false): Collection
Parameter Type Default Description
$ary array [] Additional array to merge
$deep bool false When true, also converts Arrayable objects recursively 
$collection = Collection::make([['test' => 1], 2, 3])->mapToCollection();
$collection->get(0)->get('test'); // returns 1

// With additional data to merge
$collection = Collection::make([['a' => 1]])->mapToCollection(['b' => 2]);

// With deep conversion of Arrayable objects
$collection = Collection::make([$item1, $item2])->mapToCollection(deep: true);

mapToCollectionFrom

Static method to recursively map all arrays/objects to nested Collection objects.

Collection::mapToCollectionFrom(array $ary, bool $deep = false, int $maxDepth = 512): Collection
Parameter Type Default Description
$ary array required The array to convert
$deep bool false When true, also converts Arrayable objects recursively
$maxDepth int 512 Maximum recursion depth to prevent stack overflow 
$collection = Collection::mapToCollectionFrom([['test' => 1], 2, 3]);
$collection->get(0)->get('test'); // returns 1

// With deep conversion of Arrayable objects
$collection = Collection::mapToCollectionFrom([$item1, $item2], deep: true);

odd

Filters the collection to only integer values and returns the odd ones.

odd(bool $preserveKeys = false): Collection
Parameter Type Default Description
$preserveKeys bool false Whether to preserve original array keys 
$collection = Collection::range(0, 6)->odd();
// returns [1, 3, 5]

$collection = Collection::range(0, 6)->odd(preserveKeys: true);
// returns [1 => 1, 3 => 3, 5 => 5]

onlyInts

Filters the collection to only integer values.

onlyInts(bool $preserveKeys = false): Collection
Parameter Type Default Description
$preserveKeys bool false Whether to preserve original array keys 
$collection = Collection::make([0, 'Donkey Kong', 6, new stdClass])->onlyInts();
// returns [0, 6]

$collection = Collection::make([0, 'Donkey Kong', 6, new stdClass])->onlyInts(preserveKeys: true);
// returns [0 => 0, 2 => 6]

$collection = Collection::make([-5, 1.5, 3, '4'])->onlyInts();
// returns [-5, 3] (floats and numeric strings are excluded)

onlyStrings

Filters the collection to only string values, optionally converting Stringable objects.

onlyStrings(bool $strict = false, bool $preserveKeys = false): Collection
Parameter Type Default Description
$strict bool false When true, only accepts native strings; when false, also converts Stringable objects
$preserveKeys bool false Whether to preserve original array keys 
$collection = Collection::make([0, 'Donkey Kong', 6, 'Bananas'])->onlyStrings();
// returns ['Donkey Kong', 'Bananas']

// With Stringable objects (non-strict mode converts them)
$collection = Collection::make(['Hello', new StringableObject()])->onlyStrings();
// returns ['Hello', 'StringableValue']

// Strict mode rejects Stringable objects
$collection = Collection::make(['Hello', new StringableObject()])->onlyStrings(strict: true);
// returns ['Hello']

// Preserve original keys
$collection = Collection::make(['a' => 'Hello', 'b' => 123, 'c' => 'World'])
    ->onlyStrings(preserveKeys: true);
// returns ['a' => 'Hello', 'c' => 'World']

positive

Returns true if the collection is not empty (has at least one element).

positive(): bool
Collection::make([1, 2, 3])->positive(); // returns true
Collection::make()->positive();          // returns false

recursiveToArray

Recursively converts all nested objects with toArray() to arrays.

recursiveToArray(array $ary = []): array
Parameter Type Default Description
$ary array [] Additional array to merge 
// Objects with toArray() method are recursively converted
$array = Collection::make(['item1' => $object1, 'item2' => $object2])->recursiveToArray();

// With additional data to merge
$array = Collection::make(['a' => $object])->recursiveToArray(['b' => $object2]);

recursiveToArrayFrom

Static method to recursively convert all nested objects with toArray() to arrays.

Collection::recursiveToArrayFrom(array $ary, int $maxDepth = 512): array
Parameter Type Default Description
$ary array required The array to convert
$maxDepth int 512 Maximum recursion depth to prevent stack overflow 
// Objects with toArray() method are recursively converted
$array = Collection::recursiveToArrayFrom(['item1' => $object1, 'item2' => $object2]);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.