CoolCMS API

MessageConfirmationTrait uses trait:short

Confirmation of a discussion post by its author via an e-mail link: insert handling and e-mails.

IMPORTANT: this is separate from approval by the admin (automaticApproval to approvedAt, InitialApprovalTrait). Both conditions apply independently; a post is publicly visible only when approved and confirmed (confirmedAt IS NOT NULL, regardless of the current setting, which decides only at insert).

On INSERT (thread or reply; front end, external Api, admin) the shared InitialConfirmationTrait decides by author kind through message.confirmation.required.logged (post has userId) / message.confirmation.required.guest (no account) of module 8 (EmailConfirmationSetting):

  • not required: confirmedAt is set to now, no key; after commit the DS_MESSAGE_INSERT e-mail (notification only) is sent.
  • required: a key is issued (a digest in the DB, the readable key goes to the e-mail via $meta) and after commit DS_MESSAGE_ACTIVATION_REQUEST is sent with a ?do=confirm&key=... link to the detail; until the click (:Api:Discussion:Message:confirmByKey) the post is not public.
  • required, but the post has no e-mail or the admin ticked "Confirmed" when creating it: confirmed immediately, no key, no e-mail.

The address is the post's e-mail (Message::$email), also for a logged-in author (parity with adverts); the front form pre-fills it with the account e-mail. E-mails are not sent with suppressNotifications (admin form, tests, imports).

Both e-mails also carry manageLink (self::buildManageLink()): a guest gets a "Manage post" link with a key (parity with adverts), a logged-in author the plain edit link.

Tags
requires

MessageManager getSettingContext() (SettingsTrait), getPresenterContext() (PresenterTrait), $languageContext (LanguageTrait), $emailManager (Api System EmailManager), issueManageKey() (ManageKeyTrait)

Table of Contents

Constants

META_CONFIRMATION_REQUIRED  : string = '__confirmationRequired'
`$meta` key: bool, whether author confirmation was required at insert.

Methods

applyGuestManageSecret()  : void
A guest post gets a fresh random secret in `password` (a value from the payload is ignored). The "Manage post" link ({@see \App\Core\Traits\Api\Models\Managers\ManageKeyTrait}) and the edit capability are bound to it, like an advert to its password; nobody can type it, so a guest manages the post only through the link. A logged-in author's post is left as it is.
applyInitialConfirmation()  : bool
applyInitialMessageConfirmation()  : void
Called from `beforeSave()` on insert only. A logged-in author means the post has `userId` (front end: the logged-in identity; external path: the JWT, `userId` is `#[ExternalReadonly]`).
buildManageLink()  : string
"Manage post" link for both insert e-mails. A guest post gets a link with a `manageKey` that opens the edit without login while it is valid (7 days); unlike an advert, the confirmation request carries it too, because a guest post has no password to fall back on. A logged-in author gets the plain edit link (requires login). An empty string means no link (the template then leaves the paragraph out).
initialConfirmationEmailKind()  : string|null
Returns the e-mail kind to send the author after insert commit: `'activation'` (with the confirmation link), `'insert'` (insert notice only) or `null` for nothing (confirmation was required but no key was issued: an admin confirmed or the e-mail is missing).
sendInsertEmail()  : void
Sends the author an e-mail after the insert commits: with the confirmation link, or just an insert notification. Sends nothing when confirmation was required but no key was issued (admin confirmed or no e-mail).
sendMessageEmail()  : void

Constants

META_CONFIRMATION_REQUIRED

`$meta` key: bool, whether author confirmation was required at insert.

private string META_CONFIRMATION_REQUIRED = '__confirmationRequired'

Methods

applyGuestManageSecret()

A guest post gets a fresh random secret in `password` (a value from the payload is ignored). The "Manage post" link ({@see \App\Core\Traits\Api\Models\Managers\ManageKeyTrait}) and the edit capability are bound to it, like an advert to its password; nobody can type it, so a guest manages the post only through the link. A logged-in author's post is left as it is.

private applyGuestManageSecret(Message $message) : void
Parameters
$message : Message

applyInitialConfirmation()

private applyInitialConfirmation(Advert|Advert|Message<mixed, mixed> $entity, int $module, int|null $ownerUserId, array<string, mixed> &$meta) : bool
Parameters
$entity : Advert|Advert|Message<mixed, mixed>
$module : int

5 = Bazaar, 6 = Comcat, 8 = Discussion

$ownerUserId : int|null
$meta : array<string, mixed>
Return values
bool —

true when a key was issued and the record awaits author confirmation

applyInitialMessageConfirmation()

Called from `beforeSave()` on insert only. A logged-in author means the post has `userId` (front end: the logged-in identity; external path: the JWT, `userId` is `#[ExternalReadonly]`).

private applyInitialMessageConfirmation(Message $message, array<string, mixed> &$meta) : void
Parameters
$message : Message
$meta : array<string, mixed>

buildManageLink()

"Manage post" link for both insert e-mails. A guest post gets a link with a `manageKey` that opens the edit without login while it is valid (7 days); unlike an advert, the confirmation request carries it too, because a guest post has no password to fall back on. A logged-in author gets the plain edit link (requires login). An empty string means no link (the template then leaves the paragraph out).

private buildManageLink(Message $message, PresenterContext $presenterContext) : string
Parameters
$message : Message
$presenterContext : PresenterContext
Return values
string

initialConfirmationEmailKind()

Returns the e-mail kind to send the author after insert commit: `'activation'` (with the confirmation link), `'insert'` (insert notice only) or `null` for nothing (confirmation was required but no key was issued: an admin confirmed or the e-mail is missing).

private initialConfirmationEmailKind(array<string, mixed> $meta) : string|null
Parameters
$meta : array<string, mixed>
Return values
string|null

sendInsertEmail()

Sends the author an e-mail after the insert commits: with the confirmation link, or just an insert notification. Sends nothing when confirmation was required but no key was issued (admin confirmed or no e-mail).

private sendInsertEmail(Message $message, array<string, mixed> $meta) : void
Parameters
$message : Message
$meta : array<string, mixed>

sendMessageEmail()

private sendMessageEmail(Message $message, string $emailKey, string|null $plainKey) : void
Parameters
$message : Message
$emailKey : string
$plainKey : string|null
On this page

Search results