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

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 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/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:

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:

return __('validate.uuid');

The package provides this translation key in 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:

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:

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:

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, 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 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 (or your target locale). The message() method in 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}