README

PocketMine-MP library for queuing chat messages, titles, popups and tips to offline players and delivering them on next join. Messages are persisted to disk so they survive restarts, support TTL expiration, and never get dropped on race with new writes.

Installation

composer require angegroup/notifier

Requires PHP 8.2+ and PocketMine-MP.

Usage

Queue a message

use notifier\MessageType;
use notifier\Notifier;

$notifier = new Notifier();

// Plain chat message, by UUID (preferred — survives name changes)
$notifier->queue($uuid, "§aYour reward is waiting at /claim.");

// By player name (fallback when only the name is known)
$notifier->queueByName("steve", "§eYou were promoted to moderator.");

// Different display channels — title, popup, or tip
$notifier->queue($uuid, "§6Welcome back!", MessageType::Title);
$notifier->queueByName("steve", "§bDaily bonus available", MessageType::Popup);

// With expiration: drop the message if not delivered within an hour
$notifier->queue($uuid, "Flash event in progress!", MessageType::Chat, ttlSeconds: 3600);

// Bulk queue — same message to many recipients (auto-detects UUID vs name)
$notifier->queueMany([$uuid1, $uuid2, "steve"], "§dServer restart in 5 min");

Writes are append-only and lock-protected, so concurrent producers won't clobber each other.

Deliver on join

Wire deliverQueued() from a PlayerJoinEvent listener:

use notifier\Notifier;
use pocketmine\event\Listener;
use pocketmine\event\player\PlayerJoinEvent;

final class JoinListener implements Listener {
    public function __construct(private Notifier $notifier) {}

    public function onJoin(PlayerJoinEvent $event): void {
        $this->notifier->deliverQueued($event->getPlayer());
    }
}

Delivery is atomic: the queue file is renamed before being read, so any messages queued during delivery land in a fresh file rather than being silently dropped. Expired messages are skipped.

Inspect, count, or clear the queue

// All queued notifications, grouped by file → list of QueuedMessage
$all = $notifier->listQueued();

// Just one player (UUID or name)
$mine = $notifier->listQueued("steve");
foreach ($mine as $file => $messages) {
    foreach ($messages as $msg) {
        echo $msg->message, ' (', $msg->type->value, ")\n";
    }
}

// Fast count without loading message bodies
$pending = $notifier->count();
$forSteve = $notifier->count("steve");

// Drop everything
$notifier->clearQueued();

// Drop one player's queue
$notifier->clearQueued($uuid);

Hook delivery via the event

DeliverQueuedEvent fires once per non-expired message. Cancel it to drop a message or mutate it to rewrite the payload:

use notifier\MessageType;
use notifier\event\DeliverQueuedEvent;
use pocketmine\event\Listener;

final class NotificationFilter implements Listener {
    public function onDeliver(DeliverQueuedEvent $event): void {
        if ($event->getPlayer()->isCreative()) {
            $event->cancel();
            return;
        }
        $event->setMessage("[Mail] " . $event->getMessage());
        $event->setType(MessageType::Popup); // re-route from chat to popup
    }
}

Storage format

Each message is one JSON object per line:

{"m":"Hello!","t":"chat","e":1715900000}

Legacy plain-text lines are still read and treated as chat with no expiration — the format upgrade is fully backwards compatible.

Configuration

The constructor accepts a custom storage directory. The default (<server-root>/var/notifications) works for most setups:

$notifier = new Notifier("/custom/path");

Development

composer install --ignore-platform-reqs   # PMMP needs native exts we don't run
composer test            # PHPUnit (unit tests)
composer test-coverage   # PHPUnit with coverage summary
composer cs-check        # php-cs-fixer dry-run
composer cs-fix          # apply formatting
composer phpstan         # static analysis

Test layout

tests/
├── MessageTypeTest.php         # enum cases & tryFrom
├── QueuedMessageTest.php       # value object & isExpired
├── NotifierTest.php            # queue / list / count / clear / TTL / format
└── event/
    └── DeliverQueuedEventTest.php   # event accessors & cancel

Notifier::deliverQueued() is exercised indirectly: its decoding, expiration filter, and dispatch routing logic are covered through the public API and QueuedMessage::isExpired(). The PocketMine event call itself requires a booted server and is intentionally not unit-tested.

CI runs composer validate, a syntax check, php-cs-fixer (dry-run), PHPStan level 8, and PHPUnit on every push and pull request.

License

MIT — see LICENSE.