whereDate() / orWhereDate() / whereDateBetween()

Type-safe WHERE conditions for date and datetime columns.

Signature

whereDate(string $column, mixed $value, string $operator = '='): self
orWhereDate(string $column, mixed $value, string $operator = '='): self

whereDateBetween(string $column, mixed $fromDate, mixed $toDate): self
orWhereDateBetween(string $column, mixed $fromDate, mixed $toDate): self

whereDateNotBetween(string $column, mixed $fromDate, mixed $toDate): self
orWhereDateNotBetween(string $column, mixed $fromDate, mixed $toDate): self

Accepted date formats

All date methods validate the value before building the query. Three formats are accepted:

Format Example Notes
Y-m-d '2025-01-15' Date only – for DATE columns
Y-m-d H:i:s '2025-01-15 14:30:00' Full datetime – for DATETIME columns
Unix timestamp (10 digits) 1736942400 Automatically converted to Y-m-d H:i:s
Formats like '15.01.2025', 'Jan 15 2025' or '2025/01/15' are not accepted and will throw an InvalidArgumentException.

whereDate() – basic usage

// Step by step
$db->whereDate('created_at', '2025-01-15');
$rows = $db->get('orders');

// Fluent
$rows = $db->whereDate('created_at', '2025-01-15')->get('orders');

// → SELECT * FROM orders WHERE created_at = '2025-01-15'

With operators

// Step by step – all orders since Jan 1st 2025
$db->whereDate('created_at', '2025-01-01', '>=');
$rows = $db->get('orders');

// Fluent
$rows = $db->whereDate('created_at', '2025-01-01', '>=')->get('orders');

// → SELECT * FROM orders WHERE created_at >= '2025-01-01'
// With Unix timestamp
$db->whereDate('created_at', 1736942400, '>=');
$rows = $db->get('orders');
// Timestamp is converted: 1736942400 → '2025-01-15 14:00:00'

// → SELECT * FROM orders WHERE created_at >= '2025-01-15 14:00:00'

whereDateBetween() – date range

Filter records within a date range (inclusive on both ends):

// Step by step
$db->whereDateBetween('created_at', '2025-01-01', '2025-01-31');
$orders = $db->get('orders');

// Fluent
$orders = $db->whereDateBetween('created_at', '2025-01-01', '2025-01-31')
             ->get('orders');

// → SELECT * FROM orders
//   WHERE created_at BETWEEN '2025-01-01' AND '2025-01-31'

whereDateNotBetween() – exclude a date range

// Step by step – exclude the maintenance window
$db->whereDateNotBetween('created_at', '2025-01-10 00:00:00', '2025-01-10 06:00:00');
$orders = $db->get('orders');

// Fluent
$orders = $db->whereDateNotBetween('created_at', '2025-01-10 00:00:00', '2025-01-10 06:00:00')
             ->get('orders');

// → SELECT * FROM orders
//   WHERE created_at NOT BETWEEN '2025-01-10 00:00:00' AND '2025-01-10 06:00:00'

OR variants

Every method has an orWhere… counterpart that works identically but uses OR:

// Step by step
$db->whereDateBetween('created_at', '2025-01-01', '2025-01-31');
$db->orWhereDateBetween('created_at', '2025-07-01', '2025-07-31');
$orders = $db->get('orders');

// Fluent
$orders = $db->whereDateBetween('created_at', '2025-01-01', '2025-01-31')
             ->orWhereDateBetween('created_at', '2025-07-01', '2025-07-31')
             ->get('orders');

// → SELECT * FROM orders
//   WHERE created_at BETWEEN '2025-01-01' AND '2025-01-31'
//   OR created_at BETWEEN '2025-07-01' AND '2025-07-31'

Validation & error handling

Any invalid date format throws an InvalidArgumentException and resets the query state.

try {
    $db->whereDate('created_at', '15.01.2025'); // ❌ wrong format
    $rows = $db->get('orders');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage();
    // → Invalid date or datetime: '15.01.2025'
}

// These are all invalid:
$db->whereDate('created_at', 'yesterday');   // ❌ relative date string
$db->whereDate('created_at', '2025-13-01'); // ❌ month 13 does not exist
$db->whereDate('created_at', null);         // ❌ non-scalar

See also