php 68 lines · 9 steps

Bucketing spending by time period in Laravel

A report class groups an account's outgoing transactions into pre-seeded time buckets, tallying totals and per-category spend.

Explained by highlit

Laravel Intermediate aggregation date-bucketing collections immutability reporting

1<?php
2 
3namespace App\Reports;
4 
5use App\Models\Transaction;
6use Carbon\CarbonImmutable;
7use Carbon\CarbonPeriod;
8use Illuminate\Support\Collection;
9 
10final class SpendingReport
11{
  public function __construct(
      private readonly int $accountId,
      private readonly CarbonImmutable $from,
      private readonly CarbonImmutable $to,
      private readonly string $interval = 'month',
  ) {
  }
19 
  public function build(): Collection
  {
      $buckets = $this->emptyBuckets();
23 
      Transaction::query()
          ->where('account_id', $this->accountId)
          ->where('amount', '<', 0)
          ->whereBetween('posted_at', [$this->from, $this->to])
          ->get(['amount', 'category', 'posted_at'])
          ->each(function (Transaction $tx) use ($buckets): void {
              $key = $this->bucketKey($tx->posted_at);
31 
              $bucket = $buckets->get($key);
              $bucket['total'] += abs($tx->amount);
              $bucket['count']++;
              $bucket['by_category'][$tx->category] =
                  ($bucket['by_category'][$tx->category] ?? 0) + abs($tx->amount);
37 
              $buckets->put($key, $bucket);
          });
40 
      return $buckets->values();
  }
43 
  private function emptyBuckets(): Collection
  {
      $step = "1 {$this->interval}";
47 
      return collect(CarbonPeriod::create($this->from, $step, $this->to))
          ->mapWithKeys(fn (CarbonImmutable $start): array => [
              $this->bucketKey($start) => [
                  'period' => $start->format('Y-m'),
                  'starts_at' => $start->toDateString(),
                  'total' => 0.0,
                  'count' => 0,
                  'by_category' => [],
              ],
          ]);
  }
59 
  private function bucketKey(CarbonImmutable $date): string
  {
      return match ($this->interval) {
          'week' => $date->format('o-\WW'),
          'year' => $date->format('Y'),
          default => $date->format('Y-m'),
      };
  }
68}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Pre-seeding empty buckets for every period guarantees gaps show up as zeros instead of missing rows.
2A single keying function shared between seeding and aggregation keeps both sides aligned by construction.
3Pushing filters into the query and folding results in one pass keeps the aggregation lean and readable.

Related explainers

php

<?php
 
class NameParser
{

Parsing a full name into components in PHP

string-parsing arrays normalization

Intermediate 8 steps

php

<?php
 
namespace App\Services\Checkout;

Validating coupons with Laravel's Pipeline

pipeline chain of responsibility transactions

Intermediate 7 steps

php

<?php
 
namespace App\Services;

How a password strength validator works in PHP

validation regular-expressions data-driven

Intermediate 8 steps

ruby

class LogAggregator
  BUCKET_FORMAT = "%Y-%m-%dT%H:%M"
 
  def initialize(entries)

Bucketing log entries by the minute in Ruby

aggregation hashing enumerable

Intermediate 5 steps

ruby

class WeeklySignupsReport
  DEFAULT_WEEKS = 12
 
  def initialize(weeks: DEFAULT_WEEKS, source: User.all)

Building a weekly signups report in Rails

service object aggregation group by

Intermediate 7 steps

php

<?php
 
namespace App\Services;

Building a cached daily leaderboard in Laravel

caching aggregation eager-loading

Intermediate 9 steps

Share this explainer

Here's the card — post it anywhere.

Bucketing spending by time period in Laravel — share card

Made with highlit — turn any snippet into a walkthrough like this in about a minute.

Explain your code