CoolCMS API

MessageThreadCreatorTrait

Opens a private conversation ({@see \App\UI\Api\Base\Models\Entities\MessageThread}) for an entity and links it through an FK column.

Use it in the Api manager of an entity that starts a conversation (an advert reply in Bazaar and Comcat): call openMessageThreadFor() from afterSave on insert. Sibling of CommentThreadCreatorTrait with the same contract, except that it opens a thread with participants and a first message instead of an empty one.

IMPORTANT: does not open its own transaction; it expects to run inside the consumer's save() transaction. A failure is returned as a Result that the caller answers with a rollback.

IMPORTANT: when no participant has an account, no thread is created (returns null) and messageThreadId stays empty, which is valid because the column is nullable.

Tags
requires

$this->messageThreadManager (Api MessageThreadManager, injected by the consumer)

SaveTrait providing updateColumn()

Table of Contents

Methods

blacklistedWordsForThread()  : array<string|int, string>
Returns the blacklisted words for the message filter. Empty by default (no filter); the consumer (Bazaar / Comcat `ResponseManager`) overrides the hook and supplies the words from its own `BlacklistedWordManager`.
buildMessageParticipant()  : MessageParticipant
Builds a participant from a user id, falling back to a guest. When `$userId` is missing (anonymous advert, logged-out asker), the participant carries contact data and the thread switches to e-mail-only mode.
openMessageThreadFor()  : Result|null
Opens a thread with two participants and a root message and writes its id into `$column` of the entity `$entityId` (default `messageThreadId`).
resolveThreadSubject()  : string|null
Resolves the thread subject from a response: the response subject when filled, otherwise the fallback (the advert title).
containsBlacklistedWord()  : bool
Tells whether the text contains a blacklisted word.

Methods

blacklistedWordsForThread()

Returns the blacklisted words for the message filter. Empty by default (no filter); the consumer (Bazaar / Comcat `ResponseManager`) overrides the hook and supplies the words from its own `BlacklistedWordManager`.

protected blacklistedWordsForThread() : array<string|int, string>

A hook rather than an injected dependency: BlacklistedWord is a module entity, and a shared trait in Core must not reference Bazaar or Comcat.

Return values
array<string|int, string>

buildMessageParticipant()

Builds a participant from a user id, falling back to a guest. When `$userId` is missing (anonymous advert, logged-out asker), the participant carries contact data and the thread switches to e-mail-only mode.

protected buildMessageParticipant(int|null $userId[, string|null $guestName = null ][, string|null $guestEmail = null ][, string|null $guestPhone = null ]) : MessageParticipant
Parameters
$userId : int|null
$guestName : string|null = null
$guestEmail : string|null = null
$guestPhone : string|null = null
Return values
MessageParticipant

openMessageThreadFor()

Opens a thread with two participants and a root message and writes its id into `$column` of the entity `$entityId` (default `messageThreadId`).

protected openMessageThreadFor(int|null $entityId, MessageThreadType $type, string|null $subject, MessageParticipant $sender, MessageParticipant $recipient, string $text[, string|null $ip = null ][, string $column = 'messageThreadId' ]) : Result|null

Pass $sender and $recipient without threadId and role; both are filled in by MessageThreadManager::openThread(). A participant without userId is a guest; the reply channel is derived from that.

Returns a failed Result (the caller may return it from afterSave to roll back), or null when there is nothing to do or everything succeeded.

Parameters
$entityId : int|null
$type : MessageThreadType
$subject : string|null
$sender : MessageParticipant
$recipient : MessageParticipant
$text : string
$ip : string|null = null
$column : string = 'messageThreadId'
Return values
Result|null

resolveThreadSubject()

Resolves the thread subject from a response: the response subject when filled, otherwise the fallback (the advert title).

protected resolveThreadSubject(string|null $preferred, string|null $fallback) : string|null

The raw text is stored without a prefix. The display layer composes the prefix by thread type (MessageThreadType) in the reader's language, so both sides see the subject in their own language. The text is cut to the column length (on overflow the database would otherwise fail the save in strict sql_mode or truncate silently in non-strict).

Parameters
$preferred : string|null
$fallback : string|null
Return values
string|null

containsBlacklistedWord()

Tells whether the text contains a blacklisted word.

private containsBlacklistedWord(string $text) : bool

Detection goes through StringHelper::replaceWords(), the same function that masks blacklisted words elsewhere. A custom search would drift in normalization (diacritics, word boundaries) from what the user sees on the advert.

Parameters
$text : string
Return values
bool
On this page

Search results