blank

Determine whether a value is blank, treating whitespace-only strings as empty.

Signature
blank(mixed $value): bool
  • Added in Laravel 5.5

Parameters

ParameterTypeDescription
$valuemixedAny value. Strings are trimmed before comparison, Countable values are measured by count, and everything else falls through to PHP's empty().

Return value

boolTrue when the value is considered blank, false otherwise.

See also

filledoptionalcollectdata_fillvalue

blank() answers the question PHP's empty() gets wrong: is there actually nothing here? It exists because empty() reports 0, '0' and false as empty, which is almost never what an application means when it validates a field.

The rules

  • null is blank.
  • Strings are trimmed first, so ' ', a tab and a newline are all blank. This is the behaviour you cannot get from empty().
  • Numbers and booleans are never blank — 0, 0.0, '0', true and false all return false.
  • Countable values — arrays, Collections, SplStack — are blank when their count is zero.
  • Stringable objects are cast to a string and trimmed.
  • Anything else falls through to empty(), so a plain object is not blank.

When to reach for it

Use it wherever user-supplied input is checked. A form field containing only spaces should count as missing; a quantity of 0 and a boolean false should not. Those three cases are exactly where empty() and !$value produce bugs.

Objects and models

An Eloquent model is never blank, even one with no attributes, so blank($user) tells you nothing useful — test the attribute instead.

Example

Try it yourself
Loading editor…
Press Run to execute the code.

When to use it

  • Reject a form field that contains only spaces while still accepting a literal 0.
  • Guard a code path when an optional Collection or array came back with no rows.
  • Decide whether to substitute a fallback for a nullable string column.

Frequently asked questions

Is blank() the same as empty()?

No. blank() trims strings first, so ' ' is blank, and it never treats 0, '0' or false as empty. Those four differences are the whole reason the helper exists.

Does blank() return true for an empty collection?

Yes — any Countable value, including Collections and arrays, is blank when its count is zero. An Eloquent model instance is never blank, however, even one with no attributes set.

Should I use blank() or filled()?

They are exact inverses, so pick whichever avoids a negation at the call site. Use blank($x) for a guard clause that returns early and filled($x) when the interesting branch is the one where a value is present.

More examples

Where empty() disagrees

Four of the eight rows disagree. The whitespace string is the case blank() catches and empty() misses; 0, '0' and false are the cases empty() over-reports and blank() correctly treats as real values.

Example · php
<?php

$cases = ['', '   ', null, 0, '0', false, [], [0]];

foreach ($cases as $case) {
    printf(
        "%-10s blank=%-5s empty=%s\n",
        var_export($case, true),
        var_export(blank($case), true),
        var_export(empty($case), true)
    );
}
/*
''         blank=true  empty=true
'   '      blank=true  empty=false
NULL       blank=true  empty=true
0          blank=false empty=true
'0'        blank=false empty=true
false      blank=false empty=true
array ( )  blank=true  empty=true
array (0)  blank=false empty=false
*/

Validating a nullable field

The '0' case is the one that breaks when the same function is written with `if (! $nickname)`. A user whose nickname is literally the character zero keeps it here.

Example · php
<?php

function displayName(?string $nickname, string $fallback): string
{
    // A nickname of "   " should fall back; a nickname of "0" should not.
    return blank($nickname) ? $fallback : trim($nickname);
}

echo displayName(null, 'anonymous'), "\n";     // anonymous
echo displayName('   ', 'anonymous'), "\n";    // anonymous
echo displayName('0', 'anonymous'), "\n";      // 0
echo displayName(' taylor ', 'anonymous'), "\n"; // taylor

Guarding on a query result

blank() reads more clearly than $invoices->isEmpty() when the same guard style is used for strings and arrays elsewhere in the codebase. Note that blank() on a single model would always be false — only the Collection is Countable. Needs a booted application.

Example · php
<?php

namespace App\Http\Controllers;

use App\Models\Invoice;

class ReportController extends Controller
{
    public function show(string $month)
    {
        $invoices = Invoice::whereMonth('issued_at', $month)->get();

        // A Collection is Countable, so blank() reports an empty result set.
        if (blank($invoices)) {
            return view('reports.empty', ['month' => $month]);
        }

        return view('reports.show', [
            'invoices' => $invoices,
            'total'    => $invoices->sum('amount'),
        ]);
    }
}

Related

helper filledhelper optionalhelper data fillhelper collect

Discussion

  • Be the first to comment on this lesson.