🚧 Backend implementation for timeline page

app/Actions/Photo/Timeline.php

@@ -0,0 +1,167 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2025 LycheeOrg.
+ */
+
+namespace App\Actions\Photo;
+
+use App\Eloquent\FixedQueryBuilder;
+use App\Enum\ColumnSortingPhotoType;
+use App\Enum\OrderSortingType;
+use App\Enum\TimelinePhotoGranularity;
+use App\Exceptions\Internal\LycheeInvalidArgumentException;
+use App\Exceptions\Internal\TimelineGranularityException;
+use App\Models\Configs;
+use App\Models\Photo;
+use App\Policies\PhotoQueryPolicy;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+
+class Timeline
+{
+	protected PhotoQueryPolicy $photo_query_policy;
+	private TimelinePhotoGranularity $photo_granularity;
+
+	public function __construct(PhotoQueryPolicy $photo_query_policy)
+	{
+		$this->photo_query_policy = $photo_query_policy;
+		$this->photo_granularity = Configs::getValueAsEnum('timeline_photos_granularity', TimelinePhotoGranularity::class);
+	}
+
+	/**
+	 * Create the query manually.
+	 *
+	 * @return FixedQueryBuilder<Photo>
+	 */
+	public function do(): Builder
+	{
+		$order = Configs::getValueAsEnum('timeline_photos_order', ColumnSortingPhotoType::class);
+
+		// Safe default (should not be needed).
+		// @codeCoverageIgnoreStart
+		if (!in_array($order, [ColumnSortingPhotoType::CREATED_AT, ColumnSortingPhotoType::TAKEN_AT], true)) {
+			$order = ColumnSortingPhotoType::TAKEN_AT;
+		}
+		// @codeCoverageIgnoreEnd
+
+		return $this->photo_query_policy->applySearchabilityFilter(
+			query: Photo::query()->with(['album', 'statistics', 'size_variants', 'size_variants.sym_links']),
+			origin: null,
+			include_nsfw: !Configs::getValueAsBool('hide_nsfw_in_timeline')
+		)->orderBy($order->value, OrderSortingType::DESC->value);
+	}
+
+	/**
+	 * Return the number of pictures that are younger than this.
+	 * We use this to dertermine the current page given a date.
+	 *
+	 * @param Carbon $date
+	 *
+	 * @return int
+	 */
+	public function countYoungerFromDate(Carbon $date): int
+	{
+		$order = Configs::getValueAsEnum('timeline_photos_order', ColumnSortingPhotoType::class);
+
+		// Safe default (should not be needed).
+		// @codeCoverageIgnoreStart
+		if (!in_array($order, [ColumnSortingPhotoType::CREATED_AT, ColumnSortingPhotoType::TAKEN_AT], true)) {
+			$order = ColumnSortingPhotoType::TAKEN_AT;
+		}
+		// @codeCoverageIgnoreEnd
+
+		return $this->photo_query_policy->applySearchabilityFilter(
+			query: Photo::query()
+				->where($order->value, '>', $date)
+				->whereNotNull($order->value),
+			origin: null,
+			include_nsfw: !Configs::getValueAsBool('hide_nsfw_in_timeline')
+		)->count();
+	}
+
+	/**
+	 * Return the number of pictures that are younger than this.
+	 * We use this to dertermine the current page given a photo.
+	 *
+	 * @param Photo $photo
+	 *
+	 * @return int
+	 */
+	public function countYoungerFromPhoto(Photo $photo): int
+	{
+		$order = Configs::getValueAsEnum('timeline_photos_order', ColumnSortingPhotoType::class);
+
+		// Safe default (should not be needed).
+		// @codeCoverageIgnoreStart
+		if (!in_array($order, [ColumnSortingPhotoType::CREATED_AT, ColumnSortingPhotoType::TAKEN_AT], true)) {
+			$order = ColumnSortingPhotoType::TAKEN_AT;
+		}
+		// @codeCoverageIgnoreEnd
+
+		return $this->photo_query_policy->applySearchabilityFilter(
+			query: Photo::query()
+				->joinSub(
+					query: Photo::query()->select($order->value)->where('id', $photo->id),
+					as: 'sub',
+					first: 'sub.' . $order->value,
+					operator: '<',
+					second: 'photos.' . $order->value
+				)
+				->whereNotNull('photos.' . $order->value),
+			origin: null,
+			include_nsfw: !Configs::getValueAsBool('hide_nsfw_in_timeline')
+		)->count();
+	}
+
+	/**
+	 * Get all the dates of the timeline.
+	 *
+	 * @return Collection<int,string>
+	 */
+	public function dates(): Collection
+	{
+		$order = Configs::getValueAsEnum('timeline_photos_order', ColumnSortingPhotoType::class);
+
+		// Safe default (should not be needed).
+		// @codeCoverageIgnoreStart
+		if (!in_array($order, [ColumnSortingPhotoType::CREATED_AT, ColumnSortingPhotoType::TAKEN_AT], true)) {
+			$order = ColumnSortingPhotoType::TAKEN_AT;
+		}
+		// @codeCoverageIgnoreEnd
+
+		// This is among the ugliest piece of code I had ever to write...
+		$is_driver_pgsql = DB::getDriverName() === 'pgsql';
+
+		$formatter = match (DB::getDriverName()) {
+			'sqlite' => 'strftime("%2$s", %1$s)',
+			'mysql' => 'DATE_FORMAT(%s, "%s")',
+			'mariadb' => 'DATE_FORMAT(%s, "%s")',
+			'pgsql' => "to_char(%s, '%s')",
+			default => throw new LycheeInvalidArgumentException('Unsupported database driver'),
+		};
+
+		$date_format = match ($this->photo_granularity) {
+			TimelinePhotoGranularity::YEAR => $is_driver_pgsql ? 'YYYY' : '%Y',
+			TimelinePhotoGranularity::MONTH => $is_driver_pgsql ? 'YYYY-mm' : '%Y-%m',
+			TimelinePhotoGranularity::DAY => $is_driver_pgsql ? 'YYYY-MM-DD' : '%Y-%m-%d',
+			TimelinePhotoGranularity::HOUR => $is_driver_pgsql ? 'YYYY-MM-DD"T"HH24' : '%Y-%m-%dT%H', // hoepfully this is correct
+			TimelinePhotoGranularity::DEFAULT, TimelinePhotoGranularity::DISABLED => throw new TimelineGranularityException(),
+		};
+
+		return $this->photo_query_policy->applySearchabilityFilter(
+			query: Photo::query()
+
+				->selectRaw(sprintf($formatter, $order->value, $date_format) . ' as date')
+				->whereNotNull($order->value),
+			origin: null,
+			include_nsfw: !Configs::getValueAsBool('hide_nsfw_in_timeline')
+		)->groupBy('date')
+			->orderBy('date', OrderSortingType::DESC->value)
+			->pluck('date');
+	}
+}

