Add datetime rounding for @ApiCache to improve cache hits

[Copilot]

Add @ApiCacheRoundDatetime annotation for datetime filter cache key normalization

When using datetime filters with @ApiCache, clients typically pass the current timestamp, which changes on every request and prevents cache hits. The new @ApiCacheRoundDatetime class-level annotation rounds datetime filter parameter values to a configurable precision (minute, hour, day, or year) before cache key generation, so that requests within the same time window produce identical cache keys.

Features

• New @ApiCacheRoundDatetime annotation — placed on the entity class alongside @ApiCache
• Configurable precision — minute, hour (default), day, or year
• Configurable direction — floor (default, round down) or ceil (round up)
• Automatic filter variant support — a single parameterName (e.g. "date") applies rounding to date, date[lt], date[gte], etc.
• Multiple annotations per class — one per datetime parameter
• Format-preserving — supports Unix timestamps, ISO 8601, and date-only strings; returns rounded values in the same format

Example

/**
 * @ApiCache
 * @ApiCacheRoundDatetime(parameterName="date", precision="hour")
 */
class Event extends AbstractEntity
{
    protected \DateTime $date;
}

Requests with ?date=2025-03-26T09:47:12+00:00 and ?date=2025-03-26T09:12:45+00:00 both round to 2025-03-26T09:00:00+00:00, producing the same cache key.

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.