feat(game): add sort_title field and backfill command

app/Filament/Resources/GameResource.php

@@ -15,6 +15,7 @@
 use App\Models\Game;
 use App\Models\System;
 use App\Models\User;
+use App\Platform\Actions\WriteGameSortTitleFromGameTitleAction;
 use Filament\Forms;
 use Filament\Forms\Form;
 use Filament\Forms\Get;
@@ -89,6 +90,9 @@ public static function infolist(Infolist $infolist): Infolist
 
                         Infolists\Components\TextEntry::make('title'),
 
+                        Infolists\Components\TextEntry::make('sort_title')
+                            ->label('Sort Title'),
+
                         Infolists\Components\TextEntry::make('forumTopic.id')
                             ->label('Forum Topic ID')
                             ->url(fn (?int $state) => url("viewtopic.php?t={$state}"))
@@ -238,7 +242,41 @@ public static function form(Form $form): Form
                             ->required()
                             ->minLength(2)
                             ->maxLength(80)
-                            ->disabled(!$user->can('updateField', [$form->model, 'Title'])),
+                            ->disabled(!$user->can('updateField', [$form->model, 'Title']))
+                            ->afterStateUpdated(function (Game $record, callable $set, callable $get, string $state) {
+                                // If the user is updating the sort title, don't try to override their update of that field.
+                                if ($get('sort_title') !== $get('original_sort_title')) {
+                                    return;
+                                }
+
+                                $newTitle = $state;
+                                $originalTitle = $record->title;
+
+                                $record->title = $newTitle;
+                                $record->save();
+                                $record->refresh();
+
+                                $newSortTitle = (new WriteGameSortTitleFromGameTitleAction())->execute(
+                                    $record,
+                                    $originalTitle,
+                                );
+
+                                if ($newSortTitle) {
+                                    $set('sort_title', $newSortTitle);
+                                    $set('original_sort_title', $newSortTitle);
+                                }
+                            }),
+
+                        Forms\Components\TextInput::make('sort_title')
+                            ->required()
+                            ->label('Sort Title')
+                            ->minLength(2)
+                            ->disabled(!$user->can('updateField', [$form->model, 'sort_title']))
+                            ->helperText('Manually override the automatic sorting behavior of the game\'s title. For example, "Final Fantasy IV" might be "final fantasy 04". DON\'T CHANGE THIS UNLESS YOU KNOW WHAT YOU\'RE DOING.')
+                            ->reactive()
+                            ->afterStateHydrated(function (callable $set, callable $get, string $state) {
+                                $set('original_sort_title', $state);
+                            }),
 
                         Forms\Components\TextInput::make('ForumTopicID')
                             ->label('Forum Topic ID')

app/Helpers/database/game.php

@@ -8,6 +8,7 @@
 use App\Models\User;
 use App\Platform\Actions\TrimGameMetadata;
 use App\Platform\Actions\UpdateGameSetFromGameAlternativesModification;
+use App\Platform\Actions\WriteGameSortTitleFromGameTitleAction;
 use App\Platform\Enums\AchievementFlag;
 use Illuminate\Support\Facades\Log;
 use Spatie\Activitylog\Facades\CauserResolver;
@@ -648,9 +649,14 @@ function modifyGameTitle(string $username, int $gameId, string $value): bool
         return false;
     }
 
-    $game->Title = $value;
+    $originalTitle = $game->title;
+
+    $game->title = $value;
     $game->save();
 
+    // Also, if necessary, update the game's sort title.
+    (new WriteGameSortTitleFromGameTitleAction())->execute($game, $originalTitle);
+
     addArticleComment('Server', ArticleType::GameModification, $gameId, "{$username} changed the game name");
 
     return true;

app/Models/Game.php

