[12.x] Introduce ScopeAwareRule contract to provide relative contextual array item data to validation rules

[lucasacoutinho]

When writing custom validation rules for array items, accessing sibling data requires manual path manipulation. Consider an API for bulk order creation:

{
    "orders": [
        {
            "customer_id": 123,
            "items": [
                {
                    "product_id": 1,
                    "quantity": 10,
                    "unit_price": 150.00,
                    "discount": 2000.00
                }
            ]
        }
    ]
}

To validate that discount doesn't exceed the line total (quantity x unit_price), you currently need:

class DiscountMustNotExceedLineTotal implements ValidationRule, DataAwareRule
{
    protected array $data = [];

    public function setData(array $data): static
    {
        $this->data = $data;
        return $this;
    }

    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        // $attribute = "orders.0.items.1.discount"
        // Need to extract indices and navigate the nested structure
        preg_match('/^orders\.(\d+)\.items\.(\d+)\./', $attribute, $matches);
        $orderIndex = $matches[1] ?? null;
        $itemIndex = $matches[2] ?? null;

        if ($orderIndex === null || $itemIndex === null) {
            return;
        }

        $item = $this->data['orders'][$orderIndex]['items'][$itemIndex] ?? [];
        $lineTotal = ($item['quantity'] ?? 0) * ($item['unit_price'] ?? 0);

        if ($value > $lineTotal) {
            $fail("The discount cannot exceed the line total of {$lineTotal}.");
        }
    }
}

We could make the experience much nicer with a new and more limited ScopeAwareRule interface that automatically receives the current array item's data:

class DiscountMustNotExceedLineTotal implements ValidationRule, ScopeAwareRule
{
    protected array $scope = [];

    public function setScope(array $scope): static
    {
        $this->scope = $scope;
        return $this;
    }

    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $lineTotal = ($this->scope['quantity'] ?? 0) * ($this->scope['unit_price'] ?? 0);

        if ($value > $lineTotal) {
            $fail("The discount cannot exceed the line total of {$lineTotal}.");
        }
    }
}