Resolve Halcyon DB template mtimes without a query per check

src/Halcyon/Datasource/DatasourceInterface.php

@@ -118,19 +118,23 @@ public function getPathsCacheKey(): string;
     /**
      * Get all available paths within this datasource.
      *
-     * This method returns an array, with all available paths as the key, and a boolean that represents whether the path
-     * can be handled or modified.
+     * This method returns an array, with all available paths as the key, and a value that represents whether the path
+     * can be handled or modified. A falsy value means the path cannot be handled; any truthy value means it can.
+     *
+     * Datasources that are able to determine a path's modification time cheaply may return that timestamp as the
+     * truthy value, allowing consumers to resolve modification times without a further lookup.
      *
      * Example:
      *
      * ```php
      * [
      *     'path/to/file.md' => true, // (this path is available, and can be handled)
-     *     'path/to/file2.md' => false // (this path is available, but cannot be handled)
+     *     'path/to/file2.md' => 1559390400, // (as above, and was last modified at this timestamp)
+     *     'path/to/file3.md' => false // (this path is available, but cannot be handled)
      * ]
      * ```
      *
-     * @return array An array of available paths alongside whether they can be handled.
+     * @return array<string, int|bool> An array of available paths alongside whether they can be handled.
      */
     public function getAvailablePaths(): array;
 }

src/Halcyon/Datasource/DbDatasource.php

@@ -341,25 +341,37 @@ public function delete(string $dirName, string $fileName, string $extension): bo
      */
     public function lastModified(string $dirName, string $fileName, string $extension): ?int
     {
-        try {
-            return Carbon::parse($this->getQuery()
-                    ->where('path', $this->makeFilePath($dirName, $fileName, $extension))
-                    ->first()->updated_at)->timestamp;
-        } catch (Exception $ex) {
-            return null;
-        }
+        $record = $this->getQuery()
+            ->select('updated_at')
+            ->where('path', $this->makeFilePath($dirName, $fileName, $extension))
+            ->first();
+
+        return $record ? Carbon::parse($record->updated_at)->timestamp : null;
     }
 
     /**
      * @inheritDoc
+     *
+     * The key is versioned because the payload shape has changed; see getAvailablePaths().
      */
     public function getPathsCacheKey(): string
     {
-        return 'halcyon-datastore-db-' . $this->table . '-' . $this->source;
+        return 'halcyon-datastore-db-v2-' . $this->table . '-' . $this->source;
     }
 
     /**
-     * @inheritDoc
+     * Get all available paths within this datasource.
+     *
+     * Live records are mapped to their last modification timestamp rather than `true` so that
+     * consumers can resolve mtimes without a further query. Timestamps are truthy, so the
+     * existence / deletion contract of this map is unchanged.
+     *
+     * Note that the `halcyon.datasource.db.beforeGetAvailablePaths` event below may still
+     * return plain booleans, so consumers must treat the timestamps as an optimization rather
+     * than something they can rely on being present.
+     *
+     * @return array<string, int|bool> Paths that cannot be handled are `false`; live paths are
+     *                                 a timestamp, or `true` when supplied by the event below.
      **/
     public function getAvailablePaths(): array
     {
@@ -377,14 +389,16 @@ public function getAvailablePaths(): array
         if (!$pathsCache = $this->fireEvent('halcyon.datasource.db.beforeGetAvailablePaths', [], true)) {
             // Only query for what is required
             $this->bindEventOnce('halcyon.datasource.db.extendQuery', function ($query, $ignoreDeleted) {
-                $query->addSelect('source', 'path', 'deleted_at');
+                $query->addSelect('source', 'path', 'deleted_at', 'updated_at');
             });
 
             // Get all records stored in the DB
             $records = $this->getQuery(false)->get();
 
             foreach ($records as $record) {
-                $pathsCache[$record->path] = !$record->deleted_at;
+                $pathsCache[$record->path] = $record->deleted_at
+                    ? false
+                    : Carbon::parse($record->updated_at)->timestamp;
             }
         }