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);

src/Entity/Review.php

@@ -7,6 +7,9 @@ use App\Entity\Album;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\Validator\Constraints as Assert;
 
+/**
+ * Review captures a user-authored rating and narrative about an album.
+ */
 #[ORM\Entity(repositoryClass: ReviewRepository::class)]
 #[ORM\Table(name: 'reviews')]
 #[ORM\HasLifecycleCallbacks]
@@ -45,6 +48,9 @@ class Review
     #[ORM\Column(type: 'datetime_immutable')]
     private ?\DateTimeImmutable $updatedAt = null;
 
+    /**
+     * Sets timestamps prior to the first persist.
+     */
     #[ORM\PrePersist]
     public function onPrePersist(): void
     {
@@ -53,25 +59,118 @@ class Review
         $this->updatedAt = $now;
     }
 
+    /**
+     * Updates the modified timestamp before every update.
+     */
     #[ORM\PreUpdate]
     public function onPreUpdate(): void
     {
         $this->updatedAt = new \DateTimeImmutable();
     }
 
-    public function getId(): ?int { return $this->id; }
-    public function getAuthor(): ?User { return $this->author; }
-    public function setAuthor(User $author): void { $this->author = $author; }
-    public function getAlbum(): ?Album { return $this->album; }
-    public function setAlbum(Album $album): void { $this->album = $album; }
-    public function getTitle(): string { return $this->title; }
-    public function setTitle(string $title): void { $this->title = $title; }
-    public function getContent(): string { return $this->content; }
-    public function setContent(string $content): void { $this->content = $content; }
-    public function getRating(): int { return $this->rating; }
-    public function setRating(int $rating): void { $this->rating = $rating; }
-    public function getCreatedAt(): ?\DateTimeImmutable { return $this->createdAt; }
-    public function getUpdatedAt(): ?\DateTimeImmutable { return $this->updatedAt; }
+    /**
+     * Returns the database identifier.
+     */
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    /**
+     * Returns the authoring user.
+     */
+    public function getAuthor(): ?User
+    {
+        return $this->author;
+    }
+
+    /**
+     * Assigns the authoring user.
+     */
+    public function setAuthor(User $author): void
+    {
+        $this->author = $author;
+    }
+
+    /**
+     * Returns the reviewed album.
+     */
+    public function getAlbum(): ?Album
+    {
+        return $this->album;
+    }
+
+    /**
+     * Assigns the reviewed album.
+     */
+    public function setAlbum(Album $album): void
+    {
+        $this->album = $album;
+    }
+
+    /**
+     * Returns the short review title.
+     */
+    public function getTitle(): string
+    {
+        return $this->title;
+    }
+
+    /**
+     * Sets the short review title.
+     */
+    public function setTitle(string $title): void
+    {
+        $this->title = $title;
+    }
+
+    /**
+     * Returns the long-form review content.
+     */
+    public function getContent(): string
+    {
+        return $this->content;
+    }
+
+    /**
+     * Sets the review content body.
+     */
+    public function setContent(string $content): void
+    {
+        $this->content = $content;
+    }
+
+    /**
+     * Returns the 1-10 numeric rating.
+     */
+    public function getRating(): int
+    {
+        return $this->rating;
+    }
+
+    /**
+     * Assigns the 1-10 numeric rating.
+     */
+    public function setRating(int $rating): void
+    {
+        $this->rating = $rating;
+    }
+
+    /**
+     * Returns the creation timestamp.
+     */
+    public function getCreatedAt(): ?\DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    /**
+     * Returns the last updated timestamp.
+     */
+    public function getUpdatedAt(): ?\DateTimeImmutable
+    {
+        return $this->updatedAt;
+    }
 }
 
 

src/Entity/Setting.php

@@ -6,6 +6,9 @@ use App\Repository\SettingRepository;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\Validator\Constraints as Assert;
 
+/**
+ * Setting stores lightweight key/value configuration entries.
+ */
 #[ORM\Entity(repositoryClass: SettingRepository::class)]
 #[ORM\Table(name: 'settings')]
 #[ORM\UniqueConstraint(name: 'uniq_setting_name', columns: ['name'])]
@@ -23,11 +26,45 @@ class Setting
     #[ORM\Column(type: 'text', nullable: true)]
     private ?string $value = null;
 
-    public function getId(): ?int { return $this->id; }
-    public function getName(): string { return $this->name; }
-    public function setName(string $name): void { $this->name = $name; }
-    public function getValue(): ?string { return $this->value; }
-    public function setValue(?string $value): void { $this->value = $value; }
+    /**
+     * Returns the unique identifier.
+     */
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    /**
+     * Returns the configuration key.
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Sets the configuration key.
+     */
+    public function setName(string $name): void
+    {
+        $this->name = $name;
+    }
+
+    /**
+     * Returns the stored configuration value.
+     */
+    public function getValue(): ?string
+    {
+        return $this->value;
+    }
+
+    /**
+     * Sets the stored configuration value.
+     */
+    public function setValue(?string $value): void
+    {
+        $this->value = $value;
+    }
 }
 
 

src/Entity/User.php

@@ -9,6 +9,9 @@ use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Component\Validator\Constraints as Assert;
 
+/**
+ * User models an authenticated account that can create reviews and albums.
+ */
 #[ORM\Entity(repositoryClass: UserRepository::class)]
 #[ORM\Table(name: 'users')]
 #[UniqueEntity(fields: ['email'], message: 'This email is already registered.')]
@@ -40,30 +43,49 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
     #[Assert\Length(max: 120)]
     private ?string $displayName = null;
 
+    #[ORM\Column(type: 'string', length: 255, nullable: true)]
+    private ?string $profileImagePath = null;
+
+    /**
+     * Returns the database identifier.
+     */
     public function getId(): ?int
     {
         return $this->id;
     }
 
+    /**
+     * Returns the normalized email address.
+     */
     public function getEmail(): string
     {
         return $this->email;
     }
 
+    /**
+     * Sets and normalizes the email address.
+     */
     public function setEmail(string $email): void
     {
         $this->email = strtolower($email);
     }
 
+    /**
+     * Symfony security identifier alias for the email.
+     */
     public function getUserIdentifier(): string
     {
         return $this->email;
     }
 
+    /**
+     * Returns the unique role list plus the implicit ROLE_USER.
+     *
+     * @return list<string>
+     */
     public function getRoles(): array
     {
         $roles = $this->roles;
-        // guarantee every user at least has ROLE_USER
         if (!in_array('ROLE_USER', $roles, true)) {
             $roles[] = 'ROLE_USER';
         }
@@ -71,6 +93,8 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
     }
 
     /**
+     * Replaces the granted role list.
+     *
      * @param list<string> $roles
      */
     public function setRoles(array $roles): void
@@ -78,6 +102,9 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
         $this->roles = array_values(array_unique($roles));
     }
 
+    /**
+     * Adds a single role if not already present.
+     */
     public function addRole(string $role): void
     {
         $roles = $this->getRoles();
@@ -87,30 +114,55 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
         $this->roles = $roles;
     }
 
+    /**
+     * Returns the hashed password string.
+     */
     public function getPassword(): string
     {
         return $this->password;
     }
 
+    /**
+     * Stores the hashed password string.
+     */
     public function setPassword(string $hashedPassword): void
     {
         $this->password = $hashedPassword;
     }
 
+    /**
+     * Removes any sensitive transient data (no-op here).
+     */
     public function eraseCredentials(): void
     {
         // no-op
     }
 
+    /**
+     * Returns the optional display name.
+     */
     public function getDisplayName(): ?string
     {
         return $this->displayName;
     }
 
+    /**
+     * Sets the optional display name.
+     */
     public function setDisplayName(?string $displayName): void
     {
         $this->displayName = $displayName;
     }
+
+    public function getProfileImagePath(): ?string
+    {
+        return $this->profileImagePath;
+    }
+
+    public function setProfileImagePath(?string $profileImagePath): void
+    {
+        $this->profileImagePath = $profileImagePath;
+    }
 }