Monthly usage metering with automatic reset

<?php

namespace App\Billing;

use Illuminate\Support\Facades\DB;

final class UsageMeter
{
    /** Period key; a new month means a fresh row, so there is nothing to reset. */
    public static function period(): string
    {
        return now()->utc()->format('Y-m');
    }

    /** Take $units if the limit allows it. A null limit means unlimited. */
    public static function consume(int $teamId, string $metric, int $units = 1, ?int $limit = null): bool
    {
        $key = ['team_id' => $teamId, 'metric' => $metric, 'period' => self::period()];

        // The unique index makes this safe when two requests start a month together.
        DB::table('usage_counters')->insertOrIgnore($key + ['used' => 0, 'updated_at' => now()]);

        $query = DB::table('usage_counters')->where($key);

        if ($limit !== null) {
            $query->whereRaw('used + ? <= ?', [$units, $limit]);
        }

        // Check and increment are one statement, so the last unit goes to exactly one caller.
        return $query->update(['used' => DB::raw('used + '.(int) $units), 'updated_at' => now()]) > 0;
    }

    public static function used(int $teamId, string $metric): int
    {
        return (int) DB::table('usage_counters')
            ->where(['team_id' => $teamId, 'metric' => $metric, 'period' => self::period()])
            ->value('used');
    }
}

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('usage_counters', function (Blueprint $table) {
            $table->id();
            $table->foreignId('team_id')->constrained()->cascadeOnDelete();
            $table->string('metric', 40);
            $table->string('period', 7); // e.g. 2025-06
            $table->unsignedBigInteger('used')->default(0);
            $table->timestamp('updated_at')->nullable();
            $table->unique(['team_id', 'metric', 'period']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('usage_counters');
    }
};