# How to Validate UUIDs with the Laravel-Validate Package: Complete Guide to ValidUuid

> Learn to validate UUIDs in Laravel using the milwad-dev laravel-validate package. This guide explains the ValidUuid rule for robust canonical format validation with clear error messages.

- Repository: [Milwad Khosravi/laravel-validate](https://github.com/milwad-dev/laravel-validate)
- Tags: how-to-guide
- Published: 2026-03-07

---

**The ValidUuid rule in the milwad-dev/laravel-validate package implements Laravel's Rule contract to validate canonical UUID formats using regex, returning translatable error messages via the validate.uuid localization key.**

Validating UUIDs in Laravel applications requires strict format checking to ensure data integrity across distributed systems. The **laravel-validate** package by milwad-dev provides a dedicated **ValidUuid** rule that plugs directly into Laravel's native validation system without requiring custom regex in your controllers. This article examines the source code implementation in [`src/Rules/ValidUuid.php`](https://github.com/milwad-dev/laravel-validate/blob/main/src/Rules/ValidUuid.php) and demonstrates practical usage patterns for validating 128-bit universally unique identifiers.

## Understanding the ValidUuid Rule Architecture

The **ValidUuid** class extends Laravel's validation infrastructure through the `Illuminate\Contracts\Validation\Rule` contract, as defined in [[`src/Rules/ValidUuid.php`](https://github.com/milwad-dev/laravel-validate/blob/main/src/Rules/ValidUuid.php)](https://github.com/milwad-dev/laravel-validate/blob/1.x/src/Rules/ValidUuid.php#L7-L8). This implementation allows the rule to integrate seamlessly with both inline validators and Form Request classes while maintaining a tiny, self-contained footprint.

### The passes() Method and UUID Regex Validation

The core validation logic resides in the `passes()` method, which receives the attribute name and value under validation. According to the source code at line 14, the method employs a strict regular expression matching the canonical UUID structure:

```php
return preg_match(
    '/^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/',
    $value
);

```

This regex enforces the standard 8-4-4-4-12 hexadecimal character format, ensuring the value contains exactly 32 hex digits grouped by hyphens. The word boundaries (`\b`) prevent partial matches within larger strings.

### Localized Error Messages via message()

When validation fails, the `message()` method returns a localized string using Laravel's translation helper. As implemented in lines 22-23 of [`ValidUuid.php`](https://github.com/milwad-dev/laravel-validate/blob/main/ValidUuid.php):

```php
return __('validate.uuid');

```

The package provides this translation key in [`lang/en/validate.php`](https://github.com/milwad-dev/laravel-validate/blob/main/lang/en/validate.php), allowing developers to customize error messages per locale without modifying the rule class.

## How to Use ValidUuid in Your Laravel Application

You can apply the **ValidUuid** rule through multiple patterns depending on your architecture preferences.

### Inline Validation in Controllers

For quick validation within controller methods, instantiate the rule directly in your validation array:

```php
use Milwad\LaravelValidate\Rules\ValidUuid;

$validator = validator($request->all(), [
    'order_id' => ['required', new ValidUuid()],
]);

if ($validator->fails()) {
    return back()->withErrors($validator);
}

```

This approach validates that `order_id` conforms to the UUID format (e.g., `123e4567-e89b-12d3-a456-426655440000`) before processing.

### Form Request Classes

For cleaner controllers, integrate the rule into dedicated Form Request classes:

```php
use Milwad\LaravelValidate\Rules\ValidUuid;

class StoreOrderRequest extends \Illuminate\Foundation\Http\FormRequest
{
    public function rules(): array
    {
        return [
            'order_id' => ['required', new ValidUuid()],
        ];
    }
}

```

Laravel automatically resolves this request class and applies the UUID validation when injected into controller methods.

### Programmatic Validation Outside Requests

The rule also supports direct instantiation for model observers or service classes:

```php
public static function boot()
{
    static::creating(function ($model) {
        $rule = new ValidUuid();
        if (! $rule->passes('uuid', $model->uuid)) {
            throw new \InvalidArgumentException($rule->message());
        }
    });
}

```

## Configuration and Customization

The **laravel-validate** package registers its rules through [`config/laravel-validate.php`](https://github.com/milwad-dev/laravel-validate/blob/main/config/laravel-validate.php), which handles localization settings and rule registration. To customize the error message, publish the package's language files and modify the `validate.uuid` entry in your preferred locale directory.

## Summary

- The **ValidUuid** rule in [`src/Rules/ValidUuid.php`](https://github.com/milwad-dev/laravel-validate/blob/main/src/Rules/ValidUuid.php) implements `Illuminate\Contracts\Validation\Rule` for native Laravel integration.
- The `passes()` method uses regex `/^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/` to enforce canonical UUID format.
- Error messages are translatable via the `validate.uuid` key defined in the package's language files.
- The rule supports inline validators, Form Request classes, and direct programmatic usage.

## Frequently Asked Questions

### What UUID versions does the laravel-validate package support?

The **ValidUuid** rule validates the canonical UUID format (8-4-4-4-12 hex pattern) without version-specific restrictions. It accepts any valid UUID string regardless of version (1, 4, 7, etc.), making it compatible with all RFC 4122 compliant identifiers.

### How do I customize the error message for UUID validation failures?

Publish the package's translation files and modify the `validate.uuid` key in [`lang/en/validate.php`](https://github.com/milwad-dev/laravel-validate/blob/main/lang/en/validate.php) (or your target locale). The `message()` method in [`src/Rules/ValidUuid.php`](https://github.com/milwad-dev/laravel-validate/blob/main/src/Rules/ValidUuid.php) automatically pulls from this key using Laravel's `__()` helper function.

### Can I use ValidUuid with Laravel's Validator facade instead of instantiating the class?

Yes, while the package primarily supports object-based validation using `new ValidUuid()`, you can also use it within the Validator facade's array syntax. The rule integrates seamlessly with Laravel's native validation system as implemented in [`src/Rules/ValidUuid.php`](https://github.com/milwad-dev/laravel-validate/blob/main/src/Rules/ValidUuid.php).

### Does the regex in ValidUuid.php handle uppercase and lowercase hex characters?

Yes, the regex pattern at line 14 uses the `[0-9a-fA-F]` character class, explicitly accepting both uppercase and lowercase hexadecimal digits to ensure case-insensitive UUID validation.