\WP_Buoy_Alert

Class for creating and delegating responses to alerts.

Alerts are posts that record some incident information such as the location and attached media recordings of what's going on.

Summary

Methods
Properties
Constants
register()
registerL10n()
initialize()
activate()
checkPrereqs()
install_plugin_dependency()
rest_api_install_failure_notice()
get_minimum_wordpress_version()
deactivate()
enqueueFrontEndScripts()
addHelpTab()
addHelpSidebar()
renderWebAppManifest()
renderWebAppHTML()
registerDashboardWidget()
renderDashboardWidget()
__construct()
load()
save()
set()
get_hash()
get_teams()
can_respond()
get_chat_room_name()
get_chat_system()
get_responders()
is_responder()
add_responder()
set_responder_geo()
get_responder_geo()
get_incident_state()
filterCommentsClauses()
redirectShortUrl()
redirectChatComment()
addAlertsMenu()
registerAdminMenu()
renderActivateAlertPage()
renderReviewAlertPage()
renderIncidentChatPage()
renderChatRoom()
renderPostCommentsChatRoom()
chatEventStream()
eventStreamMessage()
removeScreenOptions()
addInstallerScripts()
enqueueFrameworkScripts()
enqueueBootstrapFramework()
addIntegrityAttribute()
localizeScript()
handleNewAlert()
handleMediaUpload()
handleUnscheduleAlert()
handleLocationUpdate()
handleNewPostCommentChat()
handleDismissInstaller()
getActiveAlerts()
getScheduledAlerts()
$prefix
$wp_post
No constants found
debug_log()
No protected properties found
N/A
error_msg()
set_hash()
set_chat_room_name()
make_hash()
make_chat_room_name()
get_random_seed()
getIncidentMediaList()
getIncidentMediaHtml()
$user
$teams
$postarr
$hash
$chat_room_name
N/A

Properties

$prefix

$prefix : string

Type

string — String to prefix option names, settings, etc.

$wp_post

$wp_post : \WP_Post

Alert post.

Type

\WP_Post

$user

$user : \WP_User

The author of the alert.

Type

\WP_User

$teams

$teams : array<mixed,integer>

The teams to which this alert was sent.

Type

array<mixed,integer>

$postarr

$postarr : array

The alert's WP_Post data.

This holds the initialization data for the alert's WP_Post data and is the same as wp_insert_post()'s $postarr parameter.

Type

array

$hash

$hash : string

The alert's public identifier.

The $hash is a randomly generated lookup value that is used instead of a WordPress post ID. This is because a post ID is a sequential number, and would expose the Buoy to attack if a bad (malicious) actor. Using a hash value instead of an integer in this context makes it harder for attackrs to guess quantity and frequency of alerts that this Buoy maintains.

Type

string

$chat_room_name

$chat_room_name : string

The chat room associated with this alert.

Type

string

Methods

register()

register() : void

Registers the Buoy Alert post type and hooks.

This is the method called when WordPress loads the plugin file. It is responsible for "registering" the plugin's main functions with the WordPress Plugin API.

registerL10n()

registerL10n() : void

Loads localization files from plugin's languages directory.

initialize()

initialize() : void

Loads plugin componentry and calls that component's register() method. Called at the WordPress `init` hook.

activate()

activate(boolean  $network_wide) : void

Method to run when the plugin is activated by a user in the WordPress Dashboard admin screen.

Parameters

boolean $network_wide

checkPrereqs()

checkPrereqs() : void

Checks system requirements and exits if they are not met.

This first checks to ensure minimum WordPress and PHP versions have been satisfied. If not, the plugin deactivates and exits.

install_plugin_dependency()

install_plugin_dependency(string  $slug, string  $version = '') 

Automates installation of other plugins that we need.

We only use this for the WP REST API at the moment. It's the 1 and only dependency we have on other plugins. When that plugin gets added to WP Core, we can remove this code.

As a result, note that this code is SPECIFIC to the rest-api plugin. It will not work as-is for other plugins.

Parameters

string $slug
string $version

rest_api_install_failure_notice()

rest_api_install_failure_notice() 

get_minimum_wordpress_version()

get_minimum_wordpress_version() : string

Returns the "Requires at least" value from plugin's readme.txt.

Returns

string

deactivate()

deactivate() : void

Method to run when the plugin is deactivated by a user in the WordPress Dashboard admin screen.

enqueueFrontEndScripts()

enqueueFrontEndScripts() : void

Enqueues main alert functionality scripts and styles.

addHelpTab()

addHelpTab() : void

Attaches on-screen help tabs to the WordPress built-in help.

Loads the appropriate document from the localized help folder and inserts it as a help tab on the current screen.

addHelpSidebar()

addHelpSidebar() : void

Appends appropriate sidebar content based on current screen.

renderWebAppManifest()

renderWebAppManifest() : void

Prints the Web App manifest file.

renderWebAppHTML()

renderWebAppHTML() : void