app/Contracts/Http/Requests/RequestAttribute.php

@@ -32,6 +32,7 @@ class RequestAttribute
 	public const HEADER_ID_ATTRIBUTE = 'header_id';
 
 	public const TITLE_ATTRIBUTE = 'title';
+	public const DATE_ATTRIBUTE = 'date';
 	public const UPLOAD_DATE_ATTRIBUTE = 'upload_date';
 	public const TAKEN_DATE_ATTRIBUTE = 'taken_at';
 	public const DESCRIPTION_ATTRIBUTE = 'description';

app/Enum/TimelineAlbumGranularity.php

@@ -8,6 +8,8 @@
 
 namespace App\Enum;
 
+use App\Exceptions\Internal\TimelineGranularityException;
+
 /**
  * Defines the possible granularities for album timelines.
  */
@@ -18,4 +20,19 @@ enum TimelineAlbumGranularity: string
 	case YEAR = 'year';
 	case MONTH = 'month';
 	case DAY = 'day';
+
+	/**
+	 * Return the ISO date format for the associated granularity.
+	 *
+	 * @return string
+	 */
+	public function format(): string
+	{
+		return match ($this) {
+			self::YEAR => 'Y',
+			self::MONTH => 'Y-m',
+			self::DAY => 'Y-m-d',
+			self::DEFAULT, self::DISABLED => throw new TimelineGranularityException(),
+		};
+	}
 }

app/Enum/TimelinePhotoGranularity.php

@@ -8,6 +8,8 @@
 
 namespace App\Enum;
 
+use App\Exceptions\Internal\TimelineGranularityException;
+
 /**
  * Defines the possible granularities for photo timelines.
  */
@@ -19,4 +21,20 @@ enum TimelinePhotoGranularity: string
 	case MONTH = 'month';
 	case DAY = 'day';
 	case HOUR = 'hour';
+
+	/**
+	 * Return whether the smart album is enabled.
+	 *
+	 * @return string
+	 */
+	public function format(): string
+	{
+		return match ($this) {
+			self::YEAR => 'Y',
+			self::MONTH => 'Y-m',
+			self::DAY => 'Y-m-d',
+			self::HOUR => 'Y-m-d H',
+			self::DEFAULT, self::DISABLED => throw new TimelineGranularityException(),
+		};
+	}
 }

app/Exceptions/Internal/TimelineGranularityException.php

@@ -0,0 +1,17 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2025 LycheeOrg.
+ */
+
+namespace App\Exceptions\Internal;
+
+class TimelineGranularityException extends LycheeLogicException
+{
+	public function __construct(?string $msg = null)
+	{
+		parent::__construct($msg ?? 'Invalid granularity for timeline');
+	}
+}

app/Http/Controllers/Gallery/TimelineController.php

@@ -0,0 +1,78 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2025 LycheeOrg.
+ */
+
+namespace App\Http\Controllers\Gallery;
+
+use App\Actions\Photo\Timeline;
+use App\Http\Requests\Timeline\GetTimelineRequest;
+use App\Http\Requests\Timeline\IdOrDatedTimelineRequest;
+use App\Http\Resources\Models\Utils\TimelineData;
+use App\Http\Resources\Timeline\InitResource;
+use App\Http\Resources\Timeline\TimelineResource;
+use App\Models\Configs;
+use App\Models\Photo;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Pagination\Paginator;
+use Illuminate\Routing\Controller;
+use Spatie\LaravelData\Data;
+
+/**
+ * Controller responsible for the Timeline data.
+ */
+class TimelineController extends Controller
+{
+	/**
+	 * Return the photos given some contraints.
+	 *
+	 * @param IdOrDatedTimelineRequest $request
+	 * @param Timeline                 $timeline
+	 *
+	 * @return Data
+	 */
+	public function __invoke(IdOrDatedTimelineRequest $request, Timeline $timeline): Data
+	{
+		$pagination_limit = Configs::getValueAsInt('timeline_photos_pagination_limit');
+
+		if ($request->photo() !== null) {
+			$youngers = $timeline->countYoungerFromPhoto($request->photo());
+			Paginator::currentPageResolver(fn () => ceil($youngers / $pagination_limit));
+		} elseif ($request->date !== null) {
+			$youngers = $timeline->countYoungerFromDate($request->date);
+			Paginator::currentPageResolver(fn () => ceil($youngers / $pagination_limit));
+		}
+
+		/** @var LengthAwarePaginator<Photo> $photo_results */
+		/** @disregard P1013 Undefined method withQueryString() (stupid intelephense) */
+		$photo_results = $timeline->do()->paginate($pagination_limit);
+
+		return TimelineResource::fromData($photo_results);
+	}
+
+	/**
+	 * Return init Search.
+	 *
+	 * @return InitResource
+	 */
+	public function init(): Data
+	{
+		return new InitResource();
+	}
+
+	/**
+	 * Return all the dates of the timeline.
+	 *
+	 * @param GetTimelineRequest $request
+	 * @param Timeline           $timeline
+	 *
+	 * @return TimelineData[]
+	 */
+	public function dates(GetTimelineRequest $request, Timeline $timeline): array
+	{
+		return $timeline->dates()->map(fn (string $date) => TimelineData::fromDate($date))->toArray();
+	}
+}

app/Http/Middleware/ConfigIntegrity.php

@@ -33,6 +33,10 @@ class ConfigIntegrity
 		'timeline_album_date_format_year',
 		'timeline_album_date_format_month',
 		'timeline_album_date_format_day',
+		'timeline_quick_access_date_format_year',
+		'timeline_quick_access_date_format_month',
+		'timeline_quick_access_date_format_day',
+		'timeline_quick_access_date_format_hour',
 		'number_albums_per_row_mobile',
 		'client_side_favourite_enabled',
 		'cache_ttl',

app/Http/Requests/Timeline/GetTimelineRequest.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2025 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Timeline;
+
+use App\Http\Requests\AbstractEmptyRequest;
+use App\Models\Configs;
+use Illuminate\Support\Facades\Auth;
+
+class GetTimelineRequest extends AbstractEmptyRequest
+{
+	/**
+	 * {@inheritDoc}
+	 */
+	public function authorize(): bool
+	{
+		if (!Auth::check() && !Configs::getValueAsBool('timeline_photos_public')) {
+			return false;
+		}
+
+		return Configs::getValueAsBool('timeline_page_enabled');
+	}
+}