what the fuck

src/Entity/Album.php

@@ -7,6 +7,9 @@ use App\Entity\User;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\Validator\Constraints as Assert;
 
+/**
+ * Album aggregates Spotify or user-submitted metadata persisted in the catalog.
+ */
 #[ORM\Entity(repositoryClass: AlbumRepository::class)]
 #[ORM\Table(name: 'albums')]
 #[ORM\HasLifecycleCallbacks]
@@ -49,6 +52,9 @@ class Album
     #[ORM\Column(type: 'string', length: 1024, nullable: true)]
     private ?string $coverUrl = null;
 
+    #[ORM\Column(type: 'string', length: 255, nullable: true)]
+    private ?string $coverImagePath = null;
+
     #[ORM\Column(type: 'string', length: 1024, nullable: true)]
     private ?string $externalUrl = null;
 
@@ -62,6 +68,9 @@ class Album
     #[ORM\Column(type: 'datetime_immutable')]
     private ?\DateTimeImmutable $updatedAt = null;
 
+    /**
+     * Initializes timestamps right before first persistence.
+     */
     #[ORM\PrePersist]
     public function onPrePersist(): void
     {
@@ -70,62 +79,231 @@ class Album
         $this->updatedAt = $now;
     }
 
+    /**
+     * Refreshes the updated timestamp prior to every update.
+     */
     #[ORM\PreUpdate]
     public function onPreUpdate(): void
     {
         $this->updatedAt = new \DateTimeImmutable();
     }
 
-    public function getId(): ?int { return $this->id; }
-
-    public function getSpotifyId(): ?string { return $this->spotifyId; }
-    public function setSpotifyId(?string $spotifyId): void { $this->spotifyId = $spotifyId; }
-    public function getLocalId(): ?string { return $this->localId; }
-    public function setLocalId(?string $localId): void { $this->localId = $localId; }
-    public function getSource(): string { return $this->source; }
-    public function setSource(string $source): void { $this->source = $source; }
-
-    public function getName(): string { return $this->name; }
-    public function setName(string $name): void { $this->name = $name; }
-
     /**
-     * @return list<string>
+     * Returns the database identifier.
      */
-    public function getArtists(): array { return $this->artists; }
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
     /**
-     * @param list<string> $artists
+     * Gets the Spotify album identifier when sourced from Spotify.
      */
-    public function setArtists(array $artists): void { $this->artists = array_values($artists); }
-
-    public function getReleaseDate(): ?string { return $this->releaseDate; }
-    public function setReleaseDate(?string $releaseDate): void { $this->releaseDate = $releaseDate; }
-
-    public function getTotalTracks(): int { return $this->totalTracks; }
-    public function setTotalTracks(int $totalTracks): void { $this->totalTracks = $totalTracks; }
-
-    public function getCoverUrl(): ?string { return $this->coverUrl; }
-    public function setCoverUrl(?string $coverUrl): void { $this->coverUrl = $coverUrl; }
-
-    public function getExternalUrl(): ?string { return $this->externalUrl; }
-    public function setExternalUrl(?string $externalUrl): void { $this->externalUrl = $externalUrl; }
-    public function getCreatedBy(): ?User { return $this->createdBy; }
-    public function setCreatedBy(?User $user): void { $this->createdBy = $user; }
-
-    public function getCreatedAt(): ?\DateTimeImmutable { return $this->createdAt; }
-    public function getUpdatedAt(): ?\DateTimeImmutable { return $this->updatedAt; }
+    public function getSpotifyId(): ?string
+    {
+        return $this->spotifyId;
+    }
 
     /**
-     * Shape the album like the Spotify payload expected by Twig templates.
+     * Stores the Spotify album identifier.
+     */
+    public function setSpotifyId(?string $spotifyId): void
+    {
+        $this->spotifyId = $spotifyId;
+    }
+
+    /**
+     * Gets the local unique identifier for user-created albums.
+     */
+    public function getLocalId(): ?string
+    {
+        return $this->localId;
+    }
+
+    /**
+     * Assigns the local identifier for user-created albums.
+     */
+    public function setLocalId(?string $localId): void
+    {
+        $this->localId = $localId;
+    }
+
+    /**
+     * Returns the album source flag ("spotify" or "user").
+     */
+    public function getSource(): string
+    {
+        return $this->source;
+    }
+
+    /**
+     * Sets the album source flag ("spotify" or "user").
+     */
+    public function setSource(string $source): void
+    {
+        $this->source = $source;
+    }
+
+    /**
+     * Returns the human readable album title.
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Updates the human readable album title.
+     */
+    public function setName(string $name): void
+    {
+        $this->name = $name;
+    }
+
+    /**
+     * @return list<string> Ordered performer names.
+     */
+    public function getArtists(): array
+    {
+        return $this->artists;
+    }
+
+    /**
+     * @param list<string> $artists Ordered performer names.
+     */
+    public function setArtists(array $artists): void
+    {
+        $this->artists = array_values($artists);
+    }
+
+    /**
+     * Returns the stored release date string.
+     */
+    public function getReleaseDate(): ?string
+    {
+        return $this->releaseDate;
+    }
+
+    /**
+     * Sets the release date string (YYYY[-MM[-DD]]).
+     */
+    public function setReleaseDate(?string $releaseDate): void
+    {
+        $this->releaseDate = $releaseDate;
+    }
+
+    /**
+     * Returns the total number of tracks.
+     */
+    public function getTotalTracks(): int
+    {
+        return $this->totalTracks;
+    }
+
+    /**
+     * Sets the track count.
+     */
+    public function setTotalTracks(int $totalTracks): void
+    {
+        $this->totalTracks = $totalTracks;
+    }
+
+    /**
+     * Returns the preferred cover art URL.
+     */
+    public function getCoverUrl(): ?string
+    {
+        return $this->coverUrl;
+    }
+
+    /**
+     * Sets the preferred cover art URL.
+     */
+    public function setCoverUrl(?string $coverUrl): void
+    {
+        $this->coverUrl = $coverUrl;
+    }
+
+    /**
+     * Returns an external link (defaults to Spotify).
+     */
+    public function getExternalUrl(): ?string
+    {
+        return $this->externalUrl;
+    }
+
+    /**
+     * Sets the external reference link.
+     */
+    public function setExternalUrl(?string $externalUrl): void
+    {
+        $this->externalUrl = $externalUrl;
+    }
+
+    /**
+     * Returns the user that created the album, when applicable.
+     */
+    public function getCreatedBy(): ?User
+    {
+        return $this->createdBy;
+    }
+
+    /**
+     * Returns the locally stored cover image path for user albums.
+     */
+    public function getCoverImagePath(): ?string
+    {
+        return $this->coverImagePath;
+    }
+
+    /**
+     * Updates the locally stored cover image path for user albums.
+     */
+    public function setCoverImagePath(?string $coverImagePath): void
+    {
+        $this->coverImagePath = $coverImagePath;
+    }
+
+    /**
+     * Sets the owner responsible for the album.
+     */
+    public function setCreatedBy(?User $user): void
+    {
+        $this->createdBy = $user;
+    }
+
+    /**
+     * Returns the creation timestamp.
+     */
+    public function getCreatedAt(): ?\DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    /**
+     * Returns the last update timestamp.
+     */
+    public function getUpdatedAt(): ?\DateTimeImmutable
+    {
+        return $this->updatedAt;
+    }
+
+    /**
+     * Shapes the entity to the payload Twig templates expect.
      *
      * @return array<string,mixed>
      */
     public function toTemplateArray(): array
     {
         $images = [];
-        if ($this->coverUrl) {
+        $imageUrl = $this->coverUrl;
+        if ($this->source === 'user' && $this->coverImagePath) {
+            $imageUrl = $this->coverImagePath;
+        }
+        if ($imageUrl) {
             $images = [
-                ['url' => $this->coverUrl],
-                ['url' => $this->coverUrl],
+                ['url' => $imageUrl],
+                ['url' => $imageUrl],
             ];
         }
         $artists = array_map(static fn(string $n) => ['name' => $n], $this->artists);