Refactor Email class to implement canonical email normalization, replacing deprecated methods and introducing a new Canonicals namespace. Update README and tests to reflect changes in method names and functionality.

Author: eldadfux

README.md

@@ -30,8 +30,8 @@ $email = new Email('[email protected]');
 $email->get(); // [email protected]
 $email->getLocal(); // user
 $email->getDomain(); // example.com
-$email->getLocalOnly(); // user
-$email->getDomainOnly(); // example.com
+$email->getLocal(); // user
+$email->getDomain(); // example.com
 $email->isValid(); // true
 $email->hasValidLocal(); // true
 $email->hasValidDomain(); // true
@@ -89,7 +89,6 @@ The Email class provides the following constants for email formatting:
 * **get()** - Return full email address.
 * **getLocal()** - Return local part (before @).
 * **getDomain()** - Return domain part (after @).
-* **getLocalOnly()** - Return email without domain part (local only).
 * **getDomainOnly()** - Return email without local part (domain only).
 * **isValid()** - Check if email is valid format.
 * **hasValidLocal()** - Check if email has valid local part.

src/Emails/Normalizer/Provider.php src/Emails/Canonicals/Provider.phpsrc/Emails/Normalizer/Provider.php renamed to src/Emails/Canonicals/Provider.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Utopia\Emails\Normalizer;
+namespace Utopia\Emails\Canonicals;
 
 /**
  * Abstract Email Provider
@@ -15,13 +15,13 @@ abstract class Provider
     abstract public function supports(string $domain): bool;
 
     /**
-     * Normalize the email address according to provider rules
+     * Get the canonical form of the email address according to provider rules
      *
      * @param  string  $local  The local part of the email (before @)
      * @param  string  $domain  The domain part of the email (after @)
-     * @return array Array with 'local' and 'domain' keys containing normalized values
+     * @return array Array with 'local' and 'domain' keys containing canonical values
      */
-    abstract public function normalize(string $local, string $domain): array;
+    abstract public function getCanonical(string $local, string $domain): array;
 
     /**
      * Get the canonical domain for this provider

…Emails/Normalizer/Providers/Fastmail.php …Emails/Canonicals/Providers/Fastmail.phpsrc/Emails/Normalizer/Providers/Fastmail.php renamed to src/Emails/Canonicals/Providers/Fastmail.php src/Emails/Normalizer/Providers/Fastmail.php renamed to src/Emails/Canonicals/Providers/Fastmail.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * Fastmail
@@ -23,7 +23,7 @@ public function supports(string $domain): bool
         return in_array($domain, self::SUPPORTED_DOMAINS, true);
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

…/Emails/Normalizer/Providers/Generic.php …/Emails/Canonicals/Providers/Generic.phpsrc/Emails/Normalizer/Providers/Generic.php renamed to src/Emails/Canonicals/Providers/Generic.php src/Emails/Normalizer/Providers/Generic.php renamed to src/Emails/Canonicals/Providers/Generic.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * Generic
@@ -19,7 +19,7 @@ public function supports(string $domain): bool
         return true;
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

src/Emails/Normalizer/Providers/Gmail.php src/Emails/Canonicals/Providers/Gmail.phpsrc/Emails/Normalizer/Providers/Gmail.php renamed to src/Emails/Canonicals/Providers/Gmail.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * Gmail
@@ -23,7 +23,7 @@ public function supports(string $domain): bool
         return in_array($domain, self::SUPPORTED_DOMAINS, true);
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

…c/Emails/Normalizer/Providers/Icloud.php …c/Emails/Canonicals/Providers/Icloud.phpsrc/Emails/Normalizer/Providers/Icloud.php renamed to src/Emails/Canonicals/Providers/Icloud.php src/Emails/Normalizer/Providers/Icloud.php renamed to src/Emails/Canonicals/Providers/Icloud.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * iCloud
@@ -23,7 +23,7 @@ public function supports(string $domain): bool
         return in_array($domain, self::SUPPORTED_DOMAINS, true);
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

…/Emails/Normalizer/Providers/Outlook.php …/Emails/Canonicals/Providers/Outlook.phpsrc/Emails/Normalizer/Providers/Outlook.php renamed to src/Emails/Canonicals/Providers/Outlook.php src/Emails/Normalizer/Providers/Outlook.php renamed to src/Emails/Canonicals/Providers/Outlook.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * Outlook
@@ -26,7 +26,7 @@ public function supports(string $domain): bool
         return in_array($domain, self::SUPPORTED_DOMAINS, true);
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

…ails/Normalizer/Providers/Protonmail.php …ails/Canonicals/Providers/Protonmail.phpsrc/Emails/Normalizer/Providers/Protonmail.php renamed to src/Emails/Canonicals/Providers/Protonmail.php src/Emails/Normalizer/Providers/Protonmail.php renamed to src/Emails/Canonicals/Providers/Protonmail.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * ProtonMail
@@ -23,7 +23,7 @@ public function supports(string $domain): bool
         return in_array($domain, self::SUPPORTED_DOMAINS, true);
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

src/Emails/Normalizer/Providers/Yahoo.php src/Emails/Canonicals/Providers/Yahoo.phpsrc/Emails/Normalizer/Providers/Yahoo.php renamed to src/Emails/Canonicals/Providers/Yahoo.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Utopia\Emails\Normalizer\Providers;
+namespace Utopia\Emails\Canonicals\Providers;
 
-use Utopia\Emails\Normalizer\Provider;
+use Utopia\Emails\Canonicals\Provider;
 
 /**
  * Yahoo
@@ -26,7 +26,7 @@ public function supports(string $domain): bool
         return in_array($domain, self::SUPPORTED_DOMAINS, true);
     }
 
-    public function normalize(string $local, string $domain): array
+    public function getCanonical(string $local, string $domain): array
     {
         // Convert to lowercase
         $normalizedLocal = $this->toLowerCase($local);

src/Emails/Email.php

@@ -3,14 +3,14 @@
 namespace Utopia\Emails;
 
 use Exception;
-use Utopia\Emails\Normalizer\Provider;
-use Utopia\Emails\Normalizer\Providers\Fastmail;
-use Utopia\Emails\Normalizer\Providers\Generic;
-use Utopia\Emails\Normalizer\Providers\Gmail;
-use Utopia\Emails\Normalizer\Providers\Icloud;
-use Utopia\Emails\Normalizer\Providers\Outlook;
-use Utopia\Emails\Normalizer\Providers\Protonmail;
-use Utopia\Emails\Normalizer\Providers\Yahoo;
+use Utopia\Emails\Canonicals\Provider;
+use Utopia\Emails\Canonicals\Providers\Fastmail;
+use Utopia\Emails\Canonicals\Providers\Generic;
+use Utopia\Emails\Canonicals\Providers\Gmail;
+use Utopia\Emails\Canonicals\Providers\Icloud;
+use Utopia\Emails\Canonicals\Providers\Outlook;
+use Utopia\Emails\Canonicals\Providers\Protonmail;
+use Utopia\Emails\Canonicals\Providers\Yahoo;
 
 class Email
 {
@@ -135,22 +135,6 @@ public function getDomain(): string
         return $this->domain;
     }
 
-    /**
-     * Return email without local part (domain only)
-     */
-    public function getDomainOnly(): string
-    {
-        return $this->domain;
-    }
-
-    /**
-     * Return email without domain part (local only)
-     */
-    public function getLocalOnly(): string
-    {
-        return $this->local;
-    }
-
     /**
      * Check if email is valid format
      */
@@ -289,30 +273,30 @@ public function hasSubdomain(): bool
     }
 
     /**
-     * Normalize email address (remove extra spaces, convert to lowercase)
+     * Get the email address (as provided, just lowercased and trimmed)
      */
-    public function normalize(): string
+    public function getAddress(): string
     {
         return $this->email;
     }
 
     /**
-     * Get unique email address by removing aliases and provider-specific variations
+     * Get the canonical email address by removing aliases and provider-specific variations
      * This method removes plus addressing, dot notation (for Gmail), and other aliasing techniques
      * to return the canonical form of the email address
      */
-    public function getUnique(): string
+    public function getCanonical(): string
     {
         $provider = $this->getProviderForDomain($this->domain);
-        $normalized = $provider->normalize($this->local, $this->domain);
+        $canonical = $provider->getCanonical($this->local, $this->domain);
 
-        return $normalized['local'].'@'.$normalized['domain'];
+        return $canonical['local'].'@'.$canonical['domain'];
     }
 
     /**
-     * Check if the email domain is supported for normalization
+     * Check if the email domain is supported for canonical form generation
      */
-    public function isNormalizationSupported(): bool
+    public function isCanonicalSupported(): bool
     {
         return $this->isDomainSupported($this->domain);
     }