documentation and env changes

src/Controller/AlbumController.php

@@ -12,7 +12,7 @@ use App\Repository\AlbumRepository;
 use App\Repository\AlbumTrackRepository;
 use App\Repository\ReviewRepository;
 use App\Service\AlbumSearchService;
-use App\Service\ImageStorage;
+use App\Service\UploadStorage;
 use App\Service\SpotifyClient;
 use App\Service\SpotifyGenreResolver;
 use Doctrine\ORM\EntityManagerInterface;
@@ -30,7 +30,7 @@ use Symfony\Component\Security\Http\Attribute\IsGranted;
 class AlbumController extends AbstractController
 {
     public function __construct(
-        private readonly ImageStorage $imageStorage,
+        private readonly UploadStorage $uploadStorage,
         private readonly AlbumSearchService $albumSearch,
         private readonly SpotifyGenreResolver $genreResolver,
         private readonly int $searchLimit = 20
@@ -50,13 +50,14 @@ class AlbumController extends AbstractController
             'query' => $criteria->query,
             'album' => $criteria->albumName,
             'artist' => $criteria->artist,
-            'genre' => $criteria->getGenre(),
+            'genre' => $criteria->genre,
             'year_from' => $criteria->yearFrom ?? '',
             'year_to' => $criteria->yearTo ?? '',
             'albums' => $result->albums,
             'stats' => $result->stats,
             'savedIds' => $result->savedIds,
             'source' => $criteria->source,
+            'spotifyConfigured' => $this->albumSearch->isSpotifyConfigured(),
         ]);
     }
 
@@ -98,6 +99,7 @@ class AlbumController extends AbstractController
         $albumEntity = $this->findAlbum($id, $albumRepo);
         $isSaved = $albumEntity !== null;
         if (!$albumEntity) {
+            // Album has never been saved locally, so hydrate it via Spotify before rendering.
             $spotifyAlbum = $spotify->getAlbumWithTracks($id);
             if ($spotifyAlbum === null) {
                 throw $this->createNotFoundException('Album not found');
@@ -106,6 +108,7 @@ class AlbumController extends AbstractController
             $em->flush();
         } else {
             if ($this->syncSpotifyTracklistIfNeeded($albumEntity, $albumRepo, $trackRepo, $spotify)) {
+                // Track sync mutated the entity: persist before we build template arrays.
                 $em->flush();
             }
         }
@@ -193,7 +196,7 @@ class AlbumController extends AbstractController
         if ($album) {
             $this->ensureCanManageAlbum($album);
             if ($album->getSource() === 'user') {
-                $this->imageStorage->remove($album->getCoverImagePath());
+                $this->uploadStorage->remove($album->getCoverImagePath());
             }
             $em->remove($album);
             $em->flush();
@@ -238,6 +241,7 @@ class AlbumController extends AbstractController
         }
         // Fallback: attempt to parse
         try {
+            // Trust PHP's parser only as a last resort (it accepts many human formats).
             $dt = new \DateTimeImmutable($s);
             return $dt->format('Y-m-d');
         } catch (\Throwable) {
@@ -328,8 +332,8 @@ class AlbumController extends AbstractController
         }
         $file = $form->get('coverUpload')->getData();
         if ($file instanceof UploadedFile) {
-            $this->imageStorage->remove($album->getCoverImagePath());
-            $album->setCoverImagePath($this->imageStorage->storeAlbumCover($file));
+            $this->uploadStorage->remove($album->getCoverImagePath());
+            $album->setCoverImagePath($this->uploadStorage->storeAlbumCover($file));
         }
     }
 
@@ -365,6 +369,7 @@ class AlbumController extends AbstractController
         $storedCount = $album->getTracks()->count();
         $needsSync = $storedCount === 0;
         if (!$needsSync && $album->getTotalTracks() > 0 && $storedCount !== $album->getTotalTracks()) {
+            // Spotify track counts do not match what we have stored; re-sync to avoid stale data.
             $needsSync = true;
         }
         if (!$needsSync) {