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