php 49 lines · 7 steps

Serializing balance reconciliation in Laravel

A queued Laravel job that reconciles an account against Stripe while preventing concurrent runs for the same account.

Explained by highlit

Laravel Intermediate queues concurrency idempotency job-middleware retries

1<?php
2 
3namespace App\Jobs;
4 
5use App\Models\Account;
6use App\Services\StripeReconciler;
7use Illuminate\Bus\Queueable;
8use Illuminate\Contracts\Queue\ShouldQueue;
9use Illuminate\Foundation\Bus\Dispatchable;
10use Illuminate\Queue\InteractsWithQueue;
11use Illuminate\Queue\Middleware\WithoutOverlapping;
12use Illuminate\Queue\SerializesModels;
13 
14class ReconcileAccountBalance implements ShouldQueue
15{
16    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
17 
18    public int $tries = 3;
19 
20    public function __construct(public Account $account)
21    {
22    }
23 
24    public function middleware(): array
25    {
26        return [
27            (new WithoutOverlapping($this->account->id))
28                ->expireAfter(180)
29                ->releaseAfter(30)
30                ->dontRelease(),
31        ];
32    }
33 
34    public function handle(StripeReconciler $reconciler): void
35    {
36        $ledger = $reconciler->pullLedger($this->account);
37 
38        $this->account->forceFill([
39            'balance_cents' => $ledger->settledCents(),
40            'pending_cents' => $ledger->pendingCents(),
41            'reconciled_at' => now(),
42        ])->save();
43    }
44 
45    public function uniqueId(): string
46    {
47        return (string) $this->account->id;
48    }
49}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1WithoutOverlapping keyed by a stable id keeps mutually-destructive jobs from running at the same time.
2Pairing expireAfter with dontRelease avoids permanent locks while discarding redundant work instead of retrying it.
3Injecting a service into handle keeps the job thin and lets the queue container resolve dependencies for you.

Related explainers

java

public class SlidingLogRateLimiter {
 
    private final int maxRequests;
    private final long windowMillis;

How a sliding-log rate limiter works

rate-limiting concurrency sliding-window

Advanced 8 steps

package theme
 
import (
	"fmt"

Per-tenant HTML templates with Gin's renderer

multi-tenancy concurrency html-templates

Advanced 8 steps

php

<?php
 
namespace App\Http\Controllers;

Streaming a filtered CSV export in Laravel

streaming csv-export query-builder

Intermediate 9 steps

python

import time
import threading
from enum import Enum
from functools import wraps

Building a circuit breaker in Python

circuit-breaker resilience decorators

Advanced 7 steps

typescript

import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { BehaviorSubject, Observable, throwError } from 'rxjs';
import { catchError, filter, take, switchMap } from 'rxjs/operators';