CkDateException
What CkDate throws — only when asked.
Raised by any CkDate method called with
throwIfInvalid: true when neither the value nor the fallback can be used. Never
thrown otherwise: by default those methods answer their fallback — or the year-one
sentinel — instead. The OrNull siblings cannot raise it at all: they take no
throwIfInvalid and never throw — null is their answer for any error. final,
and derived from CkException.
The message names the method, shows the value with its type, says what it was meant to be and why it failed:
CkDate.ToCarbon: cannot use "31/12/2026" (String) as a moment in time — not a date in month-first order.
Properties
| Property | Type | What it holds |
|---|---|---|
Expected |
string |
What the value was meant to be. "a moment in time" from the methods that answer or write a moment — ToCarbon, Iso8601, Format, Unix, AddHours, AddMinutes, AddSeconds, StartOfDay, StartOfNextDay — and "a date" from the methods that answer or compare a day, ToCarbonDay and the rest. Where a method reads more than one value it names the one that failed: "a birth date", "an as-of date", "the other date", "the first date", "the second date", "the lower bound", "the upper bound". The odd ones out say what they check: "a time of day" (IsTime), "ISO 8601 date text" (IsIso8601), "a year or a date" (IsLeapYear), "an output format" (Format told no into), "a time zone" (InZone told a blank one) and "two dates that can be counted between" (WeekdaysBetween, when a holiday in its list cannot be read). A zone or assumeZone id the library does not know is never the reason: it counts as UTC. |
Input |
mixed |
From CkException: the value that failed, untouched. |
Reason |
string |
From CkException: why, in a few words. |
Quick look
use SafeCoder\CommonKit\CkDate;
use SafeCoder\CommonKit\Exceptions\CkDateException;
try {
// day 31 cannot be a month, so month-first reading fails
CkDate::ToCarbon(
input: '31/12/2026',
throwIfInvalid: true
);
} catch (CkDateException $error) {
echo $error->Reason; // -> 'not a date in month-first order'
echo $error->Expected; // -> 'a moment in time'
}
CkDate::ToCarbonDay(
input: '31/12/2026',
throwIfInvalid: true
); // throws CkDateException (the same reason, and Expected says "a date": a day was asked for)
CkDate::Explain('31/12/2026'); // -> 'not a date in month-first order' (the reason without the exception)