Form requests, custom rules and Precognition

A controller with a rule list, two custom messages, an ownership check and a phone number to tidy runs to about thirty lines before it saves anything. Move all of that into one class and the action becomes two lines, while the rules gain something they could not have in a controller: a browser can ask them about one field, after every keystroke, without saving a row.

This lesson builds that class for Pathshala’s admission form. You will see what Artisan generates and in which order its hooks run — the recorded answer is not the one most articles give — how a rule class checks an identifier that no built-in rule knows, which Laravel 13 attributes change a request’s behaviour, how a precognitive request answers a half-filled form, and where a check stops being validation and becomes authorization. Every run was recorded on Laravel 13.34.

What a form request moves out of the controller

php artisan make:request writes a class with two methods, and php artisan make:rule writes a rule with one. Both are nearly empty, and one of the two defaults is worth noticing:

from session import run

# What Artisan writes for a form request and for a rule, in a project that has neither yet.
run(
    """
php artisan make:request StoreAdmissionRequest
cat app/Http/Requests/StoreAdmissionRequest.php
php artisan make:rule Gstin
cat app/Rules/Gstin.php
""",
    app=True,
)

$ php artisan make:request StoreAdmissionRequest
   INFO  Request [app/Http/Requests/StoreAdmissionRequest.php] created successfully.
$ cat app/Http/Requests/StoreAdmissionRequest.php
<?php

namespace App\Http\Requests;

use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;

class StoreAdmissionRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return false;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            //
        ];
    }
}
$ php artisan make:rule Gstin
   INFO  Rule [app/Rules/Gstin.php] created successfully.
$ cat app/Rules/Gstin.php
<?php

namespace App\Rules;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Translation\PotentiallyTranslatedString;

class Gstin implements ValidationRule
{
    /**
     * Run the validation rule.
     *
     * @param  Closure(string, ?string=): PotentiallyTranslatedString  $fail
     */
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        //
    }
}

The generated authorize() returns false. A new form requestform request: A class holding everything about accepting one request: who may send it, the rules, the messages and the hooks. The action takes it as a parameter. refuses every caller until you decide who may send it, so the first request to a route you have just wired answers 403 rather than accepting anything. The generated rules() returns an empty array, which accepts anything, so write it before you open the class.

Filled in, the class holds everything about accepting one request: who may send it, what shape it must have, what to call its fields in a message, and the checks the rule strings cannot express:

<?php

namespace App\Http\Requests;

use App\Rules\Gstin;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
use Illuminate\Validation\Validator;

class StoreAdmissionRequest extends FormRequest
{
    /** Which hooks ran, in order, so the probe can print the order instead of describing it. */
    public static array $trace = [];

    /**
     * Who may send this request at all. Returning false ends it with a 403, before any rule runs.
     */
    public function authorize(): bool
    {
        self::$trace[] = 'authorize';

        return $this->header('X-Staff') === 'yes';
    }

    /**
     * Tidy the input before the rules read it. A parent may type a phone number with spaces.
     */
    protected function prepareForValidation(): void
    {
        self::$trace[] = 'prepareForValidation';

        $this->merge([
            'guardian_phone' => preg_replace('/\s+/', '', (string) $this->input('guardian_phone')),
        ]);
    }

    /**
     * The rule list, exactly as the controller held it before.
     */
    public function rules(): array
    {
        self::$trace[] = 'rules';

        return [
            'name' => ['required', 'string', 'max:120'],
            'born_on' => ['required', 'date_format:Y-m-d', 'before:2020-01-01'],
            'batch' => ['required', Rule::in(['morning', 'evening'])],
            'seats' => ['required', 'integer', 'between:1,3'],
            'guardian_phone' => ['required', 'regex:/^\+91[6-9]\d{9}$/'],
            'gstin' => ['nullable', new Gstin()],
        ];
    }

    /**
     * Checks the rule strings cannot express, run after the field rules.
     */
    public function after(): array
    {
        self::$trace[] = 'after';

        return [
            function (Validator $validator) {
                if ($this->input('batch') === 'morning' && $this->integer('seats') === 3) {
                    $validator->errors()->add('seats', 'The morning batch has two seats left.');
                }
            },
        ];
    }

    /**
     * Names a reader understands, used inside every message of these fields.
     */
    public function attributes(): array
    {
        return [
            'born_on' => 'date of birth',
            'guardian_phone' => "guardian's phone number",
        ];
    }

    /**
     * One sentence of our own, for the rule whose default message says nothing useful.
     */
    public function messages(): array
    {
        return [
            'guardian_phone.regex' => "The guardian's phone number must look like +919876543210.",
        ];
    }
}

The route is then a signature and two lines. Naming the class in the action is what runs the validation, because the container builds the class before the action is called:

<?php

use App\Http\Requests\StoreAdmissionRequest;
use App\Http\Requests\StoreInvoiceRequest;
use App\Http\Requests\StoreLooseInvoiceRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Storage;

// The probes are scripts with no browser, so they carry no forgery token; a real form route keeps PreventRequestForgery.

// The admission form, with its rules, its authorization and its hooks in a class of its own. The action is two
// lines, and the only data it can see is what the rules declared. Saving is a line in a file here, so that a
// precognitive request can be shown to leave nothing behind.
Route::post('/admissions', function (StoreAdmissionRequest $request) {
    Storage::disk('local')->append('admissions.log', json_encode($request->validated()));

    return response()->json(['saved' => $request->validated()], 201);
})->middleware(HandlePrecognitiveRequests::class)->withoutMiddleware(PreventRequestForgery::class);

// The same rules with and without #[FailOnUnknownFields].
Route::post('/invoices/strict', fn (StoreInvoiceRequest $request) => response()->json(['saved' => $request->validated()]))
    ->withoutMiddleware(PreventRequestForgery::class);

Route::post('/invoices/loose', fn (StoreLooseInvoiceRequest $request) => response()->json(['saved' => $request->validated()]))
    ->withoutMiddleware(PreventRequestForgery::class);

That is also why the safe thing is the natural thing to write. In a controller the easy call is $request->all(); with a form request the easy call is $request->validated(), because it is a method on the object the signature already names.

The hooks run in an order worth knowing

Four hooks carry the work before your action: prepareForValidation(), authorize(), rules() and after(). The order matters, because one of them runs for callers who are refused. The recorded probe sends three requests and prints which hooks ran for each:

from session import run

run(
    """
php order.php
""",
    app=True,
    overlay=("request-probe",),
)

$ php order.php
== a caller with no staff header
  status    403
  hooks     prepareForValidation then authorize
  message   This action is unauthorized.
== staff, with a phone typed with spaces
  status    201
  hooks     prepareForValidation then authorize then rules then after
  saved     {"name":"Meera Nair","born_on":"2016-01-05","batch":"evening","seats":"2","guardian_phone":"+919876543210"}
== staff, three seats in the morning batch
  status    422
  hooks     prepareForValidation then authorize then rules then after
  message   seats: The morning batch has two seats left.

Read the hooks line of the first block: prepareForValidation then authorize. Tidying runs before the caller is checked, and the request then answered 403 with This action is unauthorized. without running a single rule. The framework’s validateResolved() does them in that order, and the recorded run agrees with it.

The second block is a staff caller whose phone number was typed as +91 98765 43210. prepareForValidation() merged the stripped value back into the request, so the regular expression saw +919876543210 and the answer was 201 with that number in the validated data. The third block shows after(): three seats in the morning batch passed every field rule and still failed, with The morning batch has two seats left. attached to the seats field, where the reader will look for it.

after() is the right home for a check that needs something outside the payload: another field, a count, a timetable, a row. It returns an array of callables, each receiving the validator, and it runs once the field rules have been applied.

Two more hooks sit inside that order. withValidator() is called as the validator is built, before any rule is applied, which is where the next lesson adds a pixel rule for pictures only; passedValidation() runs after every rule has passed, immediately before your action. Neither changes the four above, and both are optional methods you add when you need them.

A custom rule class for an identifier of your own

India’s tax identifiers, bank codes and PIN codes have shapes no framework ships a rule for. A custom rule classcustom rule class: A class with one validate method that receives a field, its value and a fail closure, so a check the built-in rules do not cover can be reused anywhere. is one method: it receives the field name, the value and a $fail closure, and reports by calling the closure.

The number is fifteen characters, as rule 10 of the CGST Rules lays them down: two for the state code, ten for the permanent account number, two for the entity code and one checksumchecksum: A character or number computed from the rest of a value, so a single mistyped character makes the whole value inconsistent and can be caught offline. character. The class below computes that last character over the first fourteen and expects an entity number and the letter Z in the two entity places. It checks the shape with a pattern, then the checksum, and returns after each failure so a reader gets the message that fits:

<?php

namespace App\Rules;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

/**
 * A GSTIN is 15 characters: a two-digit state code, a ten-character PAN, an entity number, a fixed Z and a check
 * character (rule 10 of the CGST Rules). Those rules say that the last character is a checksum, not how it is
 * computed. This rule computes it as a Luhn mod 36 character over the first fourteen, which catches a single
 * mistyped character, and the probe builds its own numbers with the same function; before a live form refuses a
 * number somebody pasted from an invoice, check the computation against the issuer's published algorithm.
 * Either way the rule says nothing about whether the number was issued, which only the GST portal can answer.
 */
class Gstin implements ValidationRule
{
    private const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';

    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (! is_string($value) || ! preg_match('/^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$/', $value)) {
            $fail('The :attribute field must be 15 characters in the shape 22AAAAA0000A1Z5.');

            return;
        }

        if ($value[14] !== self::checkCharacter(substr($value, 0, 14))) {
            $fail('The :attribute field has a check character that does not match the rest of the number.');

            return;
        }
    }

    /**
     * The check character of the first fourteen characters: Luhn mod 36 over the base-36 values.
     */
    public static function checkCharacter(string $first14): string
    {
        $sum = 0;
        $factor = 2;

        for ($i = 13; $i >= 0; $i--) {
            $addend = $factor * strpos(self::ALPHABET, $first14[$i]);
            $factor = $factor === 2 ? 1 : 2;
            $sum += intdiv($addend, 36) + $addend % 36;
        }

        return self::ALPHABET[(36 - $sum % 36) % 36];
    }
}

The probe builds its own well-formed number — a made-up PAN, with the check character computed by the same function — and sends five candidates through the rule:

from session import run

run(
    """
php gstin.php
""",
    app=True,
    overlay=("request-probe",),
)

$ php gstin.php
the check character of 29ABCDE1234F1Z is W, so 29ABCDE1234F1ZW is well formed
== 29ABCDE1234F1ZW accepted
== 29ABCDE1234F1Z0
  The gstin field has a check character that does not match the rest of the number.
== 29ABCDE1234F1
  The gstin field must be 15 characters in the shape 22AAAAA0000A1Z5.
== GSTIN-29-ABCDE
  The gstin field must be 15 characters in the shape 22AAAAA0000A1Z5.
== 29abcde1234f1zw
  The gstin field must be 15 characters in the shape 22AAAAA0000A1Z5.

The check character of 29ABCDE1234F1Z is W, so 29ABCDE1234F1ZW is accepted. Change the last character to 0 and the answer is the checksum message. Shorten the number, or send something that is not a tax identifier at all, and the shape message comes back instead. Lower case fails the shape, because the pattern asks for capitals — if your form should accept what a parent pastes from an invoice, upper-case the value in prepareForValidation() rather than loosening the pattern.

Every number in this lesson is synthetic, built by the function on the page. Use the same habit in tests and fixtures: generate the check character rather than pasting a real identifier into a repository.

Attributes that change how a request behaves

Laravel 13 ships five PHP attributesPHP attribute: Metadata written in square brackets above a class, method or property, which the framework reads to change behaviour without a method or a property being written. for form requests, in Illuminate\Foundation\Http\Attributes: ErrorBag, FailOnUnknownFields, RedirectTo, RedirectToRoute and StopOnFirstFailure. Each replaces a property or an override people used to write by hand.

FailOnUnknownFields is the one that changes a security property, so the probe posts the same invoice payload — with one extra is_admin key — to two routes whose form requests differ only in that line:

from session import run

run(
    """
php unknown.php
""",
    app=True,
    overlay=("request-probe",),
)

$ php unknown.php
== with #[FailOnUnknownFields]
  status    422
  body      {"message":"The is admin field is prohibited.","errors":{"is_admin":["The is admin field is prohibited."]}}
== without the attribute
  status    200
  body      {"saved":{"gstin":"29ABCDE1234F1ZW","amount":"2500"}}

With the attribute the answer is 422 and The is admin field is prohibited. Without it the answer is 200, and the saved data is {"gstin":"29ABCDE1234F1ZW","amount":"2500"} — the extra key was ignored by the rules and dropped by validated(), exactly as the previous lesson showed.

Both behaviours are useful, for different callers. For a form whose fields you own, a key nobody declared is either a mistake in your own front end or somebody trying something, and refusing it turns a silent oddity into a message. For a public API whose clients age in the field, refusing unknown keys makes every client change a breaking change on the server, so the quiet filtering is the better default.

The same rules, before the parent presses submit

Live validation usually means two copies of the rules, one on the server and one in JavaScript, and two copies drift. Precognitionprecognition: Asking a route what it would answer: the middleware and the rules run and the controller does not, so a form can validate a field live against the server's own rules. keeps one copy. Its documentation draws the line at the action: the route’s middleware runs and the action’s dependencies are resolved, which is the step that validates a form request, but the action itself is never called.

Add HandlePrecognitiveRequests to the route, and a request that carries the header Precognition: true is answered by the rules alone:

The probe sends the parent’s half-filled form, then the corrected field, then the whole form, then the submit. After each one it asks the storage disk whether the action’s file exists:

from session import run

# One form, three precognitive requests and the submit itself, with the file the action writes watched after each.
run(
    """
php precognition.php
""",
    app=True,
    overlay=("request-probe",),
)

$ php precognition.php
== a precognitive request, one field, bad
  status    422
  Precognition          true
  Vary                  Precognition
  body      {"message":"The guardian's phone number must look like +919876543210.","errors":{"guardian_phone":["The guardian's phone number must look like +919876543210."]}}
  log file  no admissions.log yet
== a precognitive request, one field, good
  status    204
  Precognition          true
  Precognition-Success  true
  Vary                  Precognition
  log file  no admissions.log yet
== a precognitive request, whole form
  status    204
  Precognition          true
  Precognition-Success  true
  Vary                  Precognition
  log file  no admissions.log yet
== the submit itself
  status    201
  Vary                  Precognition
  body      {"saved":{"name":"Meera Nair","born_on":"2016-01-05","batch":"evening","seats":"2","guardian_phone":"+919876543210"}}
  log file  admissions.log has 1 line(s)

The first request names one field in a Precognition-Validate-Only header and gets 422 with that field’s message, the form request’s own sentence about the +91 shape. filterPrecognitiveRules keeps the rules whose field matches the names and drops the rest, so an empty form does not report every required box while the parent is still typing the first one. The corrected field answers 204 with Precognition-Success: true. Every precognitive answer carries Precognition: true, and every answer from the route carries Vary: Precognition, which keeps a cache from serving a precognitive answer to a real request.

The line that matters is the last one of each block. no admissions.log yet after all three precognitive requests, and admissions.log has 1 line(s) after the submit. The action never ran, and there are two places it was stopped. With Precognition-Validate-Only, an after-validation hook stops the request with 204 as soon as the named fields pass. Without that header, as in the third request, the precognition dispatcher resolves the route’s parameters — which is what validates the form request — and then stops with 204 instead of calling the closure.

Valid is not the same as allowed

A rule answers one question: is this value acceptable? A batch_id with exists:batches,id can be a real batch that belongs to another centre, another school, another city. The rule passes, and the row must still not be touched.

The test is simple. If the answer would change for a different caller sending the same payload, the question is authorization, and its answer is 403, not 422. Two of this lesson’s recorded runs were refused, one for each reason:

Put the check in authorize() when it is about the whole request, as the staff header is here, and in a policy when a particular row decides. Keeping the two apart also keeps each answer useful: a 422 tells the caller what to change, and a 403 tells them that no change to the payload will help.

A later module of this track builds gates and policies properly, with the ownership checks a real school needs. Until then, authorize() with a direct check is enough, and it is already in the right place.

Practise

Build this on your own Pathshala project, starting from the rule list you wrote in the previous lesson.

1. Run make:request StoreAdmissionRequest, move the rules in, and change the action to take the class and call validated(). Send a request before you touch authorize() and confirm the 403.
2. Add prepareForValidation() that upper-cases the tax identifier and strips spaces from the phone number, then print what rules() sees to satisfy yourself about the order.
3. Run make:rule Ifsc and write the eleven-character format check for a bank code: four letters, a zero, then six characters. Add a test with a made-up code for each branch of the rule.
4. Add #[FailOnUnknownFields], post a payload with one extra key and read the message. Decide whether you want it on your public API routes too.
5. Add HandlePrecognitiveRequests to the route and send a precognitive request with Precognition-Validate-Only naming one field. Confirm with your own counter that the action did not run.

The self-check below asks about every section of this page.

Interview questions

Warm-up: what does a form request give you that a rule list in the controller does not?

Four things, and only the first is about tidiness. It gives one place for everything about accepting that request: the rules, the messages, the attribute names, and authorize(), which answers with a 403 before any rule runs. It gives the action a parameter whose easiest method is the safe one, so validated() replaces $request->all() without anybody having to remember. It gives hooks a rule list cannot have: prepareForValidation() to shape input before the rules read it, and after() for a check that needs a count or another row. And it can be asked by a browser: with the precognition middleware on the route, the same class answers a live check field by field, so the front end never holds a second copy of the rules. The cost is a file and the discipline of writing authorize(), which starts as false for exactly that reason.

The questions below take this lesson’s class further:

Key takeaways

• make:request generates authorize() returning false, so a new form request refuses every caller until you decide who may send it.
• The hooks run as prepareForValidation(), authorize(), rules(), after(), so input is shaped even for callers who are then refused with a 403.
• A custom rule class has one method and reports through $fail; checking shape before checksum gives the reader the message that fits what is wrong.
• A checksum shows that an identifier is well formed, not that it was issued or that it belongs to the caller.
• #[FailOnUnknownFields] turns an ignored extra key into a 422, which suits a form you own and not a public API with older clients.
• A precognitive request runs the middleware and the rules but not the action: the recorded run answered 422 and then 204 with Precognition-Success: true, and wrote nothing until the real submit.