Validate some user provided calendar query range dates

Summary:
Calendar search form allows users to define date ranges. Entering gibberish data leads to a cryptic exception due to calling `format()` on `null`, as `AphrontFormDateControlValue::getDateTime()` can return `null` instead of a `DateTime` object.

Also add some additional PhpDoc as a result of playing with this code.

Note that other calendar query forms are more lenient and still accepts gibberish after applying this patch. The intention behind this patch is replacing a cryptic exception with a more appropriate and descriptive error; this patch does not attempt to introduce validation everywhere.

```
EXCEPTION: (Error) Call to a member function format() on null at [<phorge>/src/applications/calendar/query/PhabricatorCalendarEventSearchEngine.php:469]
```

Closes T15943

Test Plan:
* On http://phorge.localhost/calendar/query/month/, click "Edit Query", check "Occurs After", replace default date value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/month/, click "Edit Query", check "Occurs After", replace default time value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/month/, click "Edit Query", check "Occurs Before", replace default date value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/month/, click "Edit Query", check "Occurs Before", replace default time value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/day/, click "Edit Query", check "Occurs After", replace default date value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/day/, click "Edit Query", check "Occurs After", replace default time value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/day/, click "Edit Query", check "Occurs Before", replace default date value with "abcde", click "Search" button
* On http://phorge.localhost/calendar/query/day/, click "Edit Query", check "Occurs Before", replace default time value with "abcde", click "Search" button

Reviewers: O1 Blessed Committers, valerio.bozzolan

Reviewed By: O1 Blessed Committers, valerio.bozzolan

Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno

Maniphest Tasks: T15943

Differential Revision: https://we.phorge.it/D25825

src/applications/calendar/query/PhabricatorCalendarEventSearchEngine.php

@@ -485,6 +485,12 @@ final class PhabricatorCalendarEventSearchEngine
       ->setHeader($header);
   }
 
+  /**
+   * @param string|null $range_start Epoch
+   * @param string|null $range_end Epoch
+   * @param string $display View, such as "month" or "day"
+   * @return array<string|int, string|int, string|int> YYYY, M, D
+   */
   private function getDisplayYearAndMonthAndDay(
     $range_start,
     $range_end,
@@ -527,7 +533,7 @@ final class PhabricatorCalendarEventSearchEngine
 
   /**
    * @param PhabricatorSavedQuery $saved
-   * @return AphrontFormDateControlValue
+   * @return AphrontFormDateControlValue Query date range start
    */
   private function getQueryDateFrom(PhabricatorSavedQuery $saved) {
     if ($this->calendarYear && $this->calendarMonth) {
@@ -544,11 +550,36 @@ final class PhabricatorCalendarEventSearchEngine
         ));
     }
 
-    return $this->getQueryDate($saved, 'rangeStart');
+    $date = $this->getQueryDate($saved, 'rangeStart');
+    $this->validateDate($date);
+
+    return $date;
   }
 
+  /**
+   * @param PhabricatorSavedQuery $saved
+   * @return AphrontFormDateControlValue Query date range end
+   */
   private function getQueryDateTo(PhabricatorSavedQuery $saved) {
-    return $this->getQueryDate($saved, 'rangeEnd');
+    $date = $this->getQueryDate($saved, 'rangeEnd');
+    $this->validateDate($date);
+    return $date;
+  }
+
+  /**
+   * Validate the user provided date and time value(s) by calling
+   * @{class:AphrontFormDateControlValue}::isValid().
+   * Throw an Exception if invalid.
+   *
+   * @param AphrontFormDateControlValue $date
+   * @return void
+   */
+  private function validateDate(AphrontFormDateControlValue $date) {
+    if (!$date->isValid()) {
+      // TODO: Use DateMalformedStringException once we require PHP 8.3.0
+      throw new Exception(
+        pht('Invalid date or time value set as query value.'));
+    }
   }
 
   private function getQueryDate(PhabricatorSavedQuery $saved, $key) {