<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\tests;
use seekquarry\yioop\library\mail\MailHeaderParser;
use seekquarry\yioop\library\UnitTest;
/**
* Tests for MailHeaderParser: the parse() header-block parser,
* decodeMimeWord() RFC 2047 decoder, and splitAddresses()
* address-list splitter. All three methods are static pure
* functions of their string arguments, so each test case is
* self-contained; no setUp / tearDown is required.
*
* @author Chris Pollett
*/
class MailHeaderParserTest extends UnitTest
{
/**
* No setup state needed; the parser methods are static
* pure functions of their string arguments.
*/
public function setUp()
{
}
/**
* No teardown either; setUp does nothing.
*/
public function tearDown()
{
}
/**
* A minimal header block with three simple headers and CRLF
* terminators round-trips into a lowercase-keyed array with
* leading whitespace stripped from each value.
*/
public function parseBasicCrlfTestCase()
{
$bytes = "From: alice@example.com\r\n" .
"To: bob@example.com\r\n" .
"Subject: Hello world\r\n";
$headers = MailHeaderParser::parse($bytes);
$this->assertEqual('alice@example.com', $headers['from'],
'From header round-trips with lowercase key');
$this->assertEqual('bob@example.com', $headers['to'],
'To header round-trips with lowercase key');
$this->assertEqual('Hello world', $headers['subject'],
'Subject value has leading whitespace stripped');
}
/**
* Bare-LF line terminators are accepted as a fallback for
* sources that did not produce strict CRLF (some mailbox
* formats, some test setups).
*/
public function parseBareLfTestCase()
{
$bytes = "From: a@b\n" .
"Subject: bare-lf source\n";
$headers = MailHeaderParser::parse($bytes);
$this->assertEqual('a@b', $headers['from'],
'Bare-LF From header parses');
$this->assertEqual('bare-lf source', $headers['subject'],
'Bare-LF Subject header parses');
}
/**
* A header value continued on the next line (RFC 5322
* folding: continuation starts with whitespace) is unfolded
* into a single value with the continuation joined by a
* space.
*/
public function parseFoldedContinuationTestCase()
{
$bytes = "Subject: This is a very long subject\r\n" .
" that wraps onto a second line\r\n" .
"From: sender@example.com\r\n";
$headers = MailHeaderParser::parse($bytes);
$this->assertEqual(
'This is a very long subject ' .
'that wraps onto a second line',
$headers['subject'],
'Folded subject is unfolded with single-space join');
$this->assertEqual('sender@example.com', $headers['from'],
'Header after a fold still parses');
}
/**
* Tab-led continuation lines fold the same way as space-led
* ones (RFC 5322 LWS allows either).
*/
public function parseFoldedTabTestCase()
{
$bytes = "References: <id1@example>\r\n" .
"\t<id2@example>\r\n" .
"\t<id3@example>\r\n";
$headers = MailHeaderParser::parse($bytes);
$this->assertEqual(
'<id1@example> <id2@example> <id3@example>',
$headers['references'],
'Tab-led continuation lines fold like space-led');
}
/**
* When the same header appears twice, the parser keeps the
* later occurrence. This matches the common convention for
* Subject/From/Date that appear at most once per RFC 5322 but
* may be duplicated by buggy intermediaries.
*/
public function parseDuplicateHeaderTestCase()
{
$bytes = "Subject: first\r\n" .
"Subject: second\r\n";
$headers = MailHeaderParser::parse($bytes);
$this->assertEqual('second', $headers['subject'],
'Duplicate Subject: later occurrence wins');
}
/**
* A line with no colon is skipped without breaking the
* surrounding parse (defensive against truncated /
* malformed input).
*/
public function parseMissingColonTestCase()
{
$bytes = "From: a@b\r\n" .
"garbage-line-no-colon\r\n" .
"Subject: still parses\r\n";
$headers = MailHeaderParser::parse($bytes);
$this->assertEqual('a@b', $headers['from'],
'Header before garbage is preserved');
$this->assertEqual('still parses', $headers['subject'],
'Header after garbage is preserved');
$this->assertTrue(
!isset($headers['garbage-line-no-colon']),
'Garbage line did not synthesise a header');
}
/**
* An empty header block produces an empty array, not a
* warning or null.
*/
public function parseEmptyTestCase()
{
$headers = MailHeaderParser::parse('');
$this->assertEqual([], $headers,
'Empty input yields empty header array');
}
/**
* Plain ASCII text passes through decodeMimeWord unchanged.
*/
public function decodeMimePlainAsciiTestCase()
{
$decoded = MailHeaderParser::decodeMimeWord(
'Hello, world!');
$this->assertEqual('Hello, world!', $decoded,
'Plain ASCII passes through unchanged');
}
/**
* A single Q-encoded word with UTF-8 charset decodes to the
* expected glyph.
*/
public function decodeMimeQEncodedTestCase()
{
$decoded = MailHeaderParser::decodeMimeWord(
'=?UTF-8?Q?caf=C3=A9?=');
$this->assertEqual('café', $decoded,
'Q-encoded UTF-8 round-trips to the right glyph');
}
/**
* A single B-encoded (base64) word with UTF-8 charset
* decodes to the expected text.
*/
public function decodeMimeBEncodedTestCase()
{
/* base64("hello") = aGVsbG8= */
$decoded = MailHeaderParser::decodeMimeWord(
'=?UTF-8?B?aGVsbG8=?=');
$this->assertEqual('hello', $decoded,
'B-encoded UTF-8 round-trips');
}
/**
* Two adjacent encoded-words are concatenated WITHOUT the
* intervening whitespace per RFC 2047 Section 6.2; the
* whitespace between them is presentation, not content.
*/
public function decodeMimeAdjacentTestCase()
{
$decoded = MailHeaderParser::decodeMimeWord(
'=?UTF-8?Q?hello?= =?UTF-8?Q?_world?=');
/* the underscore in Q-encoding decodes to a space, so
the result is "hello world" with the inter-word
whitespace discarded and the encoded space honoured. */
$this->assertEqual('hello world', $decoded,
'Adjacent encoded-words drop the inter-word space');
}
/**
* Mixed content (literal text + encoded-word + literal
* text) preserves the literal pieces and decodes the
* middle.
*/
public function decodeMimeMixedTestCase()
{
$decoded = MailHeaderParser::decodeMimeWord(
'A note from =?UTF-8?Q?Andr=C3=A9?= to you');
$this->assertEqual('A note from André to you', $decoded,
'Mixed literal/encoded text preserves both');
}
/**
* A single bare address splits into a one-element list, the
* pair shape is [name='', email=bare-token].
*/
public function splitAddressesSingleTestCase()
{
$list = MailHeaderParser::splitAddresses(
'alice@example.com');
$this->assertEqual(1, count($list),
'Single bare address yields one entry');
$this->assertEqual('', $list[0][0],
'Bare address has no name component');
$this->assertEqual('alice@example.com', $list[0][1],
'Bare address surfaces as the email portion');
}
/**
* Two comma-separated bare addresses split into two entries
* with leading whitespace stripped from each.
*/
public function splitAddressesCommaTestCase()
{
$list = MailHeaderParser::splitAddresses(
'a@x.com, b@y.com');
$this->assertEqual(2, count($list),
'Two comma-separated addresses yield two entries');
$this->assertEqual('a@x.com', $list[0][1],
'First entry email matches');
$this->assertEqual('b@y.com', $list[1][1],
'Second entry email matches');
}
/**
* Display-name plus angle-bracketed address: name decoded
* and unquoted, email taken from inside the angles. The
* display-name commas inside double quotes must NOT split
* the address list since they belong to the name and not
* the recipient boundary.
*/
public function splitAddressesQuotedNameCommaTestCase()
{
$list = MailHeaderParser::splitAddresses(
'"Doe, Jane" <jane@x.com>, ' .
'"Smith, Bob" <bob@y.com>');
$this->assertEqual(2, count($list),
'Two recipients despite commas inside quoted names');
$this->assertEqual('Doe, Jane', $list[0][0],
'First recipient name (unquoted) recovered');
$this->assertEqual('jane@x.com', $list[0][1],
'First recipient email recovered');
$this->assertEqual('Smith, Bob', $list[1][0],
'Second recipient name (unquoted) recovered');
$this->assertEqual('bob@y.com', $list[1][1],
'Second recipient email recovered');
}
/**
* An empty input splits to an empty list, not a one-element
* list containing an empty pair.
*/
public function splitAddressesEmptyTestCase()
{
$list = MailHeaderParser::splitAddresses('');
$this->assertEqual([], $list,
'Empty input yields empty list');
}
/**
* Surrounding whitespace on each address is stripped so
* downstream consumers do not need to trim either part.
*/
public function splitAddressesWhitespaceTestCase()
{
$list = MailHeaderParser::splitAddresses(
' a@x.com , b@y.com ');
$this->assertEqual(2, count($list),
'Whitespace-padded addresses still yield two entries');
$this->assertEqual('a@x.com', $list[0][1],
'First email is trimmed');
$this->assertEqual('b@y.com', $list[1][1],
'Second email is trimmed');
}
/**
* parseAddressList splits on top-level commas only, keeping
* quoted-name and angle-bracketed entries whole.
*/
public function parseAddressListTestCase()
{
$list = MailHeaderParser::parseAddressList(
'Jane <j@x>, "Doe, J" <d@y>');
$this->assertEqual(2, count($list),
'a quoted comma does not split the entry');
$this->assertEqual('"Doe, J" <d@y>', $list[1],
'the second spec is kept whole');
$this->assertEqual([],
MailHeaderParser::parseAddressList(''),
'an empty header yields no entries');
}
/**
* extractBareAddress unwraps angle brackets, trims, lower-cases.
*/
public function extractBareAddressTestCase()
{
$this->assertEqual('j@x',
MailHeaderParser::extractBareAddress('Jane <J@X>'),
'the address is unwrapped and lower-cased');
$this->assertEqual('plain@x',
MailHeaderParser::extractBareAddress(' plain@x '),
'a bare address is trimmed');
}
/**
* isValidAddress accepts a normal address and rejects ones with
* no @ or nothing after it (true in both normal and test mode).
*/
public function isValidAddressTestCase()
{
$this->assertTrue(
MailHeaderParser::isValidAddress('user@example.com'),
'a normal address is valid');
$this->assertFalse(
MailHeaderParser::isValidAddress('nope'),
'an address with no @ is invalid');
$this->assertFalse(
MailHeaderParser::isValidAddress('a@'),
'an address with nothing after @ is invalid');
}
/**
* cleanHeader strips control characters, trims, and caps length.
*/
public function cleanHeaderTestCase()
{
$this->assertEqual('abcd',
MailHeaderParser::cleanHeader("a\r\nb\tcd", 100),
'control characters are stripped');
$this->assertEqual('hi',
MailHeaderParser::cleanHeader(' hi ', 100),
'surrounding spaces are trimmed');
$this->assertEqual('abc',
MailHeaderParser::cleanHeader('abcdef', 3),
'the value is capped at the maximum length');
}
/**
* filterAddressList drops the excluded address and any already
* present in the second list.
*/
public function filterAddressListTestCase()
{
$result = MailHeaderParser::filterAddressList(
'a@x, b@y, c@z', 'a@x', 'b@y');
$this->assertEqual('c@z', $result,
'the excluded and already-listed addresses are removed');
}
/**
* joinAddressLists merges two lists, dropping duplicates and the
* excluded address.
*/
public function joinAddressListsTestCase()
{
$result = MailHeaderParser::joinAddressLists(
'a@x, b@y', 'b@y, c@z', 'a@x');
$this->assertEqual('b@y, c@z', $result,
'duplicates and the excluded address are dropped');
}
/**
* envelopeSender reads the Return-Path address, or empty when
* the header is absent.
*/
public function envelopeSenderTestCase()
{
$bytes = "Return-Path: <bounce@x>\r\nFrom: a@y\r\n" .
"\r\nbody here";
$this->assertEqual('bounce@x',
MailHeaderParser::envelopeSender($bytes),
'the Return-Path address is unwrapped');
$this->assertEqual('',
MailHeaderParser::envelopeSender("From: a@y\r\n\r\nb"),
'no Return-Path yields an empty string');
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software