Laravel Collection Macros Laravel Package

Getting Started

Install the package with composer require spatie/laravel-collection-macros. No service provider registration is needed—Laravel auto-discovers it. Start by exploring commonly needed operations that aren’t in core Collections: grouping by models (groupByModel), case-insensitive lookups (getCaseInsensitive/hasCaseInsensitive), or concise fallback-handling (firstOrPush, ifEmpty). The README provides self-contained usage examples for each macro—begin with a few that solve your current pain points (e.g., filterMap for “map then remove nulls”, extract for destructuring lists from collections), then gradually adopt others as you notice repetitive patterns.

Implementation Patterns

• Replace conditional boilerplate with if, ifAny, ifEmpty, filterMap, or firstOrPush. For example, replace if ($items->isEmpty()) { $items->push($fetched); } with $items->firstOrPush(fn($i) => $i === $id, $fetched).
• Clean data transformations via extract for destructuring (e.g., [$title, $author] = $book->extract('title', 'author.name')), fromPairs/toPairs for pair conversions, and transpose for matrix operations.
• Grouping by Eloquent models (groupByModel) when working with related collections instead of raw groupBy('category_id').
• Control flow in chains using ifAny to conditionally log or track, or ifEmpty to seed a fallback—keep pipelines fluent.
• Robust lookups with getCaseInsensitive/hasCaseInsensitive for user input or inconsistent external APIs.
• Chunking/segmenting via chunkBy for continuous grouping (e.g., segment by state change), eachCons for sliding window operations, or sliceBefore for splitting on delimiters.

Gotchas and Tips

• Macros are added at runtime; ensure no naming conflicts with custom macros or future Laravel core additions. Prefer descriptive names if you add your own.
• Some macros like pluckMany return arrays, while others return Collections—check the return type to avoid chaining errors.
• extract uses null for missing keys (unlike only, which omits them); remember this when destructuring and strictness matters.
• Case-insensitive helpers only apply to string keys; numeric keys behave like standard get.
• firstOrPush requires explicit target collection if you want to push to the same collection and mutate—it’s not automatic. Pass the collection as the third argument.
• For nested paths, use dot notation consistently ('user.name') where supported (extract, getCaseInsensitive), but verify per-macro docs.
• Since the package is stable and infrequently updated, it’s safe to rely on, but audit breaking changes in changelog during upgrades.