@@ -71,6 +71,7 @@ class Game extends BaseModel implements HasComments, HasMedia
     protected $fillable = [
         'release',
         'Title',
+        'sort_title',
         'ForumTopicID',
         'Publisher',
         'Developer',
@@ -87,6 +88,7 @@ class Game extends BaseModel implements HasComments, HasMedia
     protected $visible = [
         'ID',
         'Title',
+        'sort_title',
         'ConsoleID',
         'ForumTopicID',
         'Flags',

app/Platform/Actions/WriteGameSortTitleFromGameTitleAction.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Platform\Actions;
+
+use App\Models\Game;
+
+class WriteGameSortTitleFromGameTitleAction
+{
+    public function execute(Game $game, string $originalTitle, bool $shouldRespectCustomSortTitle = true): ?string
+    {
+        // Compute the original sort title based on the original game title.
+        // We do this to determine if a developer has given the game a custom sort title, because
+        // if the game indeed has a custom sort title, we may not want to override it.
+        if ($game->sort_title && $shouldRespectCustomSortTitle) {
+            $originalSortTitle = $this->computeSortTitle($originalTitle);
+
+            if ($game->sort_title !== $originalSortTitle) {
+                return null;
+            }
+        }
+
+        // Otherwise, compute and save the new sort title.
+        $game->sort_title = $this->computeSortTitle($game->title);
+        $game->save();
+
+        return $game->sort_title;
+    }
+
+    /**
+     * Sort titles ensure games in lists are sorted properly.
+     * For titles starting with "~", the sort order is determined by the content
+     * within the "~" markers followed by the content after the "~". This ensures
+     * that titles with "~" are grouped together and sorted alphabetically based
+     * on their designated categories and then by their actual game title.
+     *
+     * The "~" prefix is retained in the SortTitle of games with "~" to ensure these
+     * games are sorted at the end of the list, maintaining a clear separation from
+     * non-prefixed titles. This approach allows game titles to be grouped and sorted
+     * in a specific order:
+     *
+     * 1. Non-prefixed titles are sorted alphabetically at the beginning of the list.
+     * 2. Titles prefixed with "~" are grouped at the end, sorted first by the category
+     *    specified within the "~" markers, and then alphabetically by the title following
+     *    the "~".
+     */
+    private function computeSortTitle(string $title): string
+    {
+        $sortTitle = mb_strtolower($title);
+
+        if ($sortTitle[0] === '~') {
+            $endOfFirstTilde = strpos($sortTitle, '~', 1);
+            if ($endOfFirstTilde !== false) {
+                $withinTildes = substr($sortTitle, 1, $endOfFirstTilde - 1);
+                $afterTildes = trim(substr($sortTitle, $endOfFirstTilde + 1));
+
+                $sortTitle = '~' . $withinTildes . ' ' . $afterTildes;
+            }
+        }
+
+        return $sortTitle;
+    }
+}

app/Platform/AppServiceProvider.php

@@ -53,6 +53,7 @@
 use App\Platform\Commands\UpdatePlayerMetrics;
 use App\Platform\Commands\UpdatePlayerPointsStats;
 use App\Platform\Commands\UpdateTotalGamesCount;
+use App\Platform\Commands\WriteGameSortTitles;
 use App\Platform\Components\GameCard;
 use App\Platform\Components\GameTitle;
 use Illuminate\Console\Scheduling\Schedule;
@@ -73,6 +74,7 @@ public function boot(): void
                 UpdateGameMetrics::class,
                 UpdateGameAchievementsMetrics::class,
                 UpdateGamePlayerGames::class,
+                WriteGameSortTitles::class,
 
                 // Game Hashes
                 NoIntroImport::class,

app/Platform/Commands/WriteGameSortTitles.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Platform\Commands;
+
+use App\Models\Game;
+use App\Platform\Actions\WriteGameSortTitleFromGameTitleAction;
+use Illuminate\Console\Command;
+
+class WriteGameSortTitles extends Command
+{
+    protected $signature = "ra:platform:write-game-sort-titles
+                            {gameId? : Target a single game}";
+    protected $description = 'Write sort titles for games derived from their canonical titles';
+
+    public function __construct()
+    {
+        parent::__construct();
+    }
+
+    public function handle(): void
+    {
+        $gameId = $this->argument('gameId');
+        if ($gameId !== null) {
+            $game = Game::findOrFail($gameId);
+
+            $this->info("\nUpserting a sort title for [{$game->id}:{$game->title}].");
+
+            (new WriteGameSortTitleFromGameTitleAction())->execute(
+                $game,
+                $game->title,
+                shouldRespectCustomSortTitle: false,
+            );
+
+            $this->info('Done.');
+        } else {
+            $gamesCount = Game::count();
+            $this->info("\nUpserting sort titles for {$gamesCount} games.");
+
+            $progressBar = $this->output->createProgressBar($gamesCount);
+            $progressBar->start();
+
+            $action = new WriteGameSortTitleFromGameTitleAction();
+            Game::query()->chunk(100, function ($games) use ($progressBar, $action) {
+                foreach ($games as $game) {
+                    $action->execute($game, $game->title, shouldRespectCustomSortTitle: false);
+                }
+
+                $progressBar->advance(count($games));
+            });
+
+            $progressBar->finish();
+
+            $this->info("\nAll sort titles have been upserted.");
+        }
+    }
+}

app/Platform/Services/GameListService.php

@@ -126,6 +126,7 @@ public function initializeGameList(array $gameIds, bool $allowNonGameSystems = f
              *    specified within the "~" markers, and then alphabetically by the title following
              *    the "~".
              */
+            // TODO use the sort_title attribute on the games table
             $game['SortTitle'] = mb_strtolower($game['Title']);
             if ($game['SortTitle'][0] === '~') {
                 $endOfFirstTilde = strpos($game['SortTitle'], '~', 1);

app/Policies/GamePolicy.php

@@ -96,7 +96,7 @@ public function updateField(User $user, Game $game, string $fieldName): bool
             Role::DEVELOPER_JUNIOR => ['GuideURL', 'Developer', 'Publisher', 'Genre', 'released_at', 'released_at_granularity'],
 
             Role::DEVELOPER => ['Title', 'GuideURL', 'Developer', 'Publisher', 'Genre', 'released_at', 'released_at_granularity'],
-            Role::DEVELOPER_STAFF => ['Title', 'GuideURL', 'Developer', 'Publisher', 'Genre', 'released_at', 'released_at_granularity'],
+            Role::DEVELOPER_STAFF => ['Title', 'sort_title', 'GuideURL', 'Developer', 'Publisher', 'Genre', 'released_at', 'released_at_granularity'],
         ];
 
         $userRoles = $user->getRoleNames();
@@ -131,8 +131,7 @@ public function createForumTopic(User $user, Game $game): bool
             Role::DEVELOPER,
             Role::FORUM_MANAGER,
             Role::MODERATOR,
-        ])
-            || $user->getAttribute('Permissions') >= Permissions::Developer;
+        ]);
     }
 
     // TODO rename to viewActivitylog or use manage() ?
@@ -143,8 +142,7 @@ public function viewModifications(User $user): bool
             Role::DEVELOPER_STAFF,
             Role::DEVELOPER,
             Role::DEVELOPER_JUNIOR,
-        ])
-            || $user->getAttribute('Permissions') >= Permissions::JuniorDeveloper;
+        ]);
     }
 
     private function canDeveloperJuniorUpdateGame(User $user, Game $game): bool

database/migrations/platform/2024_09_12_000000_update_gamedata_table.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class() extends Migration {
+    public function up(): void
+    {
+        Schema::table('GameData', function (Blueprint $table) {
+            $table->string('sort_title')->after('Title')->nullable();
+        });
+
+        Schema::table('GameData', function (Blueprint $table) {
+            $table->index('sort_title');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('GameData', function (Blueprint $table) {
+            $table->dropIndex('sort_title');
+        });
+
+        Schema::table('GameData', function (Blueprint $table) {
+            $table->dropColumn('sort_title');
+        });
+    }
+};

tests/Feature/Platform/Action/WriteGameSortTitleFromGameTitleActionTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\Platform\Action;
+
+use App\Models\Game;
+use App\Platform\Actions\WriteGameSortTitleFromGameTitleAction;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class WriteGameSortTitleFromGameTitleActionTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function testItGeneratesSortTitleBasedOnGameTitle(): void
+    {
+        // Arrange
+        $game = Game::factory()->create(['Title' => 'Sonic the Hedgehog']);
+
+        // Act
+        (new WriteGameSortTitleFromGameTitleAction())->execute($game, $game->title);
+        $game = $game->fresh();
+
+        // Assert
+        $this->assertEquals('sonic the hedgehog', $game->sort_title);
+    }
+
+    public function testItPreservesCustomSortTitlesByDefault(): void
+    {
+        // Arrange
+        $game = Game::factory()->create(['Title' => 'Final Fantasy IV', 'sort_title' => 'final fantasy 04']);
+
+        // Act
+        (new WriteGameSortTitleFromGameTitleAction())->execute($game, $game->title);
+        $game = $game->fresh();
+
+        // Assert
+        $this->assertEquals('final fantasy 04', $game->sort_title);
+    }
+
+    public function testItCanBeConfiguredToOverrideCustomSortTitles(): void
+    {
+        // Arrange
+        $game = Game::factory()->create(['Title' => 'Final Fantasy IV', 'sort_title' => 'final fantasy 04']);
+
+        // Act
+        (new WriteGameSortTitleFromGameTitleAction())->execute(
+            $game,
+            $game->title,
+            shouldRespectCustomSortTitle: false,
+        );
+        $game = $game->fresh();
+
+        // Assert
+        $this->assertEquals('final fantasy iv', $game->sort_title);
+    }
+
+    public function testItCorrectlyHandlesGameTitlesWithTildes(): void
+    {
+        // Arrange
+        $game = Game::factory()->create(['Title' => '~Homebrew~ Classic Kong']);
+
+        // Act
+        (new WriteGameSortTitleFromGameTitleAction())->execute($game, $game->title);
+        $game = $game->fresh();
+
+        // Assert
+        $this->assertEquals('~homebrew classic kong', $game->sort_title);
+    }
+}