Request Validation¶

LacePHP includes a simple, flexible request validator to help you enforce rules on user input. The RequestValidator class lives in lacebox/Sole/RequestValidator.php.

Helper Access¶

There isn’t a dedicated helper function, so import and grab the validator like this:

use Lacebox\Sole\RequestValidator;

$validator = RequestValidator::getInstance();

Why a Singleton? Using one instance means you can configure rules in one place and then call validate() anywhere—your rules and error state stay consistent across your controllers or services.

Defining Rules¶

First, tell the validator which fields to check and which rules to apply. You can define rules as comma-separated strings or arrays:

$validator->setRules([
    'email'    => 'required,email',
    'age'      => ['required', 'min[18]', 'max[120]'],
    'username' => 'required,custom:isAlphanumeric'
]);

Here’s what happens:

required: value must not be null or empty.
email: value must look like a valid email address.
min[18]: value (typically number or string length) must be at least 18.
max[120]: value must not exceed 120.
custom:isAlphanumeric: a user-supplied rule named isAlphanumeric (see below).

Custom Rules¶

If you have your own validation logic, register it before setRules():

$validator->setCustomRules([
    'isAlphanumeric' => new \Weave\Validators\IsAlphanumericRule(),
]);

Then you can refer to it with custom:isAlphanumeric.

First-Error Mode (“lace_break”)¶

By default, every field is checked against all its rules and all errors are collected. If you’d rather stop on the first failure per field, turn on lace_break:

$validator->lace_break();

Throwing Exceptions¶

You can choose to have the validator throw a ValidationException on failure instead of returning false. This can simplify controller code when you want to catch and handle errors:

$validator->throwOnFail();

Running Validation¶

Once you’ve configured your rules, call:

if ($validator->validate()) {
    // All good—proceed with your business logic
} else {
    // Validation failed
    $errors = $validator->errors();
    // $errors is an array: ['field1'=>['Error message'], ...]
}

Or, if you set throwOnFail(true), simply:

try {
    $validator->validate();
    // continue
} catch (\Lacebox\Sole\Validation\ValidationException $e) {
    $errors = $e->getErrors();
    // handle errors, e.g. return them in JSON
}

Inspecting Errors¶

fails() returns true if any rules failed.
errors() returns the full array of error messages per field.
first(‘email’) returns the first error message for the email field, or null if none.

Example Usage¶

Imagine a simple user-registration endpoint:

use Lacebox\Sole\RequestValidator;

class RegistrationController
{
    public function register()
    {
        $validator = RequestValidator::getInstance()
            ->throwOnFail()      // we want exceptions
            ->lace_break()        // stop at first error per field
            ->setRules([
                'email'    => 'required,email',
                'password' => 'required,min[8]',
            ]);

        try {
            $validator->validate();
        } catch (\Lacebox\Sole\Validation\ValidationException $e) {
            // return JSON errors with 422 status
            return kickback()->json([
                'errors' => $e->getErrors()
            ], 422);
        }

        $data = sole_request()->only(['email', 'password']);
        // ... create user ...
        return kickback()->json(['status'=>'success'], 201);
    }
}

Validation Syntax and Built-in Rules¶

LacePHP’s RequestValidator currently supports:

Comma-separated rule lists.
Bracket syntax for parameters, e.g. min[8].
Built-in rule names: required, email, isEven, isGreaterThan, isEqualsTo, min plus any custom rules you register.

Below is a sample code on how you can set your validation rules, either the custom one or the in-built rule.

RequestValidator::getInstance()
    ->setCustomRules([
        'captcha' => new weave\Validators\CaptchaRule()
    ])
    ->setRules([
        'email'    => 'required,email',        // comma-separated
        'password' => 'required,min[8]',       // bracket syntax
        'captcha'      => 'required,custom:captcha' // built-in + custom
    ])
    ->validate();

Built-in Rules¶

Here are the rules provided out of the box:

Rule Name	Syntax	Description
required	required	Field must not be null or empty.
email	email	Field must be a valid email address.
min	min[<number>]	Field (string length) must be at least <number> characters.
isGreaterThan	isGreaterThan[<number>]	Numeric field must be strictly greater than <number>.
isEqualsTo	isEqualsTo[<value>]	Field must equal <value>.
custom	custom:<ruleName>	Use a custom rule instance previously registered via setCustomRules().

Best Practices¶

Define rules early in your controller or a service before any side effects.
Use lace_break() if you only need the first failure for each field—for example, you don’t want multiple “required” and “email” errors for an empty email.
Register custom rules for complex or domain-specific checks (e.g. password strength, date ranges).
Handle exceptions cleanly by catching ValidationException and returning user-friendly messages (JSON or HTML).

Warning

Always validate any data that comes from the client—even if you think it’s “just” an internal tool.
Be explicit about which fields you validate—unvalidated fields can lead to unexpected behaviour or security issues.
Keep rules simple and reusable. If you find yourself repeating a rule combination, consider writing a custom rule class.

By following this pattern, you ensure your LacePHP apps remain robust, secure and easy to maintain—no matter how many inputs you need to validate.