enh: validate datetime fields

appinfo/info.xml

@@ -63,6 +63,7 @@
         <command>OCA\Deck\Command\BoardImport</command>
         <command>OCA\Deck\Command\TransferOwnership</command>
         <command>OCA\Deck\Command\CalendarToggle</command>
+        <command>OCA\Deck\Command\FixCardDate</command>
     </commands>
     <activity>
         <settings>

lib/Command/FixCardDate.php

@@ -0,0 +1,148 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Deck\Command;
+
+use OCP\DB\Exception;
+use OCP\IDBConnection;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class FixCardDate extends Command {
+	public function __construct(
+		private IDBConnection $db,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure() {
+		$this
+			->setName('deck:fix-card-date')
+			->setDescription('Fixes the date fields of cards. In some DBs, the date fields may have been stored incorrectly, causing issues with date handling. This command will attempt to fix those dates.')
+			->addOption(
+				'default-year',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'Default year to use for cards with invalid dates. If not provided, the large year number will be trimmed to first 4 digits.',
+			)
+			->addOption(
+				'dry-run',
+				null,
+				InputOption::VALUE_NONE,
+				'Dry run, do not make any changes.',
+			)
+		;
+	}
+
+	/**
+	 * @throws Exception
+	 */
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$isDryRun = (bool)$input->getOption('dry-run');
+		$defaultYear = $input->getOption('default-year');
+
+		// Validate default year if provided
+		if ($defaultYear !== null && !preg_match('/^\d{4}$/', $defaultYear)) {
+			$output->writeln('<error>Invalid default year provided. It must be a 4-digit year.</error>');
+			return 1;
+		}
+
+		// Fetch cards with date values and validate invalid years in PHP for DB portability.
+		$qb = $this->db->getQueryBuilder();
+		$qb->select('id', 'duedate', 'startdate', 'done')
+			->from('deck_cards')
+			->where($qb->expr()->orX(
+				$qb->expr()->isNotNull('duedate'),
+				$qb->expr()->isNotNull('startdate'),
+				$qb->expr()->isNotNull('done'),
+			));
+		$result = $qb->executeQuery();
+
+		$hasInvalidCards = false;
+
+		while (($card = $result->fetchAssociative()) !== false) {
+			$cardId = $card['id'];
+			$duedate = $card['duedate'];
+			$startdate = $card['startdate'];
+			$done = $card['done'];
+			$hasInvalidDueDate = $duedate && $this->isInvalidDate($duedate);
+			$hasInvalidStartDate = $startdate && $this->isInvalidDate($startdate);
+			$hasInvalidDoneDate = $done && $this->isInvalidDate($done);
+
+			if (!$hasInvalidDueDate && !$hasInvalidStartDate && !$hasInvalidDoneDate) {
+				continue;
+			}
+
+			$hasInvalidCards = true;
+
+			$output->writeln("Card ID: $cardId");
+
+			if ($hasInvalidDueDate) {
+				$output->writeln("  Original Due Date: $duedate");
+				$duedate = $this->fixDate($duedate, $defaultYear);
+
+				if (!$isDryRun) {
+					$this->updateCardDate($cardId, 'duedate', $duedate);
+				}
+				$output->writeln("  Fixed Due Date: $duedate");
+			}
+
+			if ($hasInvalidStartDate) {
+				$output->writeln("  Original Start Date: $startdate");
+				$startdate = $this->fixDate($startdate, $defaultYear);
+
+				if (!$isDryRun) {
+					$this->updateCardDate($cardId, 'startdate', $startdate);
+				}
+				$output->writeln("  Fixed Start Date: $startdate");
+			}
+
+			if ($hasInvalidDoneDate) {
+				$output->writeln("  Original Done Date: $done");
+				$done = $this->fixDate($done, $defaultYear);
+
+				if (!$isDryRun) {
+					$this->updateCardDate($cardId, 'done', $done);
+				}
+				$output->writeln("  Fixed Done Date: $done");
+			}
+		}
+
+		if (!$hasInvalidCards) {
+			$output->writeln('No cards with invalid dates found.');
+		}
+
+		return 0;
+	}
+
+	protected function isInvalidDate(string $date): bool {
+		$parts = explode('-', $date);
+		$year = $parts[0];
+		return $year > 9999;
+	}
+
+	protected function fixDate(string $date, ?string $defaultYear): string {
+		$parts = explode('-', $date);
+		$year = $parts[0];
+		$fixedYear = $defaultYear;
+		if (!$defaultYear) {
+			$fixedYear = substr($year, 0, 4);
+		}
+		return str_replace($year . '-', $fixedYear . '-', $date);
+	}
+
+	protected function updateCardDate(int $cardId, string $field, string $newDate): void {
+		$qb = $this->db->getQueryBuilder();
+		$qb->update('deck_cards')
+			->set($field, $qb->createNamedParameter($newDate))
+			->set('last_modified', $qb->createNamedParameter(time()))
+			->where($qb->expr()->eq('id', $qb->createNamedParameter($cardId)));
+		$qb->executeStatement();
+	}
+}

lib/Service/CardService.php

@@ -190,7 +190,7 @@ public function findCalendarEntries(int $boardId): array {
 	 * @throws BadrequestException
 	 */
 	public function create(string $title, int $stackId, string $type, int $order, string $owner, string $description = '', $duedate = null, $startdate = null, ?string $color = null, bool $insertAtPosition = false): Card {
-		$this->cardServiceValidator->check(compact('title', 'stackId', 'type', 'order', 'owner'));
+		$this->cardServiceValidator->check(compact('title', 'stackId', 'type', 'order', 'owner', 'startdate', 'duedate'));
 
 		$this->permissionService->checkPermission($this->stackMapper, $stackId, Acl::PERMISSION_EDIT);
 		if ($this->boardService->isArchived($this->stackMapper, $stackId)) {
@@ -203,8 +203,8 @@ public function create(string $title, int $stackId, string $type, int $order, st
 		$card->setOrder($order);
 		$card->setOwner($owner);
 		$card->setDescription($description);
-		$card->setDuedate($duedate);
-		$card->setStartdate($startdate);
+		$card->setDuedate($duedate ? new \DateTime($duedate) : null);
+		$card->setStartdate($startdate ? new \DateTime($startdate) : null);
 		$card->setColor($color);
 
 		if (!$insertAtPosition) {
@@ -263,7 +263,7 @@ public function delete(int $id): Card {
 	 * @throws BadRequestException
 	 */
 	public function update(int $id, string $title, int $stackId, string $type, string $owner, string $description = '', int $order = 0, ?string $duedate = null, ?int $deletedAt = null, ?bool $archived = null, ?OptionalNullableValue $done = null, ?string $startdate = null, ?OptionalNullableValue $color = null): Card {
-		$this->cardServiceValidator->check(compact('id', 'title', 'stackId', 'type', 'owner', 'order'));
+		$this->cardServiceValidator->check(compact('id', 'title', 'stackId', 'type', 'owner', 'order', 'startdate', 'duedate', 'done'));
 
 		$this->permissionService->checkPermission($this->cardMapper, $id, Acl::PERMISSION_EDIT, allowDeletedCard: true);
 		$this->permissionService->checkPermission($this->stackMapper, $stackId, Acl::PERMISSION_EDIT);

lib/Validators/BaseValidator.php

@@ -11,6 +11,7 @@
 
 use Exception;
 use OCA\Deck\BadRequestException;
+use OCA\Deck\Model\OptionalNullableValue;
 
 abstract class BaseValidator {
 
@@ -31,22 +32,35 @@ private function validate($data) {
 
 		foreach ($data as $field => $value) {
 			$field_rule = $rules[$field];
+			$isOptional = is_array($field_rule) && in_array('optional', $field_rule, true);
+
+			if ($isOptional) {
+				if ($value instanceof OptionalNullableValue) {
+					$value = $value->getValue();
+				}
+				if ($value === null || $value === '') {
+					continue;
+				}
+			}
 
 			if (is_array($field_rule)) {
 				foreach ($field_rule as $rule) {
+					if ($rule === 'optional') {
+						continue;
+					}
 					// The format for specifying validation rules and parameters follows an
 					// easy {rule}:{parameters} formatting convention. For instance the
 					// rule "Max:3" states that the value may only be three letters.
 					if (str_contains($rule, ':')) {
 						[$rule, $parameter] = explode(':', $rule, 2);
 						if (!$this->{$rule}($value, $parameter)) {
 							throw new BadRequestException(
-								$this->getErrorMessage($rule, $field, $parameter));
+								$this->getErrorMessage($rule, $field, $parameter, $isOptional));
 						}
 					} else {
 						if (!$this->{$rule}($value)) {
 							throw new BadRequestException(
-								$field . ' must be provided and must be ' . str_replace('_', ' ', $rule));
+								$this->getErrorMessage($rule, $field, null, $isOptional));
 						}
 					}
 				}
@@ -135,6 +149,61 @@ private function min($value, $limit): bool {
 		return $this->getSize($value) >= $limit;
 	}
 
+	/**
+	 * @throws Exception
+	 */
+	private function datetime(mixed $value): bool {
+		if (!is_string($value) || $value === '') {
+			return false;
+		}
+
+		// Java/Android commonly send ISO_OFFSET_DATE_TIME and ISO_INSTANT.
+		if (preg_match('/^(?<date>\d{4}-\d{2}-\d{2})T(?<hour>\d{2}):(?<minute>\d{2})(?::(?<second>\d{2})(?:\.(?<fraction>\d{1,9}))?)?(?<timezone>Z|[+\-]\d{2}:\d{2})$/', $value, $matches)) {
+			$second = ($matches['second'] ?? '') !== '' ? $matches['second'] : '00';
+			$fraction = $matches['fraction'] ?? '';
+
+			if ($fraction !== '') {
+				// PHP supports microseconds, so normalize Java nanoseconds to 6 digits.
+				$fraction = str_pad(substr($fraction, 0, 6), 6, '0');
+			} else {
+				$fraction = '000000';
+			}
+
+			$timezone = $matches['timezone'] === 'Z' ? '+00:00' : $matches['timezone'];
+			$normalizedValue = sprintf(
+				'%sT%s:%s:%s.%s%s',
+				$matches['date'],
+				$matches['hour'],
+				$matches['minute'],
+				$second,
+				$fraction,
+				$timezone
+			);
+
+			$datetime = \DateTime::createFromFormat('Y-m-d\TH:i:s.uP', $normalizedValue);
+			if ($datetime && $datetime->format('Y-m-d\TH:i:s.uP') === $normalizedValue) {
+				return true;
+			}
+		}
+
+		$allowedFormats = [
+			'Y-m-d',
+			'Y-m-d H:i:s',
+			'Y-m-d\TH:i:sP',
+			'Y-m-d\TH:i:s\Z',
+			'Y-m-d\TH:i:s.v\Z',
+		];
+
+		foreach ($allowedFormats as $format) {
+			$datetime = \DateTime::createFromFormat($format, $value);
+			if ($datetime && $datetime->format($format) === $value) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
 	/**
 	 * Get the size of an attribute.
 	 *
@@ -159,13 +228,17 @@ protected function getSize($value): int {
 	 * @param $parameter
 	 * @return string
 	 */
-	protected function getErrorMessage(string $rule, $field, $parameter = null): string {
+	protected function getErrorMessage(string $rule, $field, $parameter = null, $isOptional = false): string {
 		if (in_array($rule, ['max', 'min'], true)) {
 			return $rule === 'max'
 			? $field . ' cannot be longer than ' . $parameter . ' characters '
 			: $field . ' must be at least ' . $parameter . ' characters long ';
 		}
 
+		if ($isOptional) {
+			return $field . ' must be ' . str_replace('_', ' ', $rule);
+		}
+
 		return $field . ' must be provided and must be ' . str_replace('_', ' ', $rule);
 	}
 }

lib/Validators/CardServiceValidator.php

@@ -21,6 +21,9 @@ public function rules() {
 			'type' => ['not_empty', 'not_null', 'not_false', 'max:64'],
 			'order' => ['numeric'],
 			'owner' => ['not_empty', 'not_null', 'not_false', 'max:64'],
+			'startdate' => ['optional', 'datetime'],
+			'duedate' => ['optional', 'datetime'],
+			'done' => ['optional', 'datetime'],
 		];
 	}
 }

src/components/card/DueDateSelector.vue

@@ -180,6 +180,9 @@ export default defineComponent({
 			},
 
 			set(val) {
+				if (!this.isValidDate(val)) {
+					return
+				}
 				this.$emit('input', val ? new Date(val) : null)
 			},
 		},

src/components/card/StartDateSelector.vue

@@ -95,6 +95,9 @@ export default defineComponent({
 			},
 
 			set(val) {
+				if (!this.isValidDate(val)) {
+					return
+				}
 				this.$emit('input', val ? new Date(val) : null)
 			},
 		},

src/mixins/readableDate.js

@@ -5,6 +5,8 @@
 
 import moment from '@nextcloud/moment'
 
+const maxYear = 9999
+
 export default {
 	computed: {
 		formatReadableDate() {
@@ -13,4 +15,11 @@ export default {
 			}
 		},
 	},
+	methods: {
+		isValidDate(val) {
+			// Prevent setting a date with a year greater than 9999, as this can cause issues with some date libraries and databases.
+			const date = val ? new Date(val) : null
+			return !(date && date.getFullYear() > maxYear)
+		},
+	},
 }