Prints meta tag indicators for native-like functionality.

The "activate alert" screen is intended to be the web app "install" screen for Buoy. We insert special mobile browser specific tags in order to create a native-like "installer" for the user. We only want to do this on this specific screen.

registerDashboardWidget()

registerDashboardWidget() : void

Register the Dashboard widget.

renderDashboardWidget()

renderDashboardWidget() : void

Renders the Buoy Dashboard widget.

__construct()

__construct(integer|\WP_Post|string  $lookup = null) : \WP_Buoy_Alert

Constructor.

Retrieves an alert post as a WP_Buoy_Alert object, or an empty, new such object if no $lookup value is provided with which to search for a pre-existing alert.

Parameters

integer|\WP_Post|string $lookup

Optional lookup value, WP_Post, ID, or hash.

Returns

\WP_Buoy_Alert

load()

load(string|integer  $lookup) : \WP_Buoy_Alert

Get an alert from the WordPress database based on lookup value.

Parameters

string|integer $lookup

The lookup value.

Throws

\Exception

If no alert could be found using $lookup.

Returns

\WP_Buoy_Alert

save()

save() : integer|\WP_Error

Saves the alert (incident) in the WordPress database.

Returns

integer|\WP_Error —

Result of wp_insert_post().

set()

set(array  $postarr = array()) : \WP_Buoy_Alert

Sets the WP_Post data for this alert.

Parameters

array $postarr

Same as wp_insert_post()'s $postarr parameter.

Returns

\WP_Buoy_Alert

get_hash()

get_hash() : string

Gets this alert's lookup hash value.

Returns

string

get_teams()

get_teams() : array<mixed,integer>

Gets the teams to which this alert was sent.

Returns

array<mixed,integer>

can_respond()

can_respond(integer  $user_id) : boolean

Checks whether a user is allowed to respond to this alert.

A user is allowed to respond to an alert if they are listed as a "confirmed" member in one of the teams associated with this alert.

Parameters

integer $user_id

Returns

boolean

get_chat_room_name()

get_chat_room_name() : string

Gets this alert's chat room name.

Returns

string

get_chat_system()

get_chat_system() : string

Gets this alert's chat room system provider.

Returns

string

get_responders()

get_responders() : array<mixed,integer>

Retrieves a list of users who have responded to this alert.

Returns

array<mixed,integer>

is_responder()

is_responder(integer  $user_id) : boolean

Determine whether a user has responded to the alert.

Parameters

integer $user_id

Returns

boolean

add_responder()

add_responder(integer  $user_id) : \WP_Buoy_Alert

Adds a responder to this alert.

Parameters

integer $user_id

Returns

\WP_Buoy_Alert

set_responder_geo()

set_responder_geo(integer  $user_id, array<mixed,float>  $geo) : \WP_Buoy_Alert

Saves new geolocation data (lat/lon pair) for a responder.

Parameters

integer $user_id
array<mixed,float> $geo

Returns

\WP_Buoy_Alert

get_responder_geo()

get_responder_geo(integer  $user_id) : array<mixed,float>

Retrieves the current geolocation coords of a given responder.

Parameters

integer $user_id

Returns

array<mixed,float>

get_incident_state()

get_incident_state() : array

Retrieves an array containing information about all responders and the alerter involved in this alert.

Returns

array

filterCommentsClauses()

filterCommentsClauses(array<mixed,string>  $clauses, \WP_Comment_Query  $wp_comment_query) : array<mixed,string>

Omit comments used in Buoy Alert chats from comment queries.

Comments on Buoy Alerts (posts with the type buoy_alert) are actually "chat room" messages. These should not show elsewhere in the WordPress blog, such as in the "Recent comments" widget or other areas where a "show all comments" kind of request is asked for.

See also issue #157.

Parameters

array<mixed,string> $clauses
\WP_Comment_Query $wp_comment_query

Returns

array<mixed,string>

redirectShortUrl()

redirectShortUrl(\WP  $wp) : void

Redirects users arriving at Buoy via short url.

Detects an alert "short URL," which is an HTTP GET request with a special querystring parameter that matches the first 8 chars of an alert's hash value and, if matched, redirects to the full URL of that particular alert's "review" screen, then exit()s.

This occurrs during WordPress's send_headers hook.

Parameters

\WP $wp

redirectChatComment()

redirectChatComment(string  $location, \WP_Comment  $comment) : string

Alters the redirection URL after a "chat" comment is posted.

Parameters

string $location
\WP_Comment $comment

Returns

string

addAlertsMenu()

addAlertsMenu() : void

Attaches the "Active Alerts" menu to WordPress's admin toolbar.

registerAdminMenu()

registerAdminMenu() : void

Registers plugin hooks for the WordPress Dashboard admin menu.

renderActivateAlertPage()

renderActivateAlertPage() : void

Prints HTML for the "activate alert" page.

renderReviewAlertPage()

renderReviewAlertPage() : void

Prints HTML for the "review alert" page.

renderIncidentChatPage()

renderIncidentChatPage() : void

Prints HTML for the "incident chat" page.

renderChatRoom()

renderChatRoom(\WP_Buoy_Alert  $alert,   $curr_user) 

Hookable action to print out the HTML for the given chat room system.

This function is called by the custom buoy_chat_room action hook. Plugin developers can replace the Buoy chat room by hooking their own code to the action after removing the default action. This allows plugin developers to develop their own plugins that use custom chat room code for their own Buoys.

Parameters

\WP_Buoy_Alert $alert
$curr_user

renderPostCommentsChatRoom()

renderPostCommentsChatRoom() : void

Shows the built-in post comments chat room.

chatEventStream()

chatEventStream() 

A super-simple HTML5 Server-Side Events streaming server.

eventStreamMessage()

eventStreamMessage(string  $data = '', string  $type = '') : string

Utility function to create an HTML5 SSE message.

Call without arguments to send a heartbeat.

Parameters

string $data
string $type

Returns

string

removeScreenOptions()

removeScreenOptions() 

Utility function to remove the WordPress "Screen Options" tab.

addInstallerScripts()

addInstallerScripts() : void

Enqueues the "webapp/native" installer scripts if the user has not previously dismissed this functionality.

enqueueFrameworkScripts()

enqueueFrameworkScripts() : void

Enqueues the Bootstrap CSS and JavaScript framework resources, along with jQuery and Leaflet library plugins used for Alert UI.

enqueueBootstrapFramework()

enqueueBootstrapFramework() : void

Enqueues the Bootstrap framework CSS and JavaScript.

addIntegrityAttribute()

addIntegrityAttribute(string  $html, string  $handle) : string

Sets subresource integrity attributes on elements loaded via CDN.

Parameters

string $html
string $handle

Returns

string

localizeScript()

localizeScript() : array<mixed,string>

Translate user interface strings used in JavaScript.

Returns

array<mixed,string> —

An array of translated strings suitable for wp_localize_script().

handleNewAlert()

handleNewAlert() : void

Responds to requests activated from the main emergency alert button.

handleMediaUpload()

handleMediaUpload() : void

Adds a media file as an attachment to the incident post.

handleUnscheduleAlert()

handleUnscheduleAlert() : void

Cancels a scheduled alert by deleting it from the database.

handleLocationUpdate()

handleLocationUpdate() : void

Responds to Ajax POSTs containing new position information of responders/alerter, sends back the location of all of this alert's responders.

handleNewPostCommentChat()

handleNewPostCommentChat(boolean  $open, integer  $post_id) : boolean

Hooks the new comment routine to allow a "comment" on Alerts.

This is used to intercept the wp_handle_comment_submission() function early in its processing and allow only comments with the required Buoy Alert "chat" nonces to go through.

Parameters

boolean $open
integer $post_id

Returns

boolean

handleDismissInstaller()

handleDismissInstaller() : void

Saves a flag in the user's options that tells Buoy not to show the "webapp installer" scripts again.

getActiveAlerts()

getActiveAlerts() : array<mixed,\WP_Post>

Gets alert posts with an incident hash.

Returns

array<mixed,\WP_Post>

getScheduledAlerts()

getScheduledAlerts(integer  $uid = false) : array<mixed,\WP_Post>

Gets scheduled alert posts.

Parameters

integer $uid

The WordPress user ID of an author's scheduled posts to look up.

Returns

array<mixed,\WP_Post>

debug_log()

debug_log(string  $message) : void

Prints a message to the WordPress debug log if the plugin's "detailed debugging" setting is enabled.

By default, the WordPress debug log is wp-content/debug.log relative to the WordPress installation root (ABSPATH).

Parameters

string $message

error_msg()

error_msg(string  $message) : string

Prepares an error message for logging.

Parameters

string $message

Returns

string

set_hash()

set_hash() : void

Loads the alert hash from the database.

set_chat_room_name()

set_chat_room_name() : void

Loads this alert's chat room name from the database.

make_hash()

make_hash() : string

Makes a random lookup hash for this alert.

Returns

string

make_chat_room_name()

make_chat_room_name() : string

Makes a randomized chat room name for this alert.

Returns

string

get_random_seed()

get_random_seed() : string

This function tries to use the best available source of random numbers to create the seed data for a hash that it can find.

Returns

string

getIncidentMediaList()

getIncidentMediaList(integer  $post_id) : string

Returns an HTML structure containing nested lists and list items referring to any media attached to the given post ID.

Parameters

integer $post_id

The post ID from which to fetch attached media.

Returns

string —

HTML ready for insertion into an <ul> element.

getIncidentMediaHtml()

getIncidentMediaHtml(string  $type, integer  $post_id) : string

Gets the correct HTML embeds/elements for a given media type.

Parameters

string $type

One of 'video', 'audio', or 'image'

integer $post_id

The WP post ID of the attachment media.

Returns

string