Tsugi

NotificationsService
in package

NotificationsService - Utility class for managing user notifications

Provides methods to create, read, and manage notifications for users.

Table of Contents

Methods

cleanupOldNotifications()  : array<string|int, mixed>|false
Clean up old notifications (older than configured expiration days)
create()  : array<string|int, mixed>|false
Create a notification for a user
createForUsers()  : int
Create notifications for multiple users
delete()  : bool
Delete a notification
generateDedupeKey()  : string
Generate a dedupe key for a notification
getById()  : array<string|int, mixed>|false
Get a notification by ID
getForUser()  : array<string|int, mixed>
Get all notifications for a user, ordered by most recent first
getUnreadCount()  : int
Get unread notification count for a user
markAllAsRead()  : bool
Mark all notifications as read for a user
markAsRead()  : bool
Mark a notification as read

Methods

cleanupOldNotifications()

Clean up old notifications (older than configured expiration days)

public static cleanupOldNotifications([int $expiration_days = 30 ][, int $min_interval_seconds = 3600 ]) : array<string|int, mixed>|false

Uses opportunistic cleanup - only runs if cleanup hasn't run recently to avoid performance impact. This method is called automatically when notifications are fetched, but can also be called manually.

Parameters
$expiration_days : int = 30

Number of days after which to expire notifications (default: 30)

$min_interval_seconds : int = 3600

Minimum seconds between cleanup runs (default: 3600 = 1 hour)

Return values
array<string|int, mixed>|false —

Returns array with cleanup stats on success, false if skipped or failed

create()

Create a notification for a user

public static create(int $user_id, string $title[, string|null $text = null ][, string|null $url = null ][, array<string|int, mixed>|object|null $json = null ][, string|null $dedupe_key = null ]) : array<string|int, mixed>|false
Parameters
$user_id : int

The user ID to notify

$title : string

Notification title

$text : string|null = null

Notification text/content (optional)

$url : string|null = null

Optional URL to link to

$json : array<string|int, mixed>|object|null = null

Optional JSON data to store

$dedupe_key : string|null = null

Optional deduplication key - if provided, notifications with the same key for the same user will be de-duplicated within the time window

Return values
array<string|int, mixed>|false —

Returns notification data on success, false on failure

createForUsers()

Create notifications for multiple users

public static createForUsers(array<string|int, mixed> $user_ids, string $title, string $text[, string|null $url = null ]) : int
Parameters
$user_ids : array<string|int, mixed>

Array of user IDs to notify

$title : string

Notification title

$text : string

Notification text/content

$url : string|null = null

Optional URL to link to

Return values
int —

Number of notifications created

delete()

Delete a notification

public static delete(int $notification_id, int $user_id) : bool
Parameters
$notification_id : int

The notification ID

$user_id : int

The user ID (for security - ensures user owns the notification)

Return values
bool —

True on success, false on failure

generateDedupeKey()

Generate a dedupe key for a notification

public static generateDedupeKey(string $source, int $user_id[, int|null $link_id = null ][, string|null $additional = null ]) : string
Parameters
$source : string

Source identifier (e.g., 'peer-grade', 'aipaper-comment')

$user_id : int

User ID

$link_id : int|null = null

Optional link/assignment ID

$additional : string|null = null

Optional additional identifier

Return values
string —

Dedupe key

getById()

Get a notification by ID

public static getById(int $notification_id) : array<string|int, mixed>|false
Parameters
$notification_id : int
Return values
array<string|int, mixed>|false —

Notification data or false if not found

getForUser()

Get all notifications for a user, ordered by most recent first

public static getForUser(int $user_id[, bool $unread_only = false ][, int $limit = 0 ]) : array<string|int, mixed>
Parameters
$user_id : int

The user ID

$unread_only : bool = false

If true, only return unread notifications

$limit : int = 0

Maximum number of notifications to return (0 = no limit)

Return values
array<string|int, mixed> —

Array of notification data

getUnreadCount()

Get unread notification count for a user

public static getUnreadCount(int $user_id) : int
Parameters
$user_id : int

The user ID

Return values
int —

Number of unread notifications

markAllAsRead()

Mark all notifications as read for a user

public static markAllAsRead(int $user_id) : bool
Parameters
$user_id : int

The user ID

Return values
bool —

True on success, false on failure

markAsRead()

Mark a notification as read

public static markAsRead(int $notification_id, int $user_id) : bool
Parameters
$notification_id : int

The notification ID

$user_id : int

The user ID (for security - ensures user owns the notification)

Return values
bool —

True on success, false on failure


        
On this page

Search results