feat: add Query Builder date helpers

[memleakd]

Description

This proposes adding a small set of Query Builder helpers for filtering by parts of a date/datetime column:

$builder->whereDate('created_at', '2026-01-31');
$builder->whereYear('created_at', 2026);
$builder->whereMonth('created_at', 1);
$builder->whereDay('created_at', 31);

The matching OR variants are included as well: orWhereDate(), orWhereYear(), orWhereMonth(), and orWhereDay().

The main goal is to make a common query easier to write without asking users to remember the right SQL function for each database driver. The builder compiles the expression for the active driver, while still binding values and protecting identifiers by default.

A few details are documented explicitly:

• supported comparison operators can be added to the field name, like whereDate('created_at >=', '2026-01-01')
• null values use IS NULL / IS NOT NULL
• arrays and subqueries are not accepted for these helpers
• for large indexed timestamp columns, a range condition may still be more efficient

Tests cover the shared builder behavior, driver-specific SQL output, invalid inputs, DateTimeInterface values, grouped/or conditions, aliases before from(), and a live database query.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[patel-vansh]

Overall, this feature can be handy. Looks good. Thanks

[github-actions]

👋 Hi, @memleakd!

We detected conflicts in your PR against the base branch 🙊
You may want to sync 🔄 your branch with upstream!

Ref: Syncing Your Branch

[michalsn]

I was thinking about this for some time, and I'm not convinced the new whereDate() method should be added.

If users pass 2026-06-21 12:34:56, we either have to strip the time part silently or accept cross-driver differences. On top of that, the generated SQL wraps the column in date functions/casts like DATE(), CAST(... AS DATE), or EXTRACT(), which prevents use of a normal index on the datetime column.

Of course, we can document these limitations, but for real datetime columns, an explicit range condition is often clearer and more performant. And with whereBetween(), this is now easier to apply than before.

I think this method may be tempting to use in cases where it has the biggest drawbacks.

[memleakd]

Thanks, I think you’re right. I don’t want to add something that looks convenient but may lead people toward the wrong query shape.

I’m fine with closing this PR. Or, if you think it would still be useful, I can turn it into a small docs update showing the safer range-based approach.

[michalsn]

In theory, we could implement whereDate() and whereYear() as range-based predicates instead of wrapping the column in date functions. That would keep the common cases index-friendly.

whereMonth() and whereDay() could stay as date-part extraction helpers, but the user guide would need to clearly explain that they behave differently and won’t use normal indexes because they require functions like MONTH(), DAY(), or EXTRACT().

My concern is that this adds quite a bit of complexity to an already bloated Builder class. The implementation would need careful operator handling: = becomes >= start AND < end, <= becomes < end, > becomes >= end, and != needs a grouped col < start OR col >= end. So I'm still not sure if this is worth the extra complexity.