<?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\models;
use seekquarry\yioop\library\mail\ImapListing;
/**
* Holds the small pieces of per-user state the Mail activity keeps
* between one inbox page and the next: which way the open folder is
* sorted, the ordered message list a sorted view produced (so paging
* does not re-sort), and whether the account's mail server can sort
* at all. All of it lives in the browsing session rather than the
* database, because it is a transient view preference, not a stored
* record. Keeping it here lets the Mail controller stay a thin
* request handler instead of carrying session bookkeeping.
*
* @author Chris Pollett
*/
class MailModel extends Model
{
/**
* How long, in seconds, a cached folder list stays fresh before
* the inbox fetches it from the mail server again. Five minutes
* keeps the folder side-panel responsive without holding on to a
* stale list across a long session.
*/
const MAIL_FOLDERS_CACHE_TTL = 300;
/**
* Remembers how a folder is sorted for one account, so the choice
* sticks as the user moves around the inbox.
*
* @param int $account_id the mail account being viewed
* @param string $folder the folder being viewed
* @param array $sort a ["key" => string, "reverse" => bool] pair
*/
public function storeSort($account_id, $folder, $sort)
{
if (empty($_SESSION["MAIL_SORT"])) {
$_SESSION["MAIL_SORT"] = [];
}
if (empty($_SESSION["MAIL_SORT"][$account_id])) {
$_SESSION["MAIL_SORT"][$account_id] = [];
}
$_SESSION["MAIL_SORT"][$account_id][$folder] = $sort;
}
/**
* Returns the remembered sort for a folder, or null when none has
* been chosen yet. The caller validates it, since what counts as
* a legal sort is a controller-level decision.
*
* @param int $account_id the mail account being viewed
* @param string $folder the folder being viewed
* @return array|null the remembered ["key", "reverse"] pair, or
* null if nothing is stored
*/
public function storedSort($account_id, $folder)
{
return $_SESSION["MAIL_SORT"][$account_id][$folder] ?? null;
}
/**
* Remembers the ordered list of message sequence numbers a sorted
* view produced, so paging further into that view does not have
* to ask the server to sort again. The list is kept per account,
* folder, filter, and sort so different views of the same folder
* do not overwrite each other. A view with no such list (the
* plain newest-first one) stores nothing.
*
* @param int $account_id the account being viewed
* @param string $folder the folder being viewed
* @param string $filter the free-text filter in effect, or empty
* @param array $sort the sort in effect
* @param bool $unread_only the unread-only toggle
* @param bool $flagged_only the flagged-only toggle
* @param array|null $cursor the listing's next_cursor, which holds
* the ordered list when there is one to remember
*/
public function cacheSequence($account_id, $folder, $filter, $sort,
$unread_only, $flagged_only, $cursor)
{
if (!isset($cursor['sequence'])) {
return;
}
$signature = ImapListing::sortSignature($sort, $unread_only,
$flagged_only);
if (empty($_SESSION["MAIL_SORT_LIST"])) {
$_SESSION["MAIL_SORT_LIST"] = [];
}
$_SESSION["MAIL_SORT_LIST"][$account_id][$folder][$filter]
[$signature] = $cursor['sequence'];
}
/**
* Returns the remembered ordered list for a sorted view so a
* "load more" can continue where it left off without re-sorting,
* or an empty list when none was kept.
*
* @param int $account_id the account being viewed
* @param string $folder the folder being viewed
* @param string $filter the free-text filter in effect, or empty
* @param string $signature the sort/toggle signature identifying
* the view
* @return array the ordered sequence numbers, or an empty array
*/
public function cachedSequence($account_id, $folder, $filter,
$signature)
{
return $_SESSION["MAIL_SORT_LIST"][$account_id][$folder]
[$filter][$signature] ?? [];
}
/**
* Returns whether an account's mail server has already been found
* to support sorting, so the inbox can skip asking the server
* again on later pages. Returns null when it has not been learned
* yet.
*
* @param int $account_id the account being viewed
* @return bool|null the remembered support, or null if unknown
*/
public function sortSupportHint($account_id)
{
return $_SESSION["MAIL_SORT_SUPPORTED"][$account_id] ?? null;
}
/**
* Remembers whether an account's mail server can sort messages so
* later inbox pages do not have to ask it again.
*
* @param int $account_id the account being viewed
* @param bool $supported whether the server can sort
*/
public function cacheSortSupport($account_id, $supported)
{
if (empty($_SESSION["MAIL_SORT_SUPPORTED"])) {
$_SESSION["MAIL_SORT_SUPPORTED"] = [];
}
$_SESSION["MAIL_SORT_SUPPORTED"][$account_id] =
(bool) $supported;
}
/**
* Returns an account's cached folder list when it is still fresh,
* or null when nothing is cached or the cache has aged out. The
* inbox uses this to avoid re-asking the mail server for the
* folder list on every page load. Freshness is tracked by a
* companion expiry timestamp stamped when the list was cached.
*
* @param int $account_id the account whose folder list is wanted
* @return array|null the folder list as parsed by
* ImapFolderListParser, or null when empty or stale
*/
public function cachedFolders($account_id)
{
$folders = $_SESSION["MAIL_FOLDERS"][$account_id] ?? null;
if (!is_array($folders) || empty($folders)) {
return null;
}
$expires =
$_SESSION["MAIL_FOLDERS_FRESH_UNTIL"][$account_id] ?? 0;
if ($expires <= time()) {
return null;
}
return $folders;
}
/**
* Caches a freshly fetched folder list for an account and stamps
* how long it should be trusted, so later pages can reuse it
* rather than fetch it from the mail server again.
*
* @param int $account_id the account whose list is being cached
* @param array $folders the folder list parsed and sorted by
* ImapFolderListParser
*/
public function cacheFolders($account_id, $folders)
{
$_SESSION["MAIL_FOLDERS"][$account_id] = $folders;
$_SESSION["MAIL_FOLDERS_FRESH_UNTIL"][$account_id] =
time() + self::MAIL_FOLDERS_CACHE_TTL;
}
/**
* Drops an account's cached folder list and its freshness stamp
* so the next view rebuilds it from the server. Used after the
* folder set changes (a folder created, renamed, or deleted) or
* the account itself is removed.
*
* @param int $account_id the account whose cache to clear
*/
public function invalidateFolders($account_id)
{
unset($_SESSION["MAIL_FOLDERS"][$account_id]);
unset($_SESSION["MAIL_FOLDERS_FRESH_UNTIL"][$account_id]);
}
/**
* Returns whatever folder list is cached for an account, or an
* empty list when none is, without checking freshness. Used
* where any reasonably recent list will do -- finding a target
* folder for a cross-account move, or confirming a folder exists
* before a folder operation -- rather than for the
* freshness-sensitive inbox render.
*
* @param int $account_id the account whose cached list is wanted
* @return array the cached folder list, or an empty array
*/
public function foldersFor($account_id)
{
return $_SESSION["MAIL_FOLDERS"][$account_id] ?? [];
}
/**
* Returns the cached folder lists for every account the session
* has visited, keyed by account id. The Mail page hands this to
* the view so every pane can show the folder side-panel, not
* only the pane that happened to fetch its own list.
*
* @return array map of account id to that account's cached
* folder list
*/
public function allCachedFolders()
{
return $_SESSION["MAIL_FOLDERS"] ?? [];
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software