Factor out datetimeConversion, tweak doc

lib/Controller/TimeGateController.php

@@ -2,8 +2,7 @@
 namespace OCA\Memento\Controller;
 
 require_once __DIR__ . '/findMementos.php';
-
-use DateTime;
+require_once __DIR__ . '/datetimeConversion.php';
 
 use OCP\IRequest;
 use OCP\IServerContainer;
@@ -46,8 +45,7 @@ class TimeGateController extends Controller {
 			$acceptDatetimeHeader = $this->request->getHeader('Accept-Datetime');
 			if ($acceptDatetimeHeader) {
 				try {
-					$requestedDatetime = DateTime::createFromFormat(DateTime::RFC1123, $acceptDatetimeHeader)
-						->getTimestamp();
+					$requestedDatetime = datetimeStringToTimestamp($acceptDatetimeHeader);
 				} catch (Exception $e) {
 					return new DataDisplayResponse("Invalid Accept-Datetime header.", 400);
 				}

lib/Controller/TimeMapController.php

@@ -2,8 +2,7 @@
 namespace OCA\Memento\Controller;
 
 require_once __DIR__ . '/findMementos.php';
-
-use DateTime;
+require_once __DIR__ . '/datetimeConversion.php';
 
 use OCP\IRequest;
 use OCP\IServerContainer;
@@ -43,8 +42,9 @@ class TimeMapController extends Controller {
 		$timeMapUrl = $this->URLGenerator->getAbsoluteUrl("/apps/memento/timemap/$url");
 		$timeGateUrl = $this->URLGenerator->getAbsoluteUrl("/apps/memento/timegate/$url");
 		if (count($matchingMementos) > 0) {
-			$firstDatetime = formatDatetime($matchingMementos[0]['datetime']);
-			$lastDatetime = formatDatetime($matchingMementos[count($matchingMementos)-1]['datetime']);
+			$firstDatetime = datetimeTimestampToString($matchingMementos[0]['datetime']);
+			$lastMemento = $matchingMementos[count($matchingMementos)-1];
+			$lastDatetime = datetimeTimestampToString($lastMemento['datetime']);
 		}
 		$links = [
 			// FIXME Our $url param has its duplicate slashes removed, so it looks like 'http:/abc'.
@@ -54,7 +54,7 @@ class TimeMapController extends Controller {
 				($firstDatetime && $lastDatetime ? ";from=\"$firstDatetime\";until=\"$lastDatetime\"" : "")
 		];
 		foreach ($matchingMementos as $index => $memento) {
-			$datetime = formatDatetime($memento['datetime']);
+			$datetime = datetimeTimestampToString($memento['datetime']);
 			$maybeFirst = $index === 0 ? 'first ' : '';
 			$maybeLast = $index === count($matchingMementos)-1 ? 'last ' : '';
 			// Make absolute, as the spec says URLs are to be interpreted relative to the *original* url!
@@ -73,9 +73,3 @@ class TimeMapController extends Controller {
 		return $response;
 	}
 }
-
-function formatDatetime($datetime) {
-	$datetime = new DateTime("@$datetime");
-	$s = $datetime->format("D, d M Y H:i:s") . " GMT";
-	return $s;
-}

lib/Controller/datetimeConversion.php

@@ -0,0 +1,18 @@
+<?php
+namespace OCA\Memento\Controller;
+
+use DateTime;
+
+function datetimeTimestampToString($timestamp) {
+	$datetimeObject = new DateTime("@$timestamp"); // will supposedly have the timezone set to UTC.
+	// The spec requires exactly 'GMT' without numeric offset, so we cannot use DateTime::RFC1123.
+	$datetimeString = $datetimeObject->format("D, d M Y H:i:s") . " GMT";
+	return $datetimeString;
+}
+
+function datetimeStringToTimestamp($datetimeString) {
+	// Be tolerant and allow any RFC1123 formatted datetime string.
+	$datetimeObject = DateTime::createFromFormat(DateTime::RFC1123, $datetimeString);
+	$timestamp = $datetimeObject->getTimestamp();
+	return $timestamp;
+}

lib/Controller/findMementos.php

@@ -5,7 +5,12 @@ use DOMDocument;
 use DateTime;
 
 // Finds HTML files that claim to be a snapshot of the given URL;
-// Returns an array of each file's url + original url + snapshot datetime, sorted by datetime.
+// Returns an array of mementos, sorted by datetime, with each memento represented by an array:
+// [
+//   'mementoUrl' => URL of the file, relative to the nextcloud instance
+//   'originalUrl' => original URL, presumably equal to the given $url, except we normalise a bit
+//   'datetime' => snapshot datetime as a unix timestamp
+// ]
 function findMementos($folder, $url) {
 	// Get all HTML files the user owns.
 	$files = $folder->searchByMime('text/html');