An Email Address is a common personal address for people online. More...

Collaboration diagram for ILIAS\Data\EmailAddress:

Public Member Functions
	__construct (string $address_Full)

	getAddressFull ()

	getDomainPart ()

	getLocalPart ()

	getIsAscii ()

	getIsDomainPartAscii ()

	getIsLocalPartAscii ()

	__toString ()

Protected Member Functions
	checkAscii (string $str)

	digestFullAddress (string $address)

	digestDomainPart (string $address)

	digestLocalPart (string $address)

Static Protected Member Functions
static	isAllowedIntlUnicode (string $string)

Protected Attributes
string	$addressFull

string	$domainPart

string	$localPart

bool	$isAscii

bool	$isDomainPartAscii

bool	$isLocalPartAscii

Detailed Description

An Email Address is a common personal address for people online.

This class ensures the address follows common format requirements. It also splits the address into some of the parts outlined in RFC 2822 that can then be retrieved separately. Non-ASCII characters are technically valid in the local (RFC 6531) and the domain (RFC 3490) parts, but...

in the local part they are only supported by a small amount of mailservers
in the domain part they are converted to ASCII punycode Because of this limited support, PHP's own FILTER_VALIDATE_EMAIL does not allow Unicode characters. However, we don't want to be as strict. ILIAS is used internationally where Latin-1 Supplement characters like ö, ä, ü, é, ø become more common in email addresses. Some Service Providers need to allow Japanese, Chinese and Cyrillic/Ukrainian scripts. Therefore, we allow Unicode characters covered by the Email Address Internationalization (EAI) framework. Be aware that not all email servers can process these by default and that additional steps might be necessary to enable ILIAS to send those emails. You can use isAscii() to check if an address is following the old standards and is likely supported by all servers.

Author: Ferdinand Engländer ferdi.nosp@m.nand.nosp@m..engl.nosp@m.aend.nosp@m.er@co.nosp@m.ncep.nosp@m.ts-an.nosp@m.d-tr.nosp@m.ainin.nosp@m.g.de

Definition at line 40 of file EmailAddress.php.

Constructor & Destructor Documentation

◆ __construct()

ILIAS\Data\EmailAddress::__construct ( string $address_Full )

Definition at line 50 of file EmailAddress.php.

    {
        $this->addressFull = $this->digestFullAddress($address_Full);
        $this->domainPart = $this->digestDomainPart($address_Full);
        $this->localPart = $this->digestLocalPart($address_Full);
        if ($this->isDomainPartAscii && $this->isLocalPartAscii) {
            $this->isAscii = true;
        } else {
            $this->isAscii = false;
        }
    }

References ILIAS\Data\EmailAddress\digestDomainPart(), ILIAS\Data\EmailAddress\digestFullAddress(), and ILIAS\Data\EmailAddress\digestLocalPart().

Here is the call graph for this function:

Member Function Documentation

◆ __toString()

ILIAS\Data\EmailAddress::__toString ( )

Definition at line 92 of file EmailAddress.php.

                                : string
    {
        return $this->getAddressFull();
    }

References ILIAS\Data\EmailAddress\getAddressFull().

Here is the call graph for this function:

◆ checkAscii()

ILIAS\Data\EmailAddress::checkAscii ( string $str )

protected

Definition at line 97 of file EmailAddress.php.

                                              : bool
    {
        return mb_check_encoding($str, 'ASCII');
    }

Referenced by ILIAS\Data\EmailAddress\digestDomainPart().

Here is the caller graph for this function:

◆ digestDomainPart()

ILIAS\Data\EmailAddress::digestDomainPart ( string $address )

protected

Definition at line 120 of file EmailAddress.php.

                                                        : string
    {
        [, $domain] = explode('@', $address, 2);
 
        $this->isDomainPartAscii = $this->checkAscii($domain);
 
        if ($domain === 'localhost') {
            return $domain;
        }
 
        if (preg_match('/[\p{C}\p{Z}]/u', $domain)) {
            throw new \InvalidArgumentException("Domain part contains invalid characters (e.g., whitespace or control).");
        }
 
        if (str_contains($domain, '..')) {
            throw new \InvalidArgumentException("Domain part contains consecutive dots.");
        }
 
        // not flagging double hyphens as punycode uses those
 
        if (substr_count($domain, '.') < 1) {
            throw new \InvalidArgumentException("Domain must contain at least one dot except for 'localhost'.");
        }
 
        if (strlen($domain) > 254) {
            throw new \InvalidArgumentException("Domain part exceeds 254 character limit.");
        }
 
        $labels = explode('.', $domain);
        foreach ($labels as $label) {
            if (strlen($label) > 63) {
                throw new \InvalidArgumentException("Domain label exceeds 63 character limit.");
            }
 
            if ($label === '') {
                throw new \InvalidArgumentException("Domain contains an empty label.");
            }
 
            if ($label[0] === '-' || $label[strlen($label) - 1] === '-') {
                throw new \InvalidArgumentException("Domain labels must not start or end with a hyphen.");
            }
        }
 
        return $domain;
    }

References ILIAS\Data\EmailAddress\checkAscii().

Referenced by ILIAS\Data\EmailAddress\__construct().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ digestFullAddress()

ILIAS\Data\EmailAddress::digestFullAddress ( string $address )

protected

Definition at line 102 of file EmailAddress.php.

                                                         : string
    {
        $address = trim($address);
 
        if (substr_count($address, '@') !== 1) {
            throw new \InvalidArgumentException("Email must contain exactly one '@' character.");
        }
 
        [$local, $domain] = explode('@', $address, 2);
 
        if ($local === '' || $domain === '') {
            throw new \InvalidArgumentException("Email must have non-empty local and domain parts.");
        }
 
        $this->addressFull = $address;
        return $address;
    }

Referenced by ILIAS\Data\EmailAddress\__construct().

Here is the caller graph for this function:

◆ digestLocalPart()

ILIAS\Data\EmailAddress::digestLocalPart ( string $address )

protected

Definition at line 166 of file EmailAddress.php.

                                                       : string
    {
        [$local,] = explode('@', $address, 2);
 
        if (!mb_check_encoding($local, 'UTF-8')) {
            throw new \InvalidArgumentException("Local part is not valid UTF-8.");
        }
 
        if ($local[0] === '.' || str_ends_with($local, '.')) {
            throw new \InvalidArgumentException("Local part cannot start or end with a dot.");
        }
 
        if (str_contains($local, '..')) {
            throw new \InvalidArgumentException("Local part cannot contain consecutive dots.");
        }
 
        // double quotes are allowed only as first and last character
        if (str_starts_with($local, '"') && str_ends_with($local, '"')) {
            $local_strip_quotes = substr($local, 1, -1);
        } else {
            $local_strip_quotes = $local;
        }
 
        if (preg_match('/[\x00-\x1F\x7F]/', $local_strip_quotes)) {
            throw new \InvalidArgumentException("Local part contains unsupported control characters or invalid escape sequences.");
        }
 
        // check if safe Ascii
        if (preg_match('/^[a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]+$/', $local_strip_quotes)) {
            $this->isLocalPartAscii = true;
        } else {
            $this->isLocalPartAscii = false;
        }
        // check if save Unicode
        if (!self::isAllowedIntlUnicode($local_strip_quotes)) {
            throw new \InvalidArgumentException("Local part is not a valid Unicode string.");
        }
 
        return $local;
    }

Referenced by ILIAS\Data\EmailAddress\__construct().

Here is the caller graph for this function:

◆ getAddressFull()

ILIAS\Data\EmailAddress::getAddressFull ( )

Definition at line 62 of file EmailAddress.php.

                                    : string
    {
        return $this->addressFull;
    }

References ILIAS\Data\EmailAddress\$addressFull.

Referenced by ILIAS\Data\EmailAddress\__toString().

Here is the caller graph for this function:

◆ getDomainPart()

ILIAS\Data\EmailAddress::getDomainPart ( )

Definition at line 67 of file EmailAddress.php.

                                   : string
    {
        return $this->domainPart;
    }

References ILIAS\Data\EmailAddress\$domainPart.

◆ getIsAscii()

ILIAS\Data\EmailAddress::getIsAscii ( )

Definition at line 77 of file EmailAddress.php.

                                : bool
    {
        return $this->isAscii;
    }

References ILIAS\Data\EmailAddress\$isAscii.

◆ getIsDomainPartAscii()

ILIAS\Data\EmailAddress::getIsDomainPartAscii ( )

Definition at line 82 of file EmailAddress.php.

                                          : bool
    {
        return $this->isDomainPartAscii;
    }

References ILIAS\Data\EmailAddress\$isDomainPartAscii.

◆ getIsLocalPartAscii()

ILIAS\Data\EmailAddress::getIsLocalPartAscii ( )

Definition at line 87 of file EmailAddress.php.

                                         : bool
    {
        return $this->isLocalPartAscii;
    }

References ILIAS\Data\EmailAddress\$isLocalPartAscii.

◆ getLocalPart()

ILIAS\Data\EmailAddress::getLocalPart ( )

Definition at line 72 of file EmailAddress.php.

                                  : string
    {
        return $this->localPart;
    }

References ILIAS\Data\EmailAddress\$localPart.

◆ isAllowedIntlUnicode()

static ILIAS\Data\EmailAddress::isAllowedIntlUnicode ( string $string )

staticprotected

Definition at line 207 of file EmailAddress.php.

                                                                  : bool
    {
        // Check allowed Unicode characters this includes e.g.
        //      * a-z, A-Z, 0-9
        //      * Latin accented: é, ñ, ö, č
        //      * Greek: Α, β, Ω
        //      * Cyrillic: Б, и, я
        //      * Arabic letters: ا, ب, خ
        //      * Hebrew: א, ב, ג
        //      * East Asian ideographs (CJK): 日, 本, 語, 汉, 字
        //      * Devanagari (Hindi, Marathi): अ, आ, क
        //      * Hangul (Korean): 한, 글
        //      * and more
        // \p{L} includes all characters Unicode defines as letters
        // \p{N} includes all characters Unicode defines as numbers
        // this excludes emojis and control characters which are not allowed in the local part
        if (!preg_match('/^[\p{L}\p{N}!#$%&\'*+\/=?^_`{|}~\.-]+$/u', $string)) {
            return false;
        } else {
            return true;
        }
    }

Field Documentation

◆ $addressFull

string ILIAS\Data\EmailAddress::$addressFull

protected

Definition at line 42 of file EmailAddress.php.

Referenced by ILIAS\Data\EmailAddress\getAddressFull().

◆ $domainPart

string ILIAS\Data\EmailAddress::$domainPart

protected

Definition at line 43 of file EmailAddress.php.

Referenced by ILIAS\Data\EmailAddress\getDomainPart().

◆ $isAscii

bool ILIAS\Data\EmailAddress::$isAscii

protected

Definition at line 45 of file EmailAddress.php.

Referenced by ILIAS\Data\EmailAddress\getIsAscii().

◆ $isDomainPartAscii

bool ILIAS\Data\EmailAddress::$isDomainPartAscii

protected

Definition at line 46 of file EmailAddress.php.

Referenced by ILIAS\Data\EmailAddress\getIsDomainPartAscii().

◆ $isLocalPartAscii

bool ILIAS\Data\EmailAddress::$isLocalPartAscii

protected

Definition at line 47 of file EmailAddress.php.

Referenced by ILIAS\Data\EmailAddress\getIsLocalPartAscii().

◆ $localPart

string ILIAS\Data\EmailAddress::$localPart

protected

Definition at line 44 of file EmailAddress.php.

Referenced by ILIAS\Data\EmailAddress\getLocalPart().

The documentation for this class was generated from the following file:

components/ILIAS/Data/src/EmailAddress.php

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ __toString()

◆ checkAscii()

◆ digestDomainPart()

◆ digestFullAddress()

◆ digestLocalPart()

◆ getAddressFull()

◆ getDomainPart()

◆ getIsAscii()

◆ getIsDomainPartAscii()

◆ getIsLocalPartAscii()

◆ getLocalPart()

◆ isAllowedIntlUnicode()

Field Documentation

◆ $addressFull

◆ $domainPart

◆ $isAscii

◆ $isDomainPartAscii

◆ $isLocalPartAscii

◆ $localPart