Refactor Email class to support unique email normalization and add provider-specific handling; remove deprecated sources.php file and update README badges for CI workflows.

Author: eldadfux

README.md

@@ -1,6 +1,8 @@
 # Utopia Emails
 
-[![Build Status](https://travis-ci.org/utopia-php/emails.svg?branch=master)](https://travis-ci.com/utopia-php/emails)
+[![Tests](https://github.com/utopia-php/emails/workflows/Tests/badge.svg)](https://github.com/utopia-php/emails/actions/workflows/test.yml)
+[![Linter](https://github.com/utopia-php/emails/workflows/Linter/badge.svg)](https://github.com/utopia-php/emails/actions/workflows/linter.yml)
+[![CodeQL](https://github.com/utopia-php/emails/workflows/CodeQL/badge.svg)](https://github.com/utopia-php/emails/actions/workflows/codeql-analysis.yml)
 ![Total Downloads](https://img.shields.io/packagist/dt/utopia-php/emails.svg)
 [![Discord](https://img.shields.io/discord/564160730845151244)](https://appwrite.io/discord)
 

composer.json

@@ -8,10 +8,6 @@
       {
           "name": "Eldad Fux",
           "email": "[email protected]"
-      },
-      {
-          "name": "Wess Cope",
-          "email": "[email protected]"
       }
   ],
   "autoload": {

data/sources.php

@@ -3,6 +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;
 
 class Email
 {
@@ -58,6 +66,13 @@ class Email
      */
     protected static $disposableDomains = null;
 
+    /**
+     * Email providers
+     *
+     * @var Provider[]
+     */
+    protected static $providers = null;
+
     /**
      * Email constructor.
      */
@@ -268,6 +283,93 @@ public function normalize(): string
         return $this->email;
     }
 
+    /**
+     * Get unique 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
+    {
+        $provider = $this->getProviderForDomain($this->domain);
+        $normalized = $provider->normalize($this->local, $this->domain);
+
+        return $normalized['local'].'@'.$normalized['domain'];
+    }
+
+    /**
+     * Check if the email domain is supported for normalization
+     */
+    public function isNormalizationSupported(): bool
+    {
+        return $this->isDomainSupported($this->domain);
+    }
+
+    /**
+     * Get the canonical domain for this email
+     */
+    public function getCanonicalDomain(): ?string
+    {
+        $provider = $this->getProviderForDomain($this->domain);
+
+        // Only return canonical domain if it's not the generic provider
+        if (! $provider instanceof Generic) {
+            return $provider->getCanonicalDomain();
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the appropriate provider for a given domain
+     */
+    protected function getProviderForDomain(string $domain): Provider
+    {
+        if (self::$providers === null) {
+            self::$providers = [
+                new Gmail,
+                new Outlook,
+                new Yahoo,
+                new Icloud,
+                new Protonmail,
+                new Fastmail,
+            ];
+        }
+
+        foreach (self::$providers as $provider) {
+            if ($provider->supports($domain)) {
+                return $provider;
+            }
+        }
+
+        // Return generic provider if no specific provider found
+        return new Generic;
+    }
+
+    /**
+     * Check if a domain is supported by any provider
+     */
+    protected function isDomainSupported(string $domain): bool
+    {
+        if (self::$providers === null) {
+            self::$providers = [
+                new Gmail,
+                new Outlook,
+                new Yahoo,
+                new Icloud,
+                new Protonmail,
+                new Fastmail,
+            ];
+        }
+
+        foreach (self::$providers as $provider) {
+            if ($provider->supports($domain)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Get email in different formats
      */

src/Emails/Email.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Utopia\Emails\Normalizer;
+
+/**
+ * Abstract Email Provider
+ *
+ * Base class for email provider normalization
+ */
+abstract class Provider
+{
+    /**
+     * Check if this provider supports the given domain
+     */
+    abstract public function supports(string $domain): bool;
+
+    /**
+     * Normalize 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
+     */
+    abstract public function normalize(string $local, string $domain): array;
+
+    /**
+     * Get the canonical domain for this provider
+     */
+    abstract public function getCanonicalDomain(): string;
+
+    /**
+     * Get all supported domains for this provider
+     */
+    abstract public function getSupportedDomains(): array;
+
+    /**
+     * Remove plus addressing from local part
+     */
+    protected function removePlusAddressing(string $local): string
+    {
+        $plusPos = strpos($local, '+');
+        if ($plusPos !== false && $plusPos > 0) {
+            return substr($local, 0, $plusPos);
+        }
+
+        return $local;
+    }
+
+    /**
+     * Remove all dots from local part
+     */
+    protected function removeDots(string $local): string
+    {
+        return str_replace('.', '', $local);
+    }
+
+    /**
+     * Remove all hyphens from local part
+     */
+    protected function removeHyphens(string $local): string
+    {
+        return str_replace('-', '', $local);
+    }
+
+    /**
+     * Convert local part to lowercase
+     */
+    protected function toLowerCase(string $local): string
+    {
+        return strtolower($local);
+    }
+}

src/Emails/Normalizer/Provider.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Utopia\Emails\Normalizer\Providers;
+
+use Utopia\Emails\Normalizer\Provider;
+
+/**
+ * Fastmail
+ *
+ * Handles Fastmail email normalization
+ * - Removes plus addressing
+ * - Preserves dots and hyphens in local part
+ * - Normalizes to fastmail.com domain
+ */
+class Fastmail extends Provider
+{
+    private const SUPPORTED_DOMAINS = ['fastmail.com', 'fastmail.fm'];
+
+    private const CANONICAL_DOMAIN = 'fastmail.com';
+
+    public function supports(string $domain): bool
+    {
+        return in_array($domain, self::SUPPORTED_DOMAINS, true);
+    }
+
+    public function normalize(string $local, string $domain): array
+    {
+        // Convert to lowercase
+        $normalizedLocal = $this->toLowerCase($local);
+
+        // Check if there's plus addressing
+        $hasPlus = strpos($normalizedLocal, '+') !== false && strpos($normalizedLocal, '+') > 0;
+
+        // Remove plus addressing (everything after +)
+        $normalizedLocal = $this->removePlusAddressing($normalizedLocal);
+
+        // Remove dots only if there was plus addressing (Fastmail treats dots as aliases only with plus)
+        if ($hasPlus) {
+            $normalizedLocal = $this->removeDots($normalizedLocal);
+        }
+
+        return [
+            'local' => $normalizedLocal,
+            'domain' => self::CANONICAL_DOMAIN,
+        ];
+    }
+
+    public function getCanonicalDomain(): string
+    {
+        return self::CANONICAL_DOMAIN;
+    }
+
+    public function getSupportedDomains(): array
+    {
+        return self::SUPPORTED_DOMAINS;
+    }
+}

src/Emails/Normalizer/Providers/Fastmail.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Utopia\Emails\Normalizer\Providers;
+
+use Utopia\Emails\Normalizer\Provider;
+
+/**
+ * Generic
+ *
+ * Handles generic email normalization for unsupported providers
+ * - Only removes plus addressing
+ * - Preserves all other characters
+ */
+class Generic extends Provider
+{
+    public function supports(string $domain): bool
+    {
+        // Generic provider supports all domains
+        return true;
+    }
+
+    public function normalize(string $local, string $domain): array
+    {
+        // Convert to lowercase
+        $normalizedLocal = $this->toLowerCase($local);
+
+        // Check if there's plus addressing
+        $hasPlus = strpos($normalizedLocal, '+') !== false && strpos($normalizedLocal, '+') > 0;
+
+        // Remove plus addressing (everything after +)
+        $normalizedLocal = $this->removePlusAddressing($normalizedLocal);
+
+        // Remove dots and hyphens only if there was plus addressing (generic providers treat these as aliases only with plus)
+        if ($hasPlus) {
+            $normalizedLocal = $this->removeDots($normalizedLocal);
+            $normalizedLocal = $this->removeHyphens($normalizedLocal);
+        }
+
+        return [
+            'local' => $normalizedLocal,
+            'domain' => $domain,
+        ];
+    }
+
+    public function getCanonicalDomain(): string
+    {
+        // Generic provider doesn't have a canonical domain
+        return '';
+    }
+
+    public function getSupportedDomains(): array
+    {
+        // Generic provider supports all domains
+        return [];
+    }
+}