From fbcafb8f1d3a9afae7f1a883aba659db5e6ee53f Mon Sep 17 00:00:00 2001
From: Alex Cabal <alex@alexcabal.com>
Date: Thu, 27 Mar 2025 16:46:05 -0500
Subject: [PATCH] Improve type hints

---
 lib/Artist.php                 |  8 ++++----
 lib/Artwork.php                |  4 ++--
 lib/Benefits.php               |  4 ++--
 lib/Collection.php             |  2 +-
 lib/Contributor.php            |  2 +-
 lib/DonationDrive.php          |  8 ++++----
 lib/Ebook.php                  | 14 +++++++-------
 lib/EbookPlaceholder.php       |  4 ++--
 lib/NewsletterSubscription.php |  2 +-
 lib/Patron.php                 |  2 +-
 lib/Poll.php                   |  4 ++--
 lib/PollItem.php               |  2 +-
 lib/PollVote.php               |  2 +-
 lib/Project.php                |  8 ++++----
 lib/Session.php                |  2 +-
 lib/Tag.php                    |  4 ++--
 lib/User.php                   | 18 +++++++++---------
 17 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/lib/Artist.php b/lib/Artist.php
index 6feba509..8af45ca1 100644
--- a/lib/Artist.php
+++ b/lib/Artist.php
@@ -3,11 +3,11 @@ use Safe\DateTimeImmutable;
 
 /**
  * @property ?int $DeathYear
- * @property ?string $UrlName
- * @property ?string $Url
- * @property string $DeleteUrl
+ * @property string $UrlName
+ * @property-read string $Url
+ * @property-read string $DeleteUrl
  * @property array<string> $AlternateNames
- * @property string $AlternateNamesString
+ * @property-read string $AlternateNamesString
  */
 class Artist{
 	use Traits\Accessor;
diff --git a/lib/Artwork.php b/lib/Artwork.php
index fa257e63..3aecb008 100644
--- a/lib/Artwork.php
+++ b/lib/Artwork.php
@@ -12,8 +12,8 @@ use function Safe\unlink;
 
 /**
  * @property string $UrlName
- * @property string $Url
- * @property string $EditUrl
+ * @property-read string $Url
+ * @property-read string $EditUrl
  * @property-read array<ArtworkTag> $Tags
  * @property-write array<ArtworkTag>|string $Tags
  * @property Artist $Artist
diff --git a/lib/Benefits.php b/lib/Benefits.php
index 4b39fc76..8d6f26b6 100644
--- a/lib/Benefits.php
+++ b/lib/Benefits.php
@@ -1,7 +1,7 @@
 <?
 /**
- * @property bool $HasBenefits Are any of the benefits in this object **`TRUE`**?
- * @property bool $RequiresPassword Do any of the benefits in this object require the `User` to have a password set?
+ * @property-read bool $HasBenefits Are any of the benefits in this object **`TRUE`**?
+ * @property-read bool $RequiresPassword Do any of the benefits in this object require the `User` to have a password set?
  */
 class Benefits{
 	use Traits\Accessor;
diff --git a/lib/Collection.php b/lib/Collection.php
index e6386c1d..0fe5ab65 100644
--- a/lib/Collection.php
+++ b/lib/Collection.php
@@ -2,7 +2,7 @@
 use function Safe\preg_replace;
 
 /**
- * @property string $Url
+ * @property-read string $Url
  * @property array<Ebook> $Ebooks
  */
 class Collection{
diff --git a/lib/Contributor.php b/lib/Contributor.php
index 21bbc483..220bd129 100644
--- a/lib/Contributor.php
+++ b/lib/Contributor.php
@@ -2,7 +2,7 @@
 use function Safe\preg_match;
 
 /**
- * @property ?string $Url The URL of this `Contributor` if their MARC role is `Enums\MarcRole::Author`, or **null** otherwise.
+ * @property-read ?string $Url The URL of this `Contributor` if their MARC role is `Enums\MarcRole::Author`, or `null` otherwise.
  */
 class Contributor{
 	use Traits\Accessor;
diff --git a/lib/DonationDrive.php b/lib/DonationDrive.php
index 228ad755..6def37ac 100644
--- a/lib/DonationDrive.php
+++ b/lib/DonationDrive.php
@@ -2,10 +2,10 @@
 use Safe\DateTimeImmutable;
 
 /**
- * @property int $DonationCount
- * @property int $StretchDonationCount
- * @property bool $IsStretchEnabled
- * @property int $TargetDonationCount
+ * @property-read int $DonationCount
+ * @property-read int $StretchDonationCount
+ * @property-read bool $IsStretchEnabled
+ * @property-read int $TargetDonationCount
  */
 class DonationDrive{
 	use Traits\Accessor;
diff --git a/lib/Ebook.php b/lib/Ebook.php
index 86ebf677..114f65fc 100644
--- a/lib/Ebook.php
+++ b/lib/Ebook.php
@@ -22,9 +22,9 @@ use function Safe\shell_exec;
  * @property ?array<string> $TocEntries A list of non-Roman ToC entries *only if* the work has the `se:is-a-collection` metadata element; `null` otherwise.
  * @property string $Url The relative URL of this ebook, like `/ebooks/...`.
  * @property string $FullUrl The absolute URL of this ebook, like `https://standardebooks.org/ebooks/...`.
- * @property string $EditUrl
- * @property string $DeleteUrl
- * @property bool $HasDownloads
+ * @property-read string $EditUrl
+ * @property-read string $DeleteUrl
+ * @property-read bool $HasDownloads
  * @property string $UrlSafeIdentifier
  * @property string $HeroImageUrl
  * @property string $HeroImageAvifUrl
@@ -45,10 +45,10 @@ use function Safe\shell_exec;
  * @property string $TextSinglePageUrl
  * @property string $TextSinglePageSizeFormatted
  * @property ?EbookPlaceholder $EbookPlaceholder
- * @property array<Project> $Projects
- * @property array<Project> $PastProjects
- * @property ?Project $ProjectInProgress
- * @property ?Artwork $Artwork
+ * @property-read array<Project> $Projects
+ * @property-read array<Project> $PastProjects
+ * @property-read ?Project $ProjectInProgress
+ * @property-read ?Artwork $Artwork
  */
 final class Ebook{
 	use Traits\Accessor;
diff --git a/lib/EbookPlaceholder.php b/lib/EbookPlaceholder.php
index d0618f81..50acc518 100644
--- a/lib/EbookPlaceholder.php
+++ b/lib/EbookPlaceholder.php
@@ -1,8 +1,8 @@
 <?
 
 /**
- * @property bool $IsPublicDomain
- * @property string $TimeTillIsPublicDomain A string describing how much longer it will be before this work is in the U.S. public domain, like `3 months` or `20 years`.
+ * @property-read bool $IsPublicDomain
+ * @property-read string $TimeTillIsPublicDomain A string describing how much longer it will be before this work is in the U.S. public domain, like `3 months` or `20 years`.
  */
 class EbookPlaceholder{
 	use Traits\Accessor;
diff --git a/lib/NewsletterSubscription.php b/lib/NewsletterSubscription.php
index ee9ddd0b..40619377 100644
--- a/lib/NewsletterSubscription.php
+++ b/lib/NewsletterSubscription.php
@@ -3,7 +3,7 @@ use Safe\DateTimeImmutable;
 
 /**
  * @property User $User
- * @property string $Url
+ * @property-read string $Url
  */
 class NewsletterSubscription{
 	use Traits\Accessor;
diff --git a/lib/Patron.php b/lib/Patron.php
index 27d3007c..46fe4863 100644
--- a/lib/Patron.php
+++ b/lib/Patron.php
@@ -3,7 +3,7 @@ use Safe\DateTimeImmutable;
 
 /**
  * @property User $User
- * @property ?Payment $LastPayment
+ * @property-read ?Payment $LastPayment
  */
 class Patron{
 	use Traits\Accessor;
diff --git a/lib/Poll.php b/lib/Poll.php
index e572d6d0..6bc1cb33 100644
--- a/lib/Poll.php
+++ b/lib/Poll.php
@@ -2,10 +2,10 @@
 use Safe\DateTimeImmutable;
 
 /**
- * @property string $Url
+ * @property-read string $Url
  * @property array<PollItem> $PollItems
  * @property array<PollItem> $PollItemsByWinner
- * @property int $VoteCount
+ * @property-read int $VoteCount
  */
 class Poll{
 	use Traits\Accessor;
diff --git a/lib/PollItem.php b/lib/PollItem.php
index 5f852107..f93cba7b 100644
--- a/lib/PollItem.php
+++ b/lib/PollItem.php
@@ -1,6 +1,6 @@
 <?
 /**
- * @property int $VoteCount
+ * @property-read int $VoteCount
  * @property Poll $Poll
  */
 class PollItem{
diff --git a/lib/PollVote.php b/lib/PollVote.php
index a5cdb42b..5771840b 100644
--- a/lib/PollVote.php
+++ b/lib/PollVote.php
@@ -4,7 +4,7 @@ use Safe\DateTimeImmutable;
 /**
  * @property User $User
  * @property PollItem $PollItem
- * @property string $Url
+ * @property-read string $Url
  */
 class PollVote{
 	use Traits\Accessor;
diff --git a/lib/Project.php b/lib/Project.php
index 84a5414a..c8f1ed84 100644
--- a/lib/Project.php
+++ b/lib/Project.php
@@ -16,12 +16,12 @@ use Safe\DateTimeImmutable;
  * @property Ebook $Ebook
  * @property User $Manager
  * @property User $Reviewer
- * @property string $Url
- * @property string $EditUrl
+ * @property-read string $Url
+ * @property-read string $EditUrl
  * @property DateTimeImmutable $LastActivityTimestamp The timestamp of the latest activity, whether it's a commit, a discussion post, or simply the started timestamp.
  * @property array<ProjectReminder> $Reminders
- * @property ?string $VcsUrlDomain
- * @property ?string $DiscussionUrlDomain
+ * @property-read ?string $VcsUrlDomain
+ * @property-read ?string $DiscussionUrlDomain
  */
 final class Project{
 	use Traits\Accessor;
diff --git a/lib/Session.php b/lib/Session.php
index 006b240c..a0b2c129 100644
--- a/lib/Session.php
+++ b/lib/Session.php
@@ -5,7 +5,7 @@ use Ramsey\Uuid\Uuid;
 use Safe\DateTimeImmutable;
 
 /**
- * @property string $Url
+ * @property-read string $Url
  */
 class Session{
 	use Traits\Accessor;
diff --git a/lib/Tag.php b/lib/Tag.php
index b36e392a..6ea366ba 100644
--- a/lib/Tag.php
+++ b/lib/Tag.php
@@ -1,6 +1,6 @@
 <?
 /**
- * @property string $Url
+ * @property-read string $Url
  */
 class Tag{
 	use Traits\Accessor;
@@ -10,5 +10,5 @@ class Tag{
 	public string $UrlName;
 	public Enums\TagType $Type;
 
-	protected string $_Url;
+	protected string $_Url; // For subclasses.
 }
diff --git a/lib/User.php b/lib/User.php
index 555dd20f..9e7309ac 100644
--- a/lib/User.php
+++ b/lib/User.php
@@ -6,15 +6,15 @@ use function Safe\preg_match;
 
 /**
  * @property array<Payment> $Payments
- * @property bool $IsRegistered A user is "registered" if they have an entry in the `Benefits` table; a password is required to log in.
+ * @property-read bool $IsRegistered A user is "registered" if they have an entry in the `Benefits` table; a password is required to log in.
  * @property Benefits $Benefits
- * @property string $Url
- * @property string $EditUrl
+ * @property-read string $Url
+ * @property-read string $EditUrl
  * @property ?Patron $Patron
  * @property ?NewsletterSubscription $NewsletterSubscription
- * @property ?Payment $LastPayment
- * @property string $DisplayName The `User`'s name, or email, or ID.
- * @property ?string $SortName The `User`'s name in an (attempted) sort order, or `null` if the `User` has no name.
+ * @property-read ?Payment $LastPayment
+ * @property-read string $DisplayName The `User`'s name, or email, or ID.
+ * @property-read ?string $SortName The `User`'s name in an (attempted) sort order, or `null` if the `User` has no name.
  */
 class User{
 	use Traits\Accessor;
@@ -50,7 +50,7 @@ class User{
 			if($this->Name !== null){
 				preg_match('/\s(?:de |de la |di |van |von )?[^\s]+$/iu', $this->Name, $lastNameMatches);
 				if(sizeof($lastNameMatches) == 0){
-					$this->SortName = $this->Name;
+					$this->_SortName = $this->Name;
 				}
 				else{
 					$lastName = trim($lastNameMatches[0]);
@@ -58,7 +58,7 @@ class User{
 					preg_match('/^(.+)' . preg_quote($lastName, '/') . '$/u', $this->Name, $firstNameMatches);
 
 					if(sizeof($firstNameMatches) == 0){
-						$this->SortName = $this->Name;
+						$this->_SortName = $this->Name;
 					}
 					else{
 						$this->_SortName = $lastName . ', ' . trim($firstNameMatches[1]);
@@ -289,7 +289,7 @@ class User{
 			elseif($this->Benefits->HasBenefits){
 				$this->Benefits->UserId = $this->UserId;
 				$this->Benefits->Create();
-				$this->IsRegistered = true;
+				$this->_IsRegistered = true;
 			}
 		}
 		catch(Exceptions\DuplicateDatabaseKeyException){