ERROR_HANDLING.md

Error Handling

← Back to Main Documentation

Navigation: Validations | Conditional Validation | Rules & Schemas | Custom Strategies | Error Handling(ERROR_HANDLING.md) | Internationalization | Benchmarks

---

DataVerify provides flexible error retrieval with detailed information about validation failures.

Table of Contents

• Quick Start
• Error Structure
• Getting Errors
• Batch vs Fail-Fast
• Custom Error Messages
• Field Aliases
• Error Formatting Examples

---

Quick Start

use Gravity\DataVerify;

$data = (object)[
    'email' => 'invalid',
    'age' => 15
];

$dv = new DataVerify($data);
$dv
    ->field('email')->required->email
    ->field('age')->required->int->between(18, 100);

if (!$dv->verify()) {
    $errors = $dv->getErrors();
    
    foreach ($errors as $error) {
        echo $error['message'] . "\n";
        // The field email must be a valid email address
        // The field age must be between 18 and 100
    }
}

---

Error Structure

Each error contains detailed information about the validation failure:

Error Array Structure

[
    'field' => 'email',           // Field name (or nested path like 'user.email')
    'alias' => 'Email Address',   // Custom display name (if set)
    'test' => 'email',            // Validation rule that failed
    'message' => 'The field Email Address must be a valid email address',
    'value' => 'invalid'          // The value that failed validation
]

Fields:

• field - The field name or nested path (user.email, address.city)
• alias - Custom display name set with ->alias(), or null
• test - Name of the validation that failed (required, email, between, etc.)
• message - Translated error message (respects current locale)
• value - The actual value that failed validation

Nested Field Paths

$data = (object)[
    'user' => (object)[
        'profile' => (object)[
            'email' => 'invalid'
        ]
    ]
];

$dv = new DataVerify($data);
$dv
    ->field('user')->required->object
        ->subfield('profile')->required->object
            ->subfield('profile', 'email')->required->email;

if (!$dv->verify()) {
    $errors = $dv->getErrors();
    echo $errors[0]['field'];  // "user.profile.email"
}

Note: Nested paths use dot notation (parent.child.grandchild)

---

Getting Errors

As Arrays (Default)

$errors = $dv->getErrors();

foreach ($errors as $error) {
    echo "{$error['field']}: {$error['message']}\n";
}

Returns: Array of associative arrays

As Objects

$errors = $dv->getErrors(asObject: true);

foreach ($errors as $error) {
    echo $error->field . ": " . $error->message . "\n";
    
    // Access properties
    $fieldName = $error->field;
    $displayName = $error->alias;
    $ruleName = $error->test;
    $message = $error->message;
    $failedValue = $error->value;
}

Returns: Array of ValidationError objects

Checking for Specific Fields

$errors = $dv->getErrors();

// Find errors for specific field
$emailErrors = array_filter($errors, fn($e) => $e['field'] === 'email');

// Check if field has errors
$hasEmailError = !empty($emailErrors);

---

Batch vs Fail-Fast

Batch Mode (Default)

Collects all validation errors before returning:

$dv = new DataVerify($data);
$dv
    ->field('email')->required->email
    ->field('age')->required->int->between(18, 100)
    ->field('name')->required->string->minLength(3);

$dv->verify();  // or verify(batch: true)

$errors = $dv->getErrors();
// Returns ALL errors from email, age, and name

Use when: You want to show users all validation issues at once

Fail-Fast Mode

Stops at the first validation error:

$dv->verify(batch: false);

$errors = $dv->getErrors();
// Returns ONLY the first error encountered

Performance: ~2x faster than batch mode (stops early)

Use when:

• You want progressive feedback
• Performance is critical
• Early exit on first failure is acceptable

---

Custom Error Messages

Per-Field Custom Messages

$dv->field('email')
    ->required
    ->email
    ->errorMessage('Please provide a valid professional email address');

// Error message: "Please provide a valid professional email address"
// (ignores default translations)

Note: Custom message applies to all validations on that field

When to Use

Use custom messages for:

• Business-specific requirements
• User-friendly explanations
• Context-specific guidance

$dv->field('corporate_email')
    ->required
    ->email
    ->regex('/@company\.com$/')
    ->errorMessage('Please use your @company.com email address');

Use translations for:

• Standard validation messages
• Multi-language support
• Consistency across application

---

Field Aliases

Setting Display Names

// Without alias
$dv->field('user_email')->required;
// Error: "The field user_email is required"

// With alias
$dv->field('user_email')->alias('Email Address')->required;
// Error: "The field Email Address is required"

Benefit: Human-friendly field names in error messages

Nested Field Aliases

$dv
    ->field('user')->required->object
        ->subfield('first_name')->alias('First Name')->required->string
        ->subfield('last_name')->alias('Last Name')->required->string;

// Errors:
// "The field First Name is required"
// "The field Last Name is required"

---

Error Formatting Examples

JSON API Response

if (!$dv->verify()) {
    return response()->json([
        'success' => false,
        'errors' => $dv->getErrors()
    ], 422);
}

// Response:
// {
//   "success": false,
//   "errors": [
//     {
//       "field": "email",
//       "alias": "Email Address",
//       "test": "email",
//       "message": "The field Email Address must be a valid email address",
//       "value": "invalid"
//     }
//   ]
// }

Grouped by Field

$errors = $dv->getErrors();

$grouped = [];
foreach ($errors as $error) {
    $field = $error['field'];
    if (!isset($grouped[$field])) {
        $grouped[$field] = [];
    }
    $grouped[$field][] = $error['message'];
}

// Result:
// [
//   'email' => ['The field email must be a valid email address'],
//   'age' => ['The field age must be between 18 and 100']
// ]

HTML Error List

$errors = $dv->getErrors();

echo '<ul class="errors">';
foreach ($errors as $error) {
    $field = htmlspecialchars($error['field']);
    $message = htmlspecialchars($error['message']);
    echo "<li data-field=\"{$field}\">{$message}</li>";
}
echo '</ul>';

Console Output

if (!$dv->verify()) {
    $errors = $dv->getErrors();
    
    echo "Validation failed:\n";
    foreach ($errors as $error) {
        echo "  ✗ {$error['field']}: {$error['message']}\n";
    }
    
    exit(1);
}

First Error Only

if (!$dv->verify()) {
    $errors = $dv->getErrors();
    $firstError = $errors[0] ?? null;
    
    if ($firstError) {
        echo "Error: " . $firstError['message'];
    }
}

---

See Also

• Internationalization - Multi-language error messages
• Validation Rules - All available validation rules
• Custom Strategies - Error messages for custom validations

---

Navigation: Validations | Conditional Validation | Rules & Schemas | Custom Strategies | Error Handling | Internationalization | Benchmarks

← Back to Main Documentation