API Notify

Caligrafy\Notify

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

Part of Jobs, notifications and mail.

namespace Caligrafy;

class Notify

Source: framework/core/Notify.php:28

Class Notify Notify::user($userId, ['title' => ..., 'body' => ..., 'url' => ..., 'tag' => ..., 'urgency' => ...]) sends to every channel the user turned on and logs the result (caligrafy_notifications: never the body; kept 30 days):

• push: each browser the user subscribed (caligrafy_push_subscriptions), with the VAPID keys of .env (php caligrafer.php notify keys), 5 seconds per push service, the message kept 24 hours for a device that is off; a 404 or 410 deletes the subscription, so do 5 failures in a row
• email: the user's confirmed address only (caligrafy_notify_emails), through MAIL_*, with a one-click unsubscribe link (a signed URL) and the List-Unsubscribe headers

A delivery failure never throws; a bad message throws ServiceError::invalid. At most NOTIFY_RATE_PER_HOUR messages per user and hour (30): above it nothing is sent ('skipped' => 'rate'). In-page alerts stay the app's job. Without the tables (php caligrafer.php platform install) nothing is sent and nothing fails.

Constants

• CHANNELS = array('push', 'email')
• SUBSCRIPTIONS = 'caligrafy_push_subscriptions'
• EMAILS = 'caligrafy_notify_emails'
• PREFS = 'caligrafy_notify_prefs'
• LOG = 'caligrafy_notifications'
• TTL = 86400
• PUSH_TIMEOUT = 5
• MAX_FAILURES = 5
• PAYLOAD_BYTES = 3072
• TOKEN_HOURS = 24
• KEEP_DAYS = 30

Public properties

• public static $pushSender = null: callable|null replaces the push sender in tests: fn(array $subscriptions, string $payload, array $options) => [endpoint => status]
• public static $mailSender = null: callable|null replaces the mail sender in tests: fn($to, $subject, $html, array $headers) => bool

Methods

• Notify::user()
• Notify::forget()
• Notify::message()
• Notify::pushConfigured()
• Notify::keys()
• Notify::subscribe()
• Notify::unsubscribe()
• Notify::emailConfigured()
• Notify::setEmail()
• Notify::confirm()
• Notify::unsubscribeUrl()
• Notify::unsubscribeEmail()
• Notify::html()
• Notify::theme()
• Notify::page()
• Notify::offered()
• Notify::prefer()
• Notify::enabled()
• Notify::status()
• Notify::base()

Notify::user()

public static function user($userId, array $message)

Sends a message to a user on every channel they turned on

Parameters

• $userId int|string: the id Context::userId() returns
• $message array: title (80), body (300), url (https or a path of the app), tag, urgency (low, normal, high)

Returns array: push (how many browsers got it), email (whether it was sent), skipped (null, or 'rate')

• @throws ServiceError invalid, on a bad message

Source: framework/core/Notify.php:58

Notify::forget()

public static function forget($userId)

Deletes everything notifications keep about a user (their subscriptions, address, choices and log): call it when you delete the user

Parameters

• $userId

Source: framework/core/Notify.php:90

Notify::message()

public static function message(array $message)

The message, checked and completed (urgency normal)

Parameters

• $message array

• @throws ServiceError invalid

Source: framework/core/Notify.php:101

Notify::pushConfigured()

public static function pushConfigured()

Whether the VAPID keys are set (php caligrafer.php notify keys)

Source: framework/core/Notify.php:124

Notify::keys()

public static function keys()

A new pair of VAPID keys (base64url): public and private

Source: framework/core/Notify.php:132

Notify::subscribe()

public static function subscribe($userId, array $subscription, $userAgent = '')

Saves a browser's push subscription (the JSON of PushSubscription) for a user; an endpoint belongs to one user

Parameters

• $userId
• $subscription array
• $userAgent, default ''

Source: framework/core/Notify.php:142

Notify::unsubscribe()

public static function unsubscribe($userId, $endpoint)

Deletes one of the user's subscriptions (only theirs): whether one was deleted

Parameters

• $userId
• $endpoint

Source: framework/core/Notify.php:163

Notify::emailConfigured()

public static function emailConfigured()

Whether email can be sent: MAIL_HOST set and an address for the app's links (APP_URL, or a web request)

Source: framework/core/Notify.php:226

Notify::setEmail()

public static function setEmail($userId, $email)

Sets the user's address (one per user) and emails the confirmation link: valid 24 hours, used once

Parameters

• $userId
• $email

Returns array: the address, and whether the link was sent

Source: framework/core/Notify.php:236

Notify::confirm()

public static function confirm($token)

Confirms an address from its link: the user id, or null when the link is unknown, used or expired

Parameters

• $token

Source: framework/core/Notify.php:255

Notify::unsubscribeUrl()

public static function unsubscribeUrl($userId)

The one-click unsubscribe link of a user's emails (signed with APP_KEY)

Parameters

• $userId

Source: framework/core/Notify.php:269

Notify::unsubscribeEmail()

public static function unsubscribeEmail($userId, $signature)

Turns the user's emails off from a signed link: whether the signature was right

Parameters

• $userId
• $signature

Source: framework/core/Notify.php:277

Notify::html()

public static function html($title, array $paragraphs, $button, $footer, $code = null)

An email in the app's look: the colors, font and corners of its design style (DESIGN_STYLE), else Caligrafy's, written inline since email clients ignore stylesheets. $code: a code to type (shown large), $footer: the last line

Parameters

• $title
• $paragraphs array
• $button
• $footer
• $code, default null

Source: framework/core/Notify.php:321

Notify::theme()

public static function theme($public = null)

The look of the app's emails: Caligrafy's (public/css/look.css), with the design style of DESIGN_STYLE on top (public/css/designs/<name>.css): page, canvas, ink, text, muted, border, primary, on_primary, font, radius, card

Parameters

• $public, default null

Source: framework/core/Notify.php:353

Notify::page()

public static function page($title, $text, $status = 200)

A short page for the links of the emails (Route::notifications)

Parameters

• $title
• $text
• $status, default 200

Source: framework/core/Notify.php:396

Notify::offered()

public static function offered()

The channels the app offers (NOTIFY_CHANNELS, push,email by default)

Source: framework/core/Notify.php:413

Notify::prefer()

public static function prefer($userId, $channel, $enabled)

Turns a channel on or off for a user (a channel without a choice is on)

Parameters

• $userId
• $channel
• $enabled

Source: framework/core/Notify.php:423

Notify::enabled()

public static function enabled($userId, $channel)

No doc comment.

Parameters

• $userId
• $channel

Source: framework/core/Notify.php:430

Notify::status()

public static function status($userId)

What a user sees about their notifications: the channels, their state and the push public key

Parameters

• $userId

Source: framework/core/Notify.php:439

Notify::base()

public static function base()

The app's address, ending with /: APP_URL, else the address of the current web request (null on the command line without APP_URL)

Source: framework/core/Notify.php:478