<?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\library\mail;
/**
* Parses the untagged LIST responses defined in RFC 3501
* section 7.2.2 into the folder entries the Mail activity shows in
* its account pane.
*
* Each untagged line has the form
* * LIST (name-attributes) "hierarchy-delimiter" name
* where the attribute list is parenthesized and space-separated,
* the delimiter is a quoted character (or NIL), and the name is a
* quoted string or a {N} literal whose payload ImapClient::send()
* stitches inline.
*
* Three facts about each folder are surfaced: the folder name,
* whether the folder is selectable, and its RFC 6154 special-use
* role if any. A folder carrying the \Noselect attribute exists
* only as a point in the hierarchy and cannot be opened, so the
* caller renders it as a non-link. The special-use role drives
* sortBySpecialUse(), which puts the folder list into a stable
* display order since servers may return LIST results in any
* order.
*
* Like ImapEnvelopeParser this stays a small tokenizer rather than
* a single regular expression, because the name can be quoted or a
* literal and the attribute list varies between servers.
*
* @author Chris Pollett
*/
class ImapFolderListParser
{
/**
* Parses every untagged LIST line in a server response into a
* list of folder entries. Lines that are not LIST responses are
* skipped.
*
* @param array $untagged the untagged response lines from
* ImapClient::send()
* @return array list of associative arrays, each with a NAME
* string and a SELECTABLE boolean
*/
public static function parse($untagged)
{
$folders = [];
foreach ($untagged as $line) {
$folder = self::parseLine($line);
if ($folder !== null) {
$folders[] = $folder;
}
}
return $folders;
}
/**
* Returns the folder list in a stable display order: INBOX
* first, then the special-use folders in a conventional
* sequence (Drafts, Sent, Archive, Junk, Trash, then the
* virtual All and Flagged), then every remaining folder
* alphabetically. Folders that share a rank - including a
* server that marks more than one mailbox with the same
* special-use attribute - are ordered alphabetically among
* themselves.
*
* IMAP servers may return LIST results in any order (often the
* underlying directory order), so a list is sorted here rather
* than trusted as received. The result is a sensible default;
* a future per-user custom folder order would override it.
*
* @param array $folders folder entries as produced by parse()
* @return array the same entries in display order
*/
public static function sortBySpecialUse($folders)
{
$ranked = $folders;
usort($ranked, function ($first, $second) {
$first_rank = self::folderRank($first);
$second_rank = self::folderRank($second);
if ($first_rank !== $second_rank) {
return $first_rank <=> $second_rank;
}
return strcasecmp($first["NAME"], $second["NAME"]);
});
return $ranked;
}
/**
* Gives a folder its sort rank: 0 for INBOX, then a fixed
* sequence for the special-use roles, and a single larger rank
* for every ordinary folder so they fall together and are then
* ordered alphabetically by the caller.
*
* @param array $folder one folder entry with NAME and
* SPECIAL_USE keys
* @return int the folder's sort rank
*/
private static function folderRank($folder)
{
if (strcasecmp($folder["NAME"], "INBOX") === 0) {
return 0;
}
$special_use_order = ["\\Drafts" => 1, "\\Sent" => 2,
"\\Archive" => 3, "\\Junk" => 4, "\\Trash" => 5,
"\\All" => 6, "\\Flagged" => 7];
$special_use = $folder["SPECIAL_USE"] ?? "";
foreach ($special_use_order as $attribute => $rank) {
if (strcasecmp($special_use, $attribute) === 0) {
return $rank;
}
}
return 8;
}
/**
* Parses a single untagged response line. Returns null when the
* line is not a LIST response or carries no usable folder name.
*
* @param string $line one untagged response line
* @return array|null an associative array with NAME and
* SELECTABLE, or null when the line is not a usable LIST
* response
*/
private static function parseLine($line)
{
$marker = strpos($line, "LIST (");
if ($marker === false) {
return null;
}
$pos = $marker + strlen("LIST ");
$attributes = self::parseFlagList($line, $pos);
if ($attributes === null) {
return null;
}
/* the hierarchy delimiter token is a quoted character
or the bare atom NIL; preserved as DELIMITER so the
tree-view renderer can split nested folder names on
it. NIL flattens to an empty string. */
self::skipSpaces($line, $pos);
$delimiter = self::readToken($line, $pos);
self::skipSpaces($line, $pos);
$name = self::readToken($line, $pos);
if ($name === "") {
return null;
}
$selectable = true;
$special_use = "";
foreach ($attributes as $attribute) {
if (strcasecmp($attribute, "\\Noselect") === 0) {
$selectable = false;
} else if (self::isSpecialUseAttribute($attribute)) {
$special_use = $attribute;
}
}
return ["NAME" => $name, "SELECTABLE" => $selectable,
"SPECIAL_USE" => $special_use,
"DELIMITER" => $delimiter];
}
/**
* Reports whether an attribute is one of the RFC 6154
* special-use attributes (\All, \Archive, \Drafts, \Flagged,
* \Junk, \Sent, \Trash) that mark a mailbox's role.
*
* @param string $attribute one name-attribute from a LIST line
* @return bool true when the attribute is a special-use marker
*/
private static function isSpecialUseAttribute($attribute)
{
$special_use_attributes = ["\\All", "\\Archive", "\\Drafts",
"\\Flagged", "\\Junk", "\\Sent", "\\Trash"];
foreach ($special_use_attributes as $known) {
if (strcasecmp($attribute, $known) === 0) {
return true;
}
}
return false;
}
/**
* Parses the parenthesized, space-separated name-attribute list
* beginning at $line[$pos], which must be "(". Advances $pos
* past the closing ")". Returns null when the text does not
* start a well-formed list.
*
* @param string $line the full line being parsed
* @param int &$pos cursor into $line; advanced past the list
* @return array|null the attribute strings, or null on
* malformed input
*/
private static function parseFlagList($line, &$pos)
{
$length = strlen($line);
if ($pos >= $length || $line[$pos] !== "(") {
return null;
}
$pos++;
$attributes = [];
$current = "";
while ($pos < $length) {
$char = $line[$pos];
if ($char === ")") {
$pos++;
if ($current !== "") {
$attributes[] = $current;
}
return $attributes;
}
if ($char === " ") {
if ($current !== "") {
$attributes[] = $current;
$current = "";
}
$pos++;
continue;
}
$current .= $char;
$pos++;
}
return null;
}
/**
* Advances $pos past any run of spaces in $line.
*
* @param string $line the full line being parsed
* @param int &$pos cursor into $line; advanced past the spaces
*/
private static function skipSpaces($line, &$pos)
{
$length = strlen($line);
while ($pos < $length && $line[$pos] === " ") {
$pos++;
}
}
/**
* Reads one token beginning at $line[$pos]: a double-quoted
* string, a {N} literal, or a bare atom. Advances $pos past the
* token. The bare atom NIL is normalized to the empty string.
*
* @param string $line the full line being parsed
* @param int &$pos cursor into $line; advanced past the token
* @return string the token's string value
*/
private static function readToken($line, &$pos)
{
$length = strlen($line);
if ($pos >= $length) {
return "";
}
if ($line[$pos] === '"') {
return self::readQuoted($line, $pos);
}
if ($line[$pos] === "{") {
return self::readLiteral($line, $pos);
}
$token = "";
while ($pos < $length && $line[$pos] !== " " &&
$line[$pos] !== "(" && $line[$pos] !== ")") {
$token .= $line[$pos];
$pos++;
}
if ($token === "NIL") {
return "";
}
return $token;
}
/**
* Reads a double-quoted string beginning at $line[$pos], which
* must be the opening quote. A backslash escapes the following
* character. Advances $pos past the closing quote.
*
* @param string $line the full line being parsed
* @param int &$pos cursor into $line; advanced past the string
* @return string the unescaped string contents
*/
private static function readQuoted($line, &$pos)
{
$length = strlen($line);
$pos++;
$value = "";
while ($pos < $length) {
$char = $line[$pos];
if ($char === "\\" && $pos + 1 < $length) {
$value .= $line[$pos + 1];
$pos += 2;
continue;
}
if ($char === '"') {
$pos++;
return $value;
}
$value .= $char;
$pos++;
}
return $value;
}
/**
* Reads a {N} literal beginning at $line[$pos], which must be
* the opening brace. ImapClient::send() stitches a literal's
* payload inline immediately after the brace marker, so the N
* bytes following the "}" are the value. Advances $pos past the
* payload.
*
* @param string $line the full line being parsed
* @param int &$pos cursor into $line; advanced past the literal
* @return string the literal payload, or the empty string when
* the marker is malformed
*/
private static function readLiteral($line, &$pos)
{
$length = strlen($line);
$close = strpos($line, "}", $pos);
if ($close === false) {
$pos = $length;
return "";
}
$count = (int) substr($line, $pos + 1, $close - $pos - 1);
$payload_start = $close + 1;
$value = substr($line, $payload_start, $count);
$pos = $payload_start + $count;
return $value;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software