Getting Started

Minimal Steps

Installation

composer require splash/validator

Splash\Validator\ValidatorServiceProvider::class,

First Use Case: Validating a Form Request Extend Laravel's FormRequest to use Splash Validator:

use Splash\Validator\Facades\Validator as SplashValidator;
use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules()
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'splash:unique_user_email'],
        ];
    }

    public function withValidator($validator)
    {
        $validator->after(function ($validator) {
            SplashValidator::validateCustomRules($this->all());
        });
    }
}

Quick Validation Check Use the facade in a controller or service:

use Splash\Validator\Facades\Validator;

public function updateProfile(Request $request)
{
    $data = $request->validate([
        'profile' => ['required', 'splash:valid_profile_schema'],
    ]);

    Validator::validate($data, [
        'profile.bio' => 'max:500',
        'profile.avatar' => 'image|mimes:jpeg,png',
    ]);
}

Where to Look First

Facade: Splash\Validator\Facades\Validator – Primary entry point for validation logic.
Custom Rules: config/splash-validator.php – Predefined rules and their configurations.
Documentation: Check the README.md for rule examples and API reference.
Service Provider: Splash\Validator\ValidatorServiceProvider – Registers macros, rules, and bindings.

Implementation Patterns

Core Workflows

Declarative Rule Definition Define validation rules in a structured YAML/JSON file or directly in PHP:

// config/splash-validator/rules/connector.php
return [
    'id' => 'required|integer',
    'name' => 'required|string|max:100',
    'config' => 'required|array|splash:connector_config_schema',
];

Composable Validation for Nested Data Validate arrays/objects recursively:

Validator::validate($userData, [
    'address' => [
        'street' => 'required|string',
        'city' => 'required|string',
        'zip' => 'required|digits:5',
    ],
    'preferences' => 'splash:user_preferences_schema',
]);

Custom Rule Integration Extend core validation with domain-specific rules:

Validator::extend('splash:connector_exists', function ($attribute, $value, $parameters) {
    return Connector::where('id', $value)->exists();
});

Validation in Laravel Lifecycle
- Form Requests: Use withValidator() to inject Splash Validator.
- API Resources: Validate responses before serialization.
- Events: Validate data in listeners or observers.
```
public function handle(UserRegistered $event)
{
    Validator::validate($event->user, [
        'email_verified_at' => 'nullable|date',
    ]);
}
```

Dynamic Rule Loading Load rules from external sources (e.g., database, API):

$dynamicRules = RuleRepository::getRulesFor('user_profile');
Validator::validate($data, $dynamicRules);

Integration Tips

Leverage Laravel’s Service Container Bind custom validators as singletons for reuse:

$this->app->singleton('splash.validator.connector', function () {
    return new ConnectorValidator();
});

Error Handling Format errors consistently for APIs or forms:

try {
    Validator::validate($data, $rules);
} catch (ValidationException $e) {
    return response()->json([
        'errors' => $e->errors(),
        'status' => 'validation_failed',
    ], 422);
}

Testing Mock validators in unit tests:

$validator = Mockery::mock('Splash\Validator\Validator');
$validator->shouldReceive('validate')->once()->andReturnTrue();
$this->app->instance('splash.validator', $validator);

Performance Cache frequently used validation rules:

Cache::remember('connector_rules', now()->addHours(1), function () {
    return RuleRepository::getRulesFor('connector');
});

Gotchas and Tips

Pitfalls

Rule Conflict with Laravel’s Validator
- Issue: Splash Validator’s rules may override Laravel’s built-in rules (e.g., required, email).
- Fix: Prefix custom rules with splash: and avoid naming collisions.
```
// Avoid this:
'email' => 'email' // Laravel's rule
// Use this instead:
'email' => 'splash:valid_email_format'
```
Nested Validation Performance
- Issue: Deeply nested arrays/objects can cause timeouts or memory issues.
- Fix: Limit recursion depth or validate critical paths first.
```
Validator::validate($data, [
    'metadata' => 'splash:metadata_schema|max_depth:3',
]);
```
Database-Dependent Rules
- Issue: Rules like exists:table may fail if the database connection is unavailable.
- Fix: Use transactions or retry logic for critical validations.
```
DB::transaction(function () use ($validator) {
    $validator->validate($data, ['user_id' => 'exists:users']);
});
```

Error Message Overrides

Issue: Custom error messages may not propagate correctly.

Fix: Use Validator::extend() with custom messages:

Validator::extend('splash:connector_active', function ($attribute, $value) {
    return Connector::where('id', $value)->where('active', true)->exists();
}, 'The connector must be active.');

Configuration Quirks
- Issue: Rules defined in config/splash-validator.php may not load dynamically.
- Fix: Clear config cache after updates:
```
php artisan config:clear
```

Debugging Tips

Enable Debug Mode Set SPLASH_VALIDATOR_DEBUG=true in .env to log validation steps:
```
SPLASH_VALIDATOR_DEBUG=true
```
Inspect Validation Rules Dump loaded rules for debugging:
```
dd(Validator::getRules());
```
Validate Partial Data Use Validator::validatePartial() to test individual fields:
```
Validator::validatePartial($data, ['email' => 'splash:valid_email']);
```

Extension Points

Custom Validators Create reusable validators for domain logic:

class ConnectorValidator extends Validator
{
    public function validateConfig(array $config)
    {
        return $this->validate($config, [
            'api_key' => 'required|string',
            'timeout' => 'integer|min:1',
        ]);
    }
}

Rule Macros Add reusable rule combinations:

Validator::macro('connectorSchema', function ($attribute, $value) {
    return $this->validate($value, [
        'id' => 'required|integer',
        'name' => 'required|string',
    ]);
});

Event-Based Validation Trigger validation on model events:

User::observe(function ($user) {
    Validator::validate($user->attributes, [
        'email' => 'splash:unique_user_email',
    ]);
});

API Response Validation Validate JSON:API or GraphQL responses:

Validator::validateResponse($responseData, [
    'data' => 'required|array',
    'data.id' => 'required|string',
]);

Pro Tips

Use for Connector Validation Splash Validator excels at validating third-party connector payloads:

Validator::validate($connectorPayload, [
    'provider' => 'required|in:stripe,paypal',
    'credentials' => 'required|array|splash:provider_credentials',
]);

Dynamic Rule Loading Load rules from a database or external API:

$rules = RuleService::fetchRulesFor('user_profile');
Validator::validate($data, $rules);

Validation in Queues Offload validation to queues for long-running processes:
```
dispatch(new ValidateUserProfile($userData))->onQueue('validations');
```
Localization Support multi-language error messages:
```
Validator::setLocale('es');
```

Validator Laravel Package