omnibase/mailbox API reference

App\Controller

DemoController class

class DemoController extends AbstractController DemoController.php:24

The demonstrator: it seeds two members and a conversation between them, signs you in as one, walks the mailbox's rules - then hands over to the mailbox itself. "Switch member" swaps you to the other side of the conversation, so both ends of an exchange can be seen in one browser.

Demo scaffolding throughout: a real application signs members in through base-bundle's security controllers.

DemoController::__construct()

public function __construct(readonly EntityManagerInterface $entityManager, readonly Mailbox $mailbox, readonly Security $security)

DemoController::index()

public function index(): Response

DemoController::switch()

public function switch(): Response

Swap to the other member, to read the conversation from the other side.

App\Entity

User class

class User extends User User.php:15

The demo's member. base-bundle's User identifies people by email and has no username; the forum and the mailbox address members by username (an @mention, a recipient typed by hand), so the application's User carries one - as every base-bundle application's User does.

User::getUsername()

public function getUsername(): ?string

User::setUsername()

public function setUsername(string $username): self

User::__toString()

public function __toString(): string

App\Repository

UserRepository class

class UserRepository extends UserRepository UserRepository.php:5

Base\Mailbox

MailboxBundle class

class MailboxBundle extends AbstractBaseBundle MailboxBundle.php:18

Private messages between members: conversations, each with its participants and their own read/archive state.

Deliberately NOT built on Thread: a private message is not content that is published, tagged, liked or listed - it is mail. What it shares with the rest of base-bundle is the User, the Timestamp attributes and the paginator.

MailboxBundle::__construct()

public function __construct()

MailboxBundle::getPath()

public function getPath(): string

Modern layout: package root, templates/ as @Mailbox, entities in src/Entity.

MailboxBundle::build()

public function build(ContainerBuilder $container): void

Base\Mailbox\Attachment\Office

ConversationAudience class

final class ConversationAudience implements AudienceResolverInterface ConversationAudience.php:18

Who reads a conversation's attachments in the vault: whoever takes part in the conversation, and the staff of the desk it was written to. Nobody withdraws one from here.

ConversationAudience::__construct()

public function __construct(readonly EntityManagerInterface $entityManager, readonly Desks $desks)

ConversationAudience::decide()

public function decide(string $attribute, Document $document, UserInterface $user): ?bool

VaultAttachments class

class VaultAttachments VaultAttachments.php:25

A message's attachment kept in omnibase/office's encrypted vault (when mailbox.attachments is on and omnibase/office installed): the file is a Document of the conversation ("mailbox:<id>"), read by its participants through ConversationAudience and logged like any other. The vault does not e-mail about it: the message's own notice does.

const CONTEXT = 'mailbox:'

VaultAttachments::__construct()

public function __construct(readonly DocumentVault $vault, readonly EntityManagerInterface $entityManager, readonly bool $enabled = false)

VaultAttachments::isEnabled()

public function isEnabled(): bool

VaultAttachments::attach()

public function attach(Message $message, UploadedFile $file, User $sender, User $owner): Attachment

$owner

whose document it is: the other participant, or the sender's own when written to a desk

Throws

MailboxException

VaultAttachments::of()

public function of(Conversation $conversation): array

Returns

by message id

Base\Mailbox\Controller\Client

MailboxController class

class MailboxController extends AbstractController MailboxController.php:35

The member's mailbox: inbox, archives, a conversation, composing and replying. Everything is behind ROLE_USER (mailbox.required_role is checked on top in each action).

Route names are mailbox_*; the paths are French, as the site is.

MailboxController::__construct()

public function __construct(EntityManagerInterface $entityManager, readonly Mailbox $mailbox, readonly PaginatorInterface $paginator, readonly TranslatorInterface $translator, readonly int $perPage = 20, readonly string $requiredRole = 'ROLE_USER', readonly ?Desks $desks = null, readonly ?Directory $directory = null, readonly bool $useDirectory = false, readonly int $poll = 0, readonly ?object $attachments = null)

MailboxController::Index()

public function Index(Request $request, string $box = ConversationRepository::BOX_INBOX): Response

MailboxController::Compose()

public function Compose(Request $request, ?string $to = null): Response

MailboxController::Show()

public function Show(Request $request, int $id): Response

MailboxController::State()

public function State(int $id): JsonResponse

What the open conversation's page asks every mailbox.poll seconds: has something arrived?

MailboxController::Reply()

public function Reply(Request $request, int $id): Response

MailboxController::Action()

public function Action(Request $request, int $id, string $action): Response

archive / unarchive / star / unstar / delete - one POST, one switch, CSRF in the form.

MailboxController::Batch()

public function Batch(Request $request, string $action): Response

Several at once from the list: the old inbox's row of checkboxes.

Base\Mailbox\Crypto

MessageCipher class

class MessageCipher MessageCipher.php:17

Subjects and messages encrypted at rest, when mailbox.encrypt is on: libsodium's secretbox, "mbx1:" + base64(nonce + box) in the same columns.

A value without that mark is read as it is - what was written before encryption was turned on stays readable.

Fail closed: asked to encrypt without a usable key (mailbox.key, base64 of 32 bytes), it refuses - the message is not sent, never stored clear.

const PREFIX = 'mbx1:'

MessageCipher::__construct()

public function __construct(readonly bool $enabled = false, ?string $key = null)

MessageCipher::isEnabled()

public function isEnabled(): bool

MessageCipher::isReady()

public function isReady(): bool

Encryption asked for and a key to do it with.

MessageCipher::encrypt()

public function encrypt(string $text): string

Throws

MailboxException error.no_key

MessageCipher::decrypt()

public function decrypt(?string $value): ?string

The clear text; null when it cannot be read (no key, another key, altered).

MessageCipher::isEncrypted()

public static function isEncrypted(?string $value): bool

Base\Mailbox\DependencyInjection

MailboxConfiguration class

class MailboxConfiguration extends AbstractBaseConfiguration MailboxConfiguration.php:8

MailboxConfiguration::getConfigTreeBuilder()

public function getConfigTreeBuilder(): TreeBuilder

MailboxExtension class

class MailboxExtension extends AbstractBaseExtension implements PrependExtensionInterface MailboxExtension.php:12

MailboxExtension::prepend()

public function prepend(ContainerBuilder $container): void

The extension's own tables (mailbox_desk_conversation, mailbox_attachment) are mapped only where desks or attachments are configured: a site that uses neither keeps the three tables it had, and no migration to write.

MailboxExtension::getConfiguration()

public function getConfiguration(array $config, ContainerBuilder $container): MailboxConfiguration

MailboxExtension::load()

public function load(array $configs, ContainerBuilder $container): void

Base\Mailbox\Desk

Desks class

class Desks Desks.php:19

The desks (mailbox.desks): "the secretariat", "the front office". A member writes to one without knowing who is behind it; whoever holds its role - their own, a group's, or through the role hierarchy - reads its conversations and answers them.

Desks::__construct()

public function __construct(readonly EntityManagerInterface $entityManager, readonly RoleHierarchyInterface $roles, readonly array $desks = [])

Desks::isEnabled()

public function isEnabled(): bool

Desks::all()

public function all(): array

Returns

name => label

Desks::has()

public function has(string $desk): bool

Desks::label()

public function label(string $desk): string

Desks::forUser()

public function forUser(User $user): array

Returns

the desks this user answers at

Desks::of()

public function of(Conversation $conversation): ?DeskConversation

Desks::staffs()

public function staffs(User $user, Conversation $conversation): bool

Whether the user reads this conversation as staff of its desk.

Desks::countWaiting()

public function countWaiting(User $user): int

Desks::conversations()

public function conversations(): DeskConversationRepository

The repository, asked only where desks are configured: without them the entity is not mapped (MailboxExtension::prepend) and must not be touched.

Base\Mailbox\Entity

Conversation class

class Conversation Conversation.php:18

A conversation: a subject, its participants, its messages. Replies stay in the conversation rather than starting a new one - what the old inbox did with "rep_s"/"rep_eid" by hand.

Conversation::__construct()

public function __construct(?string $subject = null)

Conversation::__toString()

public function __toString(): string

Conversation::getId()

public function getId(): ?int

Conversation::getSubject()

public function getSubject(): ?string

Conversation::setSubject()

public function setSubject(?string $subject): self

Conversation::getParticipants()

public function getParticipants(): Collection

Conversation::addParticipant()

public function addParticipant(User $user): Participant

Conversation::getParticipant()

public function getParticipant(User $user): ?Participant

Conversation::hasParticipant()

public function hasParticipant(User $user): bool

Conversation::getOthers()

public function getOthers(?User $except = null): array

Returns

everyone in the conversation except $except

Conversation::getMessages()

public function getMessages(): Collection

Conversation::addMessage()

public function addMessage(Message $message): self

Conversation::getLastMessage()

public function getLastMessage(): ?Message

Conversation::getCreatedAt()

public function getCreatedAt(): ?\DateTimeInterface

Conversation::getLastMessageAt()

public function getLastMessageAt(): ?\DateTimeInterface

Conversation::getLastSender()

public function getLastSender(): ?User

Conversation::getMessageCount()

public function getMessageCount(): int

Conversation::isUnreadFor()

public function isUnreadFor(User $user): bool

Unread for this member: something arrived after they last read.

Message class

class Message Message.php:12

One message of a conversation. Plain text; line breaks are kept, nothing else is interpreted.

Message::__construct()

public function __construct(?User $sender = null, ?string $content = null)

Message::__toString()

public function __toString(): string

Message::getId()

public function getId(): ?int

Message::getConversation()

public function getConversation(): ?Conversation

Message::setConversation()

public function setConversation(?Conversation $conversation): self

Message::getSender()

public function getSender(): ?User

Message::setSender()

public function setSender(?User $sender): self

Message::getContent()

public function getContent(): ?string

Message::setContent()

public function setContent(?string $content): self

Message::getCreatedAt()

public function getCreatedAt(): ?\DateTimeInterface

Participant class

class Participant Participant.php:15

One member's view of a conversation: when they last read it, whether they archived or deleted it. The conversation itself is shared; this row is theirs - so one member deleting a conversation never removes it from the other's box.

Participant::__construct()

public function __construct(?Conversation $conversation = null, ?User $user = null)

Participant::getId()

public function getId(): ?int

Participant::getConversation()

public function getConversation(): ?Conversation

Participant::setConversation()

public function setConversation(?Conversation $conversation): self

Participant::getUser()

public function getUser(): ?User

Participant::setUser()

public function setUser(?User $user): self

Participant::getLastReadAt()

public function getLastReadAt(): ?\DateTimeInterface

Participant::markRead()

public function markRead(?\DateTimeInterface $at = null): self

Participant::isArchived()

public function isArchived(): bool

Participant::getArchivedAt()

public function getArchivedAt(): ?\DateTimeInterface

Participant::archive()

public function archive(): self

Participant::unarchive()

public function unarchive(): self

Participant::isDeleted()

public function isDeleted(): bool

Participant::getDeletedAt()

public function getDeletedAt(): ?\DateTimeInterface

Participant::delete()

public function delete(): self

Participant::restore()

public function restore(): self

Participant::isStarred()

public function isStarred(): bool

Participant::setStarred()

public function setStarred(bool $starred): self

Base\Mailbox\Event

MessageSentEvent class

final class MessageSentEvent extends Event MessageSentEvent.php:11

A message was sent - a new conversation's first, or a reply. $desk: the desk it was written to, if any.

public readonly Conversation $conversation

public readonly Message $message

public readonly User $sender

public readonly ?string $desk

public readonly bool $first

MessageSentEvent::__construct()

public function __construct(public readonly Conversation $conversation, public readonly Message $message, public readonly User $sender, public readonly ?string $desk = null, public readonly bool $first = false)

Base\Mailbox\Extension\Entity

Attachment class

class Attachment Attachment.php:14

A file sent with a message: only where it is kept - the id of its document in omnibase/office's encrypted vault - and whether it is a picture to show in the conversation. Its name and content are the vault's.

Attachment::__construct()

public function __construct(Message $message, int $documentId, bool $image = false)

Attachment::getId()

public function getId(): ?int

Attachment::getMessage()

public function getMessage(): Message

Attachment::getDocumentId()

public function getDocumentId(): int

Attachment::isImage()

public function isImage(): bool

DeskConversation class

class DeskConversation DeskConversation.php:16

A conversation written to a desk rather than to someone: its author is its only participant at first; whoever holds the desk's role reads it, and joins it by answering. In a table of its own so that a site without desks has nothing to migrate.

DeskConversation::__construct()

public function __construct(Conversation $conversation, string $desk, ?User $author)

DeskConversation::getId()

public function getId(): ?int

DeskConversation::getConversation()

public function getConversation(): Conversation

DeskConversation::getDesk()

public function getDesk(): string

DeskConversation::getAuthor()

public function getAuthor(): ?User

DeskConversation::isWaiting()

public function isWaiting(): bool

The author wrote last: the desk has something to answer.

Base\Mailbox\Extension\Repository

AttachmentRepository class

class AttachmentRepository extends ServiceEntityRepository AttachmentRepository.php:11

AttachmentRepository::__construct()

public function __construct(ManagerRegistry $registry)

AttachmentRepository::findByConversation()

public function findByConversation(Conversation $conversation): array

Returns

a conversation's attachments, by message id

DeskConversationRepository class

class DeskConversationRepository extends ServiceEntityRepository DeskConversationRepository.php:12

DeskConversationRepository::__construct()

public function __construct(ManagerRegistry $registry)

DeskConversationRepository::findOneByConversation()

public function findOneByConversation(Conversation $conversation): ?DeskConversation

DeskConversationRepository::createDeskQuery()

public function createDeskQuery(array $desks): Query

$desks

the conversations written to those desks, the latest first

DeskConversationRepository::countWaiting()

public function countWaiting(array $desks): int

$desks

how many wait for an answer: their author wrote last

DeskConversationRepository::findWaiting()

public function findWaiting(array $desks, int $limit = 5): array

Base\Mailbox\Form\Model

ComposeModel class

class ComposeModel ComposeModel.php:8

The compose form: recipients as typed usernames, a subject, the first message.

public ?string $recipients = null

Comma-separated usernames; the service resolves and checks them.

public ?string $to = null

With mailbox.directory: a choice of the directory, "desk:<name>" or "user:<id>".

public ?string $subject = null

The longest: the form's subject_max_length option (mailbox.subject_max_length), ComposeType's constraint.

public ?string $content = null

ComposeModel::getRecipientList()

public function getRecipientList(): array

Base\Mailbox\Form\Type

ComposeType class

class ComposeType extends AbstractType ComposeType.php:15

ComposeType::configureOptions()

public function configureOptions(OptionsResolver $resolver): void

ComposeType::buildForm()

public function buildForm(FormBuilderInterface $builder, array $options): void

ReplyType class

class ReplyType extends AbstractType ReplyType.php:13

A reply inside a conversation: the text only.

ReplyType::configureOptions()

public function configureOptions(OptionsResolver $resolver): void

ReplyType::buildForm()

public function buildForm(FormBuilderInterface $builder, array $options): void

Base\Mailbox\Notification

NotifyListener class

final class NotifyListener NotifyListener.php:19

"A message awaits you", when mailbox.notify is on: each other participant who kept the conversation is mailed a link to it - not its content, not its subject, not who wrote. The desk's staff are not mailed: they see what waits in their box.

NotifyListener::__construct()

public function __construct(readonly ?MailerInterface $mailer, readonly UrlGeneratorInterface $urls, readonly TranslatorInterface $translator, readonly bool $enabled = false, readonly ?string $sender = null)

NotifyListener::onMessageSent()

public function onMessageSent(MessageSentEvent $event): void

Base\Mailbox\Recipient

Directory class

class Directory Directory.php:15

Whom a member may write to when mailbox.directory is on: the desks, then the people the site's RecipientProviderInterface services offer. Choices are "desk:<name>" and "user:<id>"; what comes back from the form is looked up here again, never trusted.

Directory::__construct()

public function __construct(readonly Desks $desks, iterable $providers = [])

Directory::choices()

public function choices(User $sender): array

Returns

label => choice

Directory::resolve()

public function resolve(User $sender, ?string $choice): string|User|null

The desk's name, or the user, a choice stands for; null when it was not offered to this sender.

RecipientProviderInterface interface

interface RecipientProviderInterface RecipientProviderInterface.php:13

Whom a member may write to by name rather than by username, when mailbox.directory is on: a site's own rule - a patient's practitioners, a tenant's manager. Autoconfigured (tag mailbox.recipient_provider).

RecipientProviderInterface::recipients()

public function recipients(User $sender): array

Returns

a label => the account

Base\Mailbox\Repository

ConversationRepository class

class ConversationRepository extends ServiceEntityRepository ConversationRepository.php:17

const BOX_INBOX = 'inbox'

const BOX_ARCHIVE = 'archive'

const BOX_SENT = 'sent'

ConversationRepository::createBoxQuery()

public function createBoxQuery(User $user, string $box = self::BOX_INBOX): Query

ConversationRepository::countInbox()

public function countInbox(User $user): int

How many conversations sit in the member's inbox (the quota).

ConversationRepository::countUnread()

public function countUnread(User $user): int

Conversations with something the member has not read yet.

ConversationRepository::findOneForUser()

public function findOneForUser(int $id, User $user): ?Conversation

A conversation the member takes part in (and has not deleted), fully loaded.

MessageRepository class

class MessageRepository extends ServiceEntityRepository MessageRepository.php:15

MessageRepository::findLastBySender()

public function findLastBySender(User $sender): ?Message

The member's latest message, whatever the conversation - the flood check.

ParticipantRepository class

class ParticipantRepository extends ServiceEntityRepository ParticipantRepository.php:14

Base\Mailbox\Service

Mailbox class

class Mailbox Mailbox.php:27

The rules of the mailbox, in one place: who may write to whom, how often, how long a subject may be, how full a box may get. The controller only turns a refusal into a flash.

The limits are the historical site's: 100 conversations in a box, two minutes between two messages, a 55-character subject.

Mailbox::__construct()

public function __construct(readonly EntityManagerInterface $entityManager, readonly Security $security, readonly int $inboxLimit = 100, readonly int $floodInterval = 120, readonly int $subjectMaxLength = 55, readonly int $contentMaxLength = 10000, readonly int $maxRecipients = 5, readonly ?MessageCipher $cipher = null, readonly ?Desks $desks = null, readonly ?EventDispatcherInterface $dispatcher = null)

Mailbox::compose()

public function compose(User $sender, array $usernames, string $subject, string $content): Conversation

Start a conversation. Recipients are usernames, typed by the sender, matched case-insensitively.

Throws

MailboxException

Mailbox::composeTo()

public function composeTo(User $sender, array $recipients, string $subject, string $content): Conversation

Start a conversation with accounts already known (a directory's choice) rather than typed usernames.

Throws

MailboxException

Mailbox::composeToDesk()

public function composeToDesk(User $sender, string $desk, string $subject, string $content): Conversation

Write to a desk (mailbox.desks): the author is the conversation's only participant until someone of the desk answers.

Throws

MailboxException

Mailbox::reveal()

public function reveal(?string $stored): ?string

A subject or a message as written: decrypted when it was stored encrypted; null when it cannot be read.

Mailbox::reply()

public function reply(User $sender, Conversation $conversation, string $content): Message

Throws

MailboxException

Mailbox::markRead()

public function markRead(User $user, Conversation $conversation): void

Mailbox::archive()

public function archive(User $user, Conversation $conversation, bool $archive = true): void

Mailbox::star()

public function star(User $user, Conversation $conversation, bool $starred): void

Mailbox::delete()

public function delete(User $user, Conversation $conversation): void

Delete for this member only. When nobody keeps it any more the conversation itself goes.

Mailbox::countUnread()

public function countUnread(User $user): int

Mailbox::getInboxLimit()

public function getInboxLimit(): int

Mailbox::getSubjectMaxLength()

public function getSubjectMaxLength(): int

MailboxException class

class MailboxException extends RuntimeException MailboxException.php:6

A refusal the member should read: the message is a translation key in the "mailbox" domain.

MailboxException::__construct()

public function __construct(string $key, readonly array $parameters = [])

MailboxException::getParameters()

public function getParameters(): array

Base\Mailbox\Twig

MailboxTwigExtension class

final class MailboxTwigExtension extends AbstractExtension MailboxTwigExtension.php:26

mailbox_unread_count() unread conversations of the signed-in member, for a badge in the site's menu. Counted once per request; null when nobody is signed in or the count cannot be had - a menu must never 500.

|mailbox_text a message body as HTML: escaped, paragraphs and line breaks kept, URLs made clickable. |mailbox_plain a subject or a message as written (decrypted when mailbox.encrypt stored it encrypted). mailbox_desks() the desks the signed-in member answers at (name => label); mailbox_desk_waiting() how many of their conversations wait for an answer.

MailboxTwigExtension::__construct()

public function __construct(readonly Mailbox $mailbox, readonly Security $security, readonly ?Desks $desks = null)

MailboxTwigExtension::getFunctions()

public function getFunctions(): array

MailboxTwigExtension::getFilters()

public function getFilters(): array

MailboxTwigExtension::unreadCount()

public function unreadCount(): ?int

MailboxTwigExtension::desks()

public function desks(): array

Returns

the desks the signed-in member answers at

MailboxTwigExtension::deskWaiting()

public function deskWaiting(): int

MailboxTwigExtension::plain()

public function plain(?string $stored): string

As written; "…" in place of what cannot be decrypted.

MailboxTwigExtension::text()

public function text(?string $content): string