whereBool() / orWhereBool()

Type-safe WHERE condition for boolean columns – the clean way to filter by true/false flags.

Signature

whereBool(string $column, mixed $value, string $operator = '='): self
orWhereBool(string $column, mixed $value, string $operator = '='): self

Why whereBool()?

MySQL stores boolean values as TINYINT(1) – so true is 1 and false is 0. Without a typed method you end up writing where('active', 1) and hoping nobody passes 'true', 'yes' or 2 by accident.

whereBool() only accepts the four values true, false, 1 and 0 (strict comparison). Everything else throws an exception. Internally it always sends 1 or 0 to the database.

Accepted values Sent to DB
true / 1 1
false / 0 0
'true', 'yes', 2, null … ❌ rejected – InvalidArgumentException

Basic usage

// Step by step
$db->whereBool('active', true);
$users = $db->get('users');

// Fluent
$users = $db->whereBool('active', true)->get('users');

// → SELECT * FROM users WHERE active = 1
// Filtering inactive records
// Step by step
$db->whereBool('active', false);
$inactive = $db->get('users');

// Fluent
$inactive = $db->whereBool('active', false)->get('users');

// → SELECT * FROM users WHERE active = 0

Combined with other conditions

// Step by step
$db->whereBool('active', true);
$db->whereBool('email_verified', true);
$db->whereString('role', 'editor');
$users = $db->get('users');

// Fluent
$users = $db->whereBool('active', true)
            ->whereBool('email_verified', true)
            ->whereString('role', 'editor')
            ->get('users');

// → SELECT * FROM users
//   WHERE active = 1 AND email_verified = 1 AND role = 'editor'

Using orWhereBool()

// Step by step
$db->whereBool('active', true);
$db->orWhereBool('is_admin', true);
$users = $db->get('users');

// Fluent
$users = $db->whereBool('active', true)
            ->orWhereBool('is_admin', true)
            ->get('users');

// → SELECT * FROM users WHERE active = 1 OR is_admin = 1

Validation & error handling

Any value other than true, false, 1 or 0 throws an InvalidArgumentException immediately – before the query is built. 

try {
    $db->whereBool('active', 'yes'); // ❌ not a valid boolean
    $users = $db->get('users');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage();
    // → Invalid boolean value for column 'active'
}

// These are all invalid:
$db->whereBool('active', 'true');  // ❌ string 'true'
$db->whereBool('active', 2);       // ❌ integer 2
$db->whereBool('active', null);    // ❌ null

See also

  • whereInt() – if you need to filter by TINYINT values beyond 0/1
  • whereString() – type-safe string filtering
  • where() – generic WHERE without type enforcement