refactor: improve docblocks and naming

Author: innocenzi

packages/mailer/src/Builder/Email.php

@@ -9,14 +9,17 @@
 use Tempest\Mail\Attachments\StorageAttachment;
 use Tempest\Mail\Content;
 use Tempest\Mail\Email as EmailInterface;
+use Tempest\Mail\EmailPriority;
 use Tempest\Mail\Envelope;
 use Tempest\Mail\GenericEmail;
-use Tempest\Mail\Priority;
 use Tempest\Support\Arr;
 use Tempest\Support\Arr\ArrayInterface;
 use Tempest\View\View;
 use UnitEnum;
 
+/**
+ * A builder class for creating email objects.
+ */
 final class Email
 {
     public function __construct(
@@ -28,7 +31,7 @@ public function __construct(
         private(set) ?string $subject = null,
         private(set) null|string|View $html = null,
         private(set) ?string $text = null,
-        private(set) Priority|int $priority = Priority::NORMAL,
+        private(set) EmailPriority|int $priority = EmailPriority::NORMAL,
         private(set) array $headers = [],
         private(set) array $attachments = [],
     ) {}
@@ -116,7 +119,7 @@ public function text(string $text): self
     /**
      * Defines the priority of the email.
      */
-    public function priority(Priority|int $priority): self
+    public function priority(EmailPriority|int $priority): self
     {
         $this->priority = $priority;
 
@@ -183,7 +186,7 @@ public function make(): EmailInterface
                 bcc: Arr\wrap($this->bcc),
                 replyTo: Arr\wrap($this->replyTo),
                 priority: is_int($this->priority)
-                    ? Priority::from($this->priority)
+                    ? EmailPriority::from($this->priority)
                     : $this->priority,
                 headers: $this->headers,
             ),

packages/mailer/src/Email.php

@@ -2,6 +2,9 @@
 
 namespace Tempest\Mail;
 
+/**
+ * Represents an email.
+ */
 interface Email
 {
     /**

packages/mailer/src/EmailPriority.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Tempest\Mail;
+
+enum EmailPriority: int
+{
+    /**
+     * Indicates to email services that immediate attention is required.
+     */
+    case HIGHEST = 1;
+
+    /**
+     * Indicates to email services that this email is important, but not critical.
+     */
+    case HIGH = 2;
+
+    /**
+     * The default priority for regular emails.
+     */
+    case NORMAL = 3;
+
+    /**
+     * Indicates to email services that this email is not important and may be read later.
+     */
+    case LOW = 4;
+
+    /**
+     * Indicates to email services that this email is not important.
+     */
+    case LOWEST = 5;
+}

packages/mailer/src/Envelope.php

@@ -15,6 +15,6 @@ public function __construct(
         public null|string|array|Address $bcc = null,
         public null|string|array|Address $replyTo = null,
         public array $headers = [],
-        public Priority $priority = Priority::NORMAL,
+        public EmailPriority $priority = EmailPriority::NORMAL,
     ) {}
 }

packages/mailer/src/Priority.php

@@ -9,7 +9,7 @@
 use Symfony\Component\Mime\Part\DataPart;
 use Tempest\Mail\Address;
 use Tempest\Mail\Email;
-use Tempest\Mail\Priority;
+use Tempest\Mail\EmailPriority;
 use Tempest\Mail\SentEmail;
 use Tempest\Support\Arr;
 
@@ -154,9 +154,9 @@ public function assertNotBlindCarbonCopy(string|array $addresses): self
     /**
      * Asserts that the email has the given priority.
      */
-    public function assertPriority(null|int|Priority $priority): self
+    public function assertPriority(null|int|EmailPriority $priority): self
     {
-        if ($priority instanceof Priority) {
+        if ($priority instanceof EmailPriority) {
             $priority = $priority->value;
         }
 

packages/mailer/src/Testing/SentTestingEmail.php

@@ -7,10 +7,10 @@
 use Tempest\Mail\Attachments\FileAttachment;
 use Tempest\Mail\Attachments\StorageAttachment;
 use Tempest\Mail\Content;
+use Tempest\Mail\EmailPriority;
 use Tempest\Mail\Envelope;
 use Tempest\Mail\GenericEmail;
 use Tempest\Mail\Mailer;
-use Tempest\Mail\Priority;
 use Tempest\Mail\Testing\SentTestingEmail;
 use Tempest\Mail\Testing\TestingAttachment;
 use Tempest\Mail\Testing\TestingMailer;
@@ -78,7 +78,7 @@ public function test_sent_email_assertions(): void
         $sent->assertFrom('[email protected]');
         $sent->assertNotFrom('[email protected]');
 
-        $sent->assertPriority(Priority::NORMAL);
+        $sent->assertPriority(EmailPriority::NORMAL);
 
         $sent->assertHasHeader('X-Foo');
         $sent->assertHasHeader('X-Foo', 'bar');