Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

An optional field fails Laravel validation when it is empty

ErrorThe field must be a string. (when the input was left blank)

Short answer

Laravel converts empty strings in the request to null, and a rule such as string or date then fails on null. Mark optional fields nullable so null passes and the other rules run only on real values. Use sometimes when the key may be absent, and required_with when the field depends on another.

  • Applies to Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print what validation actually receives for the blank field. If it is null, the rule list needs nullable.

    // top of the controller method
    dd($request->all());
  2. 2Match what you see, then jump to its fix

    1. 1The error shows only when the optional input is emptyBlank input becomes null and the rule rejects nullFix
    2. 2The field is sent only by some clients, for example a PATCH with a few fieldsThe key may be missing from the request entirelyFix
    3. 3Your rule says required, but it should apply only in some casesThe field is only needed when another one is filledFix

What does the error look like?

  • The field must be a string. (when the input was left blank)
  • A validation error on a field that is optional and was left empty

Cause 1 of 3

Blank input becomes null and the rule rejects null

1Check

Laravel's TrimStrings and ConvertEmptyStringsToNull middleware are in the global stack by default. The validation docs say optional fields must be marked nullable, or null counts as invalid.

grep -rn "ConvertEmptyStringsToNull" bootstrap/app.php app/Http 2>/dev/null

2Fix

Add nullable to the optional field's rules.

$request->validate([
    'title'      => 'required|max:255',
    'publish_at' => 'nullable|date',
]);

3Verify

Post the form with publish_at left blank and with a bad date, and compare the two results.

php artisan route:list --path=posts

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

The key may be missing from the request entirely

1Check

The validation docs describe the present rule (key must exist) and the filled rule (must not be empty when present). The sometimes rule runs the other rules only if the field is in the data.

dd($request->has('nickname'), $request->filled('nickname'));

2Fix

Use sometimes with the rules, or sometimes plus nullable when a present-but-empty value should pass.

'nickname' => ['sometimes', 'nullable', 'string', 'max:30'],

3Verify

Send a request without the key and one with an empty value: both pass.

curl -i -X PATCH http://localhost:8000/api/profile -H "Accept: application/json" -d ""

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

The field is only needed when another one is filled

1Check

required_with makes the field required only if any of the other listed fields are present and not empty.

grep -rn "required" app/Http/Requests | head

2Fix

Replace required with required_with, and keep nullable for the other case.

'company_vat' => ['nullable', 'required_with:company_name', 'string'],

3Verify

Send company_name alone and expect an error on company_vat, then neither and expect a pass.

php artisan test

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Decide for every field whether it is required, nullable or sometimes, and write that first in the rule list.
  • Do not remove ConvertEmptyStringsToNull to fix one field: the docs show per-request exceptions if you need them.
  • Test each optional field with a blank value and with a bad value.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.