message_functions.php
Table of Contents
Functions
- message_get() : bool
- Gets messages for a given user (returns true if there are messages, false if not) Note that messages are passed by reference.
- message_add() : void
- Add a new resourcespace system message
- message_remove() : void
- Remove a message from message table and associated user_messages
- message_seen() : void
- Mark a message as seen
- message_unseen() : void
- Mark a message as unseen
- message_seen_all() : void
- Flags all non-read messages as read for given user and seen type
- message_purge() : void
- Remove all messages from message and user_message tables that have expired (regardless of read).
- message_deleteselusrmsg() : void
- Delete all selected messages
- message_selectedseen() : void
- Mark all selected messages as seen
- message_selectedunseen() : void
- Mark all selected messages as unseen
- message_send_unread_emails() : bool
- Send a summary of all unread notifications as an email from the standard cron_copy_hitcount
- message_remove_related() : void
- Remove all messages related to a certain activity (e.g. resource request or resource submission) matching the given ref(s)
- system_notification() : void
- Send a system notification or email to the system administrators according to preference
- message_getrefs() : void
- Get all message refs for a given user
- message_get_conversation() : array<string|int, mixed>
- Get all messages between the given user IDs
- send_user_message() : bool|string
- Send a user to user(s) message
- send_user_notification() : array<string|int, mixed>
- Send system notifications to specified users, checking the user preferences first if specified
- get_user_message() : array<string|int, mixed>|bool
- Gets the user message for the given ref
- send_integrity_failure_notices() : void
- Send notifications about file integrity failures
- build_specialsearch_list_urls() : array<string|int, mixed>
- Limit the length of !list special search url by adding a maximum of 650 characters of resource references per link including separators.
Functions
message_get()
Gets messages for a given user (returns true if there are messages, false if not) Note that messages are passed by reference.
message_get(array<string|int, mixed> &$messages, int $user[, bool $expired = false ][, bool $seen = false ][, string $sort = "ASC" ][, string $order_by = "ref" ][, int $limit = 0 ]) : bool
Parameters
- $messages : array<string|int, mixed>
-
Array that will be populated by messages. Passed by reference
- $user : int
-
User ID
- $expired : bool = false
-
Include expired messages?
- $seen : bool = false
-
Include seen messages?
- $sort : string = "ASC"
-
Sort by message ID in ascending (ASC) or descending (DESC) order
- $order_by : string = "ref"
-
Order of messages returned
- $limit : int = 0
-
Limit the number of messages returned, defaults to 0 which is no limit
Return values
bool —Flag to indicate if any messages exist
message_add()
Add a new resourcespace system message
message_add(mixed $users, string $text[, string $url = "" ][, int $owner = null ][, int $notification_type = MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN ][, int $ttl_seconds = MESSAGE_DEFAULT_TTL_SECONDS ][, int $related_activity = 0 ][, int $related_ref = 0 ]) : void
Parameters
- $users : mixed
-
User ID, or array of user IDs
- $text : string
-
Message text
- $url : string = ""
-
URL to include as link in message
- $owner : int = null
-
ID of message creator/owner
- $notification_type : int = MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN
-
Message type e.g. MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN, MESSAGE_ENUM_NOTIFICATION_TYPE_EMAIL. See definitions.php
- $ttl_seconds : int = MESSAGE_DEFAULT_TTL_SECONDS
-
Lifetime of message in seconds before expiry
- $related_activity : int = 0
-
ID of related activity type - see SYSTEM NOTIFICATION TYPES section in definitions.php
- $related_ref : int = 0
-
Related activity ID - used with type above to delete redundant messages e.g. once a user or resource request has been approved
Tags
message_remove()
Remove a message from message table and associated user_messages
message_remove(int $message) : void
Parameters
- $message : int
-
Message ID
message_seen()
Mark a message as seen
message_seen(int $message[, int $seen_type = MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN ]) : void
Parameters
- $message : int
-
Message ID
- $seen_type : int = MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN
-
- see definitons.php
message_unseen()
Mark a message as unseen
message_unseen(int $message) : void
Parameters
- $message : int
-
Message ID
message_seen_all()
Flags all non-read messages as read for given user and seen type
message_seen_all(int $user[, int $seen_type = MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN ]) : void
Parameters
- $user : int
-
User ID
- $seen_type : int = MESSAGE_ENUM_NOTIFICATION_TYPE_SCREEN
-
- see definitons.php
message_purge()
Remove all messages from message and user_message tables that have expired (regardless of read).
message_purge() : void
This will be called from a cron job.
message_deleteselusrmsg()
Delete all selected messages
message_deleteselusrmsg(mixed $messages) : void
Parameters
- $messages : mixed
-
List of message refs in JSON list format
message_selectedseen()
Mark all selected messages as seen
message_selectedseen(mixed $messages) : void
Parameters
- $messages : mixed
-
List of message refs in JSON list format
message_selectedunseen()
Mark all selected messages as unseen
message_selectedunseen(mixed $messages) : void
Parameters
- $messages : mixed
-
List of message refs in JSON list format
message_send_unread_emails()
Send a summary of all unread notifications as an email from the standard cron_copy_hitcount
message_send_unread_emails() : bool
Return values
bool —Returns false if not due to run
message_remove_related()
Remove all messages related to a certain activity (e.g. resource request or resource submission) matching the given ref(s)
message_remove_related([int $remote_activity = 0 ][, mixed $remote_refs = array() ]) : void
Parameters
- $remote_activity : int = 0
-
ID of related activity type - see SYSTEM NOTIFICATION TYPES section in definitions.php
- $remote_refs : mixed = array()
-
Related activity ID or array of IDs
system_notification()
Send a system notification or email to the system administrators according to preference
system_notification(string $message[, string $url = "" ]) : void
Parameters
- $message : string
-
Message text
- $url : string = ""
-
Optional URL
message_getrefs()
Get all message refs for a given user
message_getrefs(string $user) : void
Parameters
- $user : string
-
User ID
message_get_conversation()
Get all messages between the given user IDs
message_get_conversation(int $user[, array<string|int, mixed> $msgusers = array() ][, array<string|int, mixed> $filteropts = array() ]) : array<string|int, mixed>
Parameters
- $user : int
- $msgusers : array<string|int, mixed> = array()
-
Array of other user IDs
- $filteropts : array<string|int, mixed> = array()
-
Array of extra options to filter and sort messages returned "msgfind" - (string) Text to find "sort_desc" - (bool) Sort by message ID in descending order? False = Ascending "limit" - (int) Maximum number of messages to return
Return values
array<string|int, mixed> —Array of messages
send_user_message()
Send a user to user(s) message
send_user_message(array<string|int, mixed> $users, string $text) : bool|string
Parameters
- $users : array<string|int, mixed>
-
Array of user IDs or usernames/groupnames from user select
- $text : string
-
Message text
Return values
bool|string —True if sent ok or error message
send_user_notification()
Send system notifications to specified users, checking the user preferences first if specified
send_user_notification(array<string|int, mixed> $users, ResourceSpaceUserNotification $notifymessage[, bool $forcemail = false ]) : array<string|int, mixed>
Parameters
- $users : array<string|int, mixed>
-
Array of user IDs or array of user details from get_users()
- $notifymessage : ResourceSpaceUserNotification
-
An instance of a ResourceSpaceUserNotification object holding message properties
- $forcemail : bool = false
-
Force system to send email instead of notification?
Return values
array<string|int, mixed> —Array containing resulting messages - can be used for testing when emails are not being sent This will contain two arrays:- "emails" array of emails sent, with the following elements:- "email" => Email address "subject" => Email subject "body" => Body text
"messages" Array of system messages sent with the following elements :-
"user" => User ID
"message" => message text
"url" => url
get_user_message()
Gets the user message for the given ref
get_user_message(int $ref[, bool $checkaccess = true ]) : array<string|int, mixed>|bool
Parameters
- $ref : int
-
Message ID
- $checkaccess : bool = true
-
Check if user can see the given message?
Return values
array<string|int, mixed>|bool —Array with two elements: 'message' => message text,'url'=> message URL and 'owner' => message owner False if user has no access or the requested message doesn't exist,
send_integrity_failure_notices()
Send notifications about file integrity failures
send_integrity_failure_notices(array<string|int, mixed> $failures) : void
Parameters
- $failures : array<string|int, mixed>
-
Array of resources that have failed integrity check
build_specialsearch_list_urls()
Limit the length of !list special search url by adding a maximum of 650 characters of resource references per link including separators.
build_specialsearch_list_urls(array<string|int, mixed> $resource_refs) : array<string|int, mixed>
Mail servers may break very long text strings into multiple lines and this will cause the special search to fail. Loading URLs of great length may also cause a Request-URI Too Long error in the browser. Multiple urls will be returned, formatted to include in action dates notifications.
Parameters
- $resource_refs : array<string|int, mixed>
-
Array containing resource references to include in url.
Return values
array<string|int, mixed> —Array containing 'single' value of url (650 characters of resources or less) and 'multiple' value of url (more than 650 characters of resources).