Mastering Custom Collection Methods in Laravel

Learn how to implement and leverage custom collection methods for cleaner, reusable, and domain-specific logic in Laravel applications.

Laravel's collection library is one of its most powerful and beloved features, providing a fluent, expressive API for working with arrays of data. While the base collection offers dozens of helpful methods, a truly transformative practice is creating custom collection methods. This technique allows you to encapsulate complex business logic directly onto collections of your Eloquent models, resulting in cleaner controllers, more readable code, and a more organized application architecture.

When you find yourself repeating the same complex calculations or filtering logic across different parts of your application—be it in controllers, services, or Artisan commands—it is a strong signal that your logic could be better organized. Placing this domain-specific logic in a custom collection class turns messy, procedural code into a clean, chainable, and reusable method. Instead of a controller bogged down with fifteen lines of financial calculations, you get a single, expressive method call.

This guide provides a comprehensive overview of creating and using custom collection methods in Laravel. We will explore the "why" and "when" of custom collections, walk through practical, real-world examples, and demonstrate how to implement them using both traditional methods and the new, elegant #[CollectedBy] attribute.

Why Use Custom Collection Methods?

Scattering business logic across controllers and services leads to code that is difficult to maintain, test, and understand. Custom collections solve this by providing a dedicated, domain-specific home for logic that operates on a group of models.

Key Benefits:

• Improved Readability: Complex operations are hidden behind descriptive method names. $orders->totalRevenue() is far more expressive than a long chain of map, filter, and sum calls.
• Reusability: Once defined, a custom method can be used anywhere you have a collection of that model, from API endpoints to scheduled jobs, ensuring consistency.
• Centralized Logic: Business rules related to a set of models are located in one place. If a calculation needs to be updated, you only change it once.
• Cleaner Architecture: It keeps controllers slim and focused on their primary responsibility: handling HTTP requests and returning responses. It also prevents Eloquent models from becoming bloated with static methods that operate on lists of objects.

How to Implement Custom Collections

There are two primary ways to link a custom collection class to an Eloquent model in Laravel.

1. The Traditional newCollection Method

The classic approach involves overriding the newCollection method on your Eloquent model. This method tells Laravel to use your custom collection class whenever it returns a collection of that model.

First, create your custom collection class. It should extend Illuminate\Database\Eloquent\Collection.

// app/Collections/TransactionCollection.php
namespace App\Collections;

use Illuminate\Database\Eloquent\Collection;

class TransactionCollection extends Collection
{
    // Custom methods will go here
}

Next, override the newCollection method in the corresponding Eloquent model.

// app/Models/Transaction.php
namespace App\Models;

use App\Collections\TransactionCollection;
use Illuminate\Database\Eloquent\Model;

class Transaction extends Model
{
    /**
     * Create a new Eloquent Collection instance.
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = []): TransactionCollection
    {
        return new TransactionCollection($models);
    }
}

Now, any time an Eloquent query returns a collection of Transaction models, it will be an instance of TransactionCollection, giving you access to your custom methods.

2. The Modern #[CollectedBy] Attribute

Laravel 12 introduced a more declarative and elegant way to specify a custom collection: the #[CollectedBy] attribute. This approach achieves the same result without needing to override a method.

Simply add the attribute to your Eloquent model, pointing to your custom collection class.

// app/Models/Transaction.php
namespace App\Models;

use App\Collections\TransactionCollection;
use Illuminate\Database\Eloquent\Attributes\CollectedBy;
use Illuminate\Database\Eloquent\Model;

#[CollectedBy(TransactionCollection::class)]
class Transaction extends Model
{
    // Model properties and methods
}

This modern syntax is cleaner, more readable, and the recommended approach for new Laravel applications.

Real-World Examples

Let's explore some practical scenarios where custom collections shine.

Example 1: Financial Calculations

Imagine you are building an investment portfolio application. A user has many Transaction models, and you frequently need to calculate aggregate data like the total quantity of shares, total invested capital, or the weighted average cost per share.

Placing this logic in a controller would be messy. A custom TransactionCollection is the perfect solution.

// app/Collections/TransactionCollection.php
namespace App\Collections;

use App\Models\Transaction;
use Illuminate\Database\Eloquent\Collection;

class TransactionCollection extends Collection
{
    public function totalQuantity(): float
    {
        return $this->sum('quantity');
    }

    public function totalInvestedCapital(): float
    {
        // Assuming a 'total_price' attribute on the transaction model
        return $this->sum('total_price');
    }

    public function weightedAverageCost(): float
    {
        $totalQuantity = $this->totalQuantity();

        if ($totalQuantity === 0.0) {
            return 0;
        }

        $sumOfProducts = $this->sum(function (Transaction $transaction) {
            return $transaction->quantity * $transaction->price_per_share;
        });

        return $sumOfProducts / $totalQuantity;
    }
}

Now, your controller or service logic becomes incredibly clean and expressive.

// In a service or controller
use App\Models\Transaction;

$transactions = Transaction::where('stock_id', $stockId)->get();

$holdingSummary = [
    'stock_id' => $stockId,
    'quantity' => $transactions->totalQuantity(),
    'invested_capital' => $transactions->totalInvestedCapital(),
    'average_cost' => $transactions->weightedAverageCost(),
];

The complex calculations are neatly encapsulated, making the high-level code easy to read and reason about.

Example 2: Domain-Specific Filtering

While query scopes are great for database-level filtering, sometimes you need to perform complex filtering on a collection that is already in memory. Custom collections are excellent for this.

Consider a blog application where you have a collection of Post models. You might want to filter them by whether they are published, or find all posts by a specific category.

// app/Collections/PostCollection.php
namespace App\Collections;

use Illuminate\Database\Eloquent\Collection;

class PostCollection extends Collection
{
    public function published(): self
    {
        return $this->filter->isPublished();
    }

    public function byCategory(int $categoryId): self
    {
        return $this->filter(fn ($post) => $post->category_id === $categoryId);
    }
}

// app/Models/Post.php
use App\Collections\PostCollection;
use Illuminate\Database\Eloquent\Attributes\CollectedBy;

#[CollectedBy(PostCollection::class)]
class Post extends Model
{
    protected $casts = [
        'published_at' => 'datetime',
    ];

    public function isPublished(): bool
    {
        return $this->published_at && $this->published_at->isPast();
    }
}

This allows you to perform expressive, chainable filtering on any collection of posts.

// Get all posts from the database
$posts = Post::all();

// Now filter them using custom methods
$publishedTechPosts = $posts->published()->byCategory(5);

When Should You Use Custom Collections?

Custom collections are not necessary for every model, but they are incredibly useful in specific situations. Consider creating a custom collection when:

• You perform repeated calculations on a list of models.
• The logic is domain-specific and operates on a group of objects, not a single one. For example, a single Transaction doesn't have a weighted average cost, but a collection of them does.
• You want to improve the readability of your code by giving complex operations a descriptive name.
• You find your controllers or services becoming bloated with logic that manipulates collections of models.

By moving this logic into a custom collection, you create a more organized, maintainable, and expressive application.

Conclusion

Custom collection methods are a powerful feature in Laravel for abstracting domain-specific logic away from your controllers and models. They encourage a cleaner architecture by providing a dedicated home for operations that apply to a group of objects. By creating expressive, reusable methods, you make your codebase easier to read, test, and maintain.

Whether you use the traditional newCollection method or the modern #[CollectedBy] attribute, integrating custom collections into your workflow is a significant step toward writing more professional and scalable Laravel applications. Next time you find yourself writing complex collection logic in a controller, consider if it belongs in a custom collection instead.