website/website/app/Models/TaxRate.php

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class TaxRate extends Model
{
    use HasFactory;

    protected $fillable = [
        'name',
        'country_code',
        'region_code',
        'rate',
        'type',
        'priority',
        'is_active',
    ];

    protected function casts(): array
    {
        return [
            'rate' => 'decimal:2',
            'is_active' => 'boolean',
            'priority' => 'integer',
        ];
    }

    /**
     * Scope to only active tax rates.
     */
    public function scopeActive(Builder $query): Builder
    {
        return $query->where('is_active', true);
    }

    /**
     * Scope to filter by country code.
     */
    public function scopeForCountry(Builder $query, string $code): Builder
    {
        return $query->where('country_code', strtoupper($code));
    }

    /**
     * Scope to filter by country and region.
     */
    public function scopeForRegion(Builder $query, string $country, ?string $region): Builder
    {
        $query->where('country_code', strtoupper($country));

        if ($region !== null) {
            $query->where(function (Builder $q) use ($region): void {
                $q->where('region_code', $region)
                    ->orWhereNull('region_code');
            });
        }

        return $query;
    }

    /**
     * Get applicable tax rates for a given country and optional region, ordered by priority.
     *
     * @return Collection<int, TaxRate>
     */
    public static function getApplicableRates(string $countryCode, ?string $regionCode = null): Collection
    {
        $query = static::query()
            ->active()
            ->where('country_code', strtoupper($countryCode));

        if ($regionCode !== null) {
            $query->where(function (Builder $q) use ($regionCode): void {
                $q->where('region_code', $regionCode)
                    ->orWhereNull('region_code');
            });
        } else {
            $query->whereNull('region_code');
        }

        return $query->orderBy('priority')->get();
    }
}