Como outra extensão do Flarum 2 pode reagir à atividade do chat, publicar em canais, mudar quem pode fazer o quê, adicionar campos na API e colocar interface dentro do chat. Tudo aqui é um ponto de extensão público, usado pelo próprio chat.
- Pacote Composer:
ramon/chat
- Id da extensão:
ramon-chat
- Namespace PHP:
Ramon\Chat\
- Imports JS:
ext:ramon/chat/…
- Namespace de tradução:
ramon-chat.*
Visão geral
Três regras moldam todos os pontos de extensão abaixo.
- Um único caminho de escrita. Mensagens de usuário passam pelo
Service\MessageDispatcher, que valida, aplica rate limit, salva, vincula uploads, sincroniza menções e atualiza contadores de não lidas em uma só transação. Construa em cima dele em vez de salvar um Message por conta própria.
- Eventos após o commit. A maioria dos eventos dispara depois que a escrita no banco já é definitiva, então o listener pode enfileirar trabalho ou chamar outros serviços com segurança. Os poucos que disparam dentro da transação estão marcados abaixo.
- Policies se abstêm por padrão. Toda ability do chat retorna
null quando não tem opinião, então sua policy pode adicionar um deny() ou allow() sem brigar com a do chat.
As integrações do próprio chat (tags, realtime, menções, GDPR, audit, fof/upload) são opcionais. Faça a sua do mesmo jeito: declare ramon/chat em suggest no composer.json se sua extensão também funciona sem ele, e proteja os extenders com Extend\Conditional.
// extend.php
use Flarum\Extend;
return [
(new Extend\Conditional())
->whenExtensionEnabled('ramon-chat', fn () => [
(new Extend\Event())
->listen(\Ramon\Chat\Event\MessageWasSent::class, Listener\MirrorChatMessage::class),
]),
];
Ouvindo eventos
Todos os eventos ficam em Ramon\Chat\Event. São classes simples, com propriedades públicas promovidas no construtor. $actor é null quando a mudança veio do sistema: um webhook, um job de retenção ou um anúncio de bot.
Mensagens
MessageWasSent — Message $message, ?User $actor — após o commitMessageWasEdited — Message $message, ?User $actor — após salvarMessageWasDeleted — Message $message, ?User $actor (exclusão lógica) — após salvarMessageWasRestored — Message $message, ?User $actor — após salvarMessageWasPurged — int $messageId, Channel $channel, ?int $threadId, ?User $actor (a linha já não existe) — após excluirReactionToggled — Message $message, User $actor, string $emoji, bool $added — após salvarMessagePinToggled — Message $message, ?User $actor — após salvarMessageWasMoved — Message $message, Channel $from, Channel $to, ?User $actor, uma vez por mensagem — dentro da transaçãoMessagesWereMoved — array $messageIdsBySource, array $sources, Channel $target, array $threadIds, ?User $actor, uma vez por movimentação — após o commit
Tópicos e canais
ThreadWasCreated — Thread $thread, ?User $actor — após o commitThreadWasEdited — Thread $thread, ?User $actor, só quando algo mudou — após salvarChannelWasCreated — Channel $channel, ?User $actor, também para novos canais diretos — após o commitChannelWasEdited — Channel $channel, ?User $actor, também quando a imagem muda — após salvarChannelStatusChanged — Channel $channel, string $previousStatus, ?User $actor — após salvarChannelWasArchived — Channel $channel, Discussion $discussion, ?User $actor — dentro da transaçãoChannelWasDeleted — Channel $channel, ?User $actor (exclusão lógica) — após salvarChannelModeratorChanged — Channel $channel, User $user, bool $isModerator, ?User $actor — após salvarChannelRanksChanged — Channel $channel, ?User $actor — após salvar
Participação, convites e propriedade
UserJoinedChannel — Channel $channel, User $user, ?User $actor, bool $hidden, bool $automatic, bool $acceptedInvite, ?User $invitedBy — após salvarUserLeftChannel — Channel $channel, User $user, ?User $actor, bool $hidden — após salvarUserWasInvited — Channel $channel, User $user, User $inviter, ChannelInvite $invite, uma vez por convite — após salvarInviteWasCancelled — Channel $channel, User $user, User $actor, ?User $inviter — após excluirInviteWasDeclined — Channel $channel, User $user, ?User $inviter — após excluirOwnershipTransferRequested — Channel $channel, ChannelTransfer $transfer, User $from, User $to — após o commitOwnershipTransferEnded — Channel $channel, ChannelTransfer $transfer, string $reason, ?User $actor. $reason é DECLINED, CANCELLED ou REPLACED; a linha já foi excluída — após o commitChannelOwnershipTransferred — Channel $channel, User $newOwner, ?User $previousOwner, ?ChannelTransfer $transfer, ?User $initiator, bool $inherited. $inherited é verdadeiro na sucessão, quando o dono saiu — após o commitFlagsChanged — ?User $actor: a fila de moderação mudou — após salvar
Entradas em massa são silenciosas. Adicionar um grupo inteiro a um canal automaticamente (MembershipManager::addMany, os jobs de auto-join) não dispara UserJoinedChannel. Use esse evento para entradas feitas por pessoas, não como registro completo de participação.
Exemplo: espelhar mensagens para um log externo
// src/Listener/MirrorChatMessage.php
namespace Acme\ChatMirror\Listener;
use Illuminate\Contracts\Bus\Dispatcher;
use Ramon\Chat\Event\MessageWasSent;
use Acme\ChatMirror\Job\MirrorMessageJob;
class MirrorChatMessage
{
public function __construct(protected Dispatcher $bus)
{
}
public function handle(MessageWasSent $event): void
{
$message = $event->message;
if ($message->isSystem() || $message->channel->isPrivate()) {
return;
}
$this->bus->dispatch(new MirrorMessageJob((int) $message->id));
}
}
Passe ids para os jobs, não modelos nem conteúdo, e recarregue a mensagem dentro do job. O conteúdo de um canal privado não pode sair do fórum sem verificar quem tem permissão de ler.
Publicando mensagens pela sua extensão
Injete Ramon\Chat\Service\MessageDispatcher. Ele é resolvido automaticamente pelo container, então você também pode decorá-lo com $container->extend().
send(Channel $channel, User $actor, string $content, ?Thread $thread = null, ?Message $replyTo = null, array $uploadIds = [], bool $createThread = false): Message — uma mensagem escrita por uma pessoa. O conteúdo passa pelo formatter do fórum, então menções, emoji e BBCode funcionam.sendSystem(Channel $channel, string $key, array $data = []): Message — um aviso de uma linha, sem autor, renderizado no cliente a partir de uma chave de tradução.assertMayRevise(Channel $channel, User $actor, string $content): void — para rodar as mesmas checagens de conteúdo antes de uma edição que você mesmo faz.
O dispatcher não verifica permissões. Ele valida conteúdo, modo lento e rate limits, mas não se o ator pode publicar. Chame $actor->assertCan('postMessage', $channel) antes, como faz o próprio endpoint do chat.
use Ramon\Chat\Channel;
use Ramon\Chat\Service\MessageDispatcher;
$channel = Channel::whereVisibleTo($actor)->findOrFail($channelId);
$actor->assertCan('postMessage', $channel);
$message = $this->dispatcher->send($channel, $actor, 'Saiu a versão 2.4. Notas na tag de anúncios.');
Avisos do sistema
sendSystem() guarda uma chave e dados. O cliente renderiza com ramon-chat.forum.message.system.{key}, passando $data como parâmetros de tradução, que entram como texto. Distribua a chave no seu próprio arquivo de tradução, dentro do namespace do chat.
$this->dispatcher->sendSystem($channel, 'acme_deploy_finished', [
'version' => '2.4.0',
]);
# locale/pt-BR.yml
ramon-chat:
forum:
message:
system:
acme_deploy_finished: "A versão {version} foi publicada."
Prefixe suas chaves com o nome da sua extensão, para nunca colidirem com as do chat: user_joined, user_added, user_accepted_invite, user_left, channel_closed, channel_reopened, channel_archived, discussion_started.
As factories dos modelos (Message::build, buildSystem, buildBot, Channel::build, Thread::build) apenas montam um modelo não salvo. Elas não atualizam contadores, estado de não lidas nem menções, e não disparam eventos — é por isso que o dispatcher existe.
Canais, membros e convites
MembershipManager — join(Channel, User, ?int $notificationLevel = null, bool $hidden = false), leave(Channel, User, ?User $actor = null), updatePreferences(…), addMany(Channel, array $userIds). Sem eventos: dispare UserJoinedChannel / UserLeftChannel você mesmo se quiser que a sala fique sabendo.InvitationManager — invite(Channel, iterable $users, User $inviter), accept, decline, cancel, mayEnter(User, Channel).ChannelArchiver — archive(Channel, User, ?int $discussionId = null, ?string $title = null): Discussion, unarchive(Channel, User).UnreadTracker — markChannelRead(Channel, User, ?int), totalUnreadFor(User), totalUnreadMentionsFor(User).ChannelRanks — book(Channel), forUser(Channel, ?int $userId), assign(Channel, User $actor, User $user, array $rankIds). É um singleton.
Permissões e policies
O chat registra ChannelPolicy, MessagePolicy, ThreadPolicy e uma GlobalPolicy com Extend\Policy. Adicione sua própria policy para o mesmo modelo para restringir ou ampliar uma ability. O Flarum resolve forceDeny acima de forceAllow, acima de deny, acima de allow.
- Global —
useChat, startDirect, createChannel
Channel — view, postMessage, join, joinHidden, edit, close, archive, unarchive, delete, manageMembers, manageModerators, manageRanks, transferOwnership, mentionChannelWide, viewMembersMessage — view, edit, delete, forceDelete, restore, react, bookmark, flag, reply, createThread, move, pin, viewRevisionsThread — view, postMessage, rename
Exemplo: horário de silêncio para quem não é moderador
// src/Access/QuietHoursPolicy.php
namespace Acme\QuietHours\Access;
use Carbon\Carbon;
use Flarum\User\Access\AbstractPolicy;
use Flarum\User\User;
use Ramon\Chat\Channel;
class QuietHoursPolicy extends AbstractPolicy
{
public function postMessage(User $actor, Channel $channel)
{
if ($channel->isDirect() || $actor->hasPermission('ramon-chat.moderate')) {
return null;
}
return Carbon::now()->hour < 7 ? $this->deny() : null;
}
}
// extend.php
(new Extend\Policy())->modelPolicy(\Ramon\Chat\Channel::class, Access\QuietHoursPolicy::class),
Os recursos da API expõem o resultado como flags (canPostMessage, canEdit, canReact e assim por diante), então a interface do chat esconde o campo de escrita e os botões sem nenhuma mudança de frontend da sua parte. Entregas por webhook não têm ator e não passam por postMessage.
Strings de permissão
Verifique estas com $actor->hasPermission(…) quando precisar da concessão bruta em vez de uma ability.
ramon-chat.use (Membros) — abrir o chatramon-chat.accessPrivateChannels (ninguém por padrão) — ver canais de categorias privadasramon-chat.startDirect (Membros) — iniciar mensagens diretasramon-chat.upload (Membros) — anexar arquivosramon-chat.react (Membros) — reaçõesramon-chat.createThread (Membros) — iniciar tópicosramon-chat.sendStickers (Membros) — shortcodes de figurinhas (com ramon/stickers)ramon-chat.flagMessage (Membros) — denunciar mensagensramon-chat.mentionChannelWide (Moderadores) — @here e @allramon-chat.bypassSlowMode (Moderadores) — ignorar o modo lentoramon-chat.moderate (Moderadores) — excluir, mover e restaurar mensagens, e a fila de denúnciasramon-chat.inspectChannels (Moderadores) — entrar em canais privados de forma ocultaramon-chat.pinMessage (ninguém por padrão) — fixar mensagensramon-chat.editChannel (ninguém por padrão) — editar qualquer canalramon-chat.createChannel (Membros, no modo "membros") — criar canais quando os membros são donos dos canaisramon-chat.manageOwnChannels (Membros, no modo "membros") — gerenciar os canais que você criouramon-chat.editOwnChannels (Membros, no modo "membros") — editar os canais que você criou
A visibilidade de canais é garantida por escopos de visibilidade em Channel, Message, Thread e Upload. Carregue sempre os modelos do chat com whereVisibleTo($actor); um find() cru ignora canais privados e restrições de tag.
Recursos da API
O chat é um conjunto de classes AbstractDatabaseResource do Flarum 2, então Extend\ApiResource funciona nelas como funciona nas do core.
chat-channels — Api\Resource\ChannelResource — modelo Channelchat-messages — Api\Resource\MessageResource — modelo Messagechat-threads — Api\Resource\ThreadResource — modelo Threadchat-uploads — Api\Resource\UploadResource — modelo Uploadchat-message-flags — Api\Resource\MessageFlagResource — modelo MessageFlagchat-webhooks — Api\Resource\WebhookResource — modelo Webhook (só admin)
Adicionando um campo
// extend.php
use Flarum\Api\Context;
use Flarum\Api\Schema;
use Ramon\Chat\Api\Resource\ChannelResource;
use Ramon\Chat\Channel;
(new Extend\ApiResource(ChannelResource::class))
->fields(fn () => [
Schema\Boolean::make('acmeCanExport')
->get(fn (Channel $channel, Context $context) =>
$context->getActor()->can('acme.exportChat') && ! $channel->isDirect()
),
]),
O endpoint de listagem de canais devolve até 50 linhas, e o de mensagens até 100. Uma query dentro de ->get() roda uma vez por linha. Prefira dados que já estão no modelo, uma relação com eager loading ou uma coluna de contador.
Campos que o chat adiciona ao core
- Forum:
canUseChat, canCreateChatChannel, canStartChatDirect, canUploadChatFiles, canSendChatStickers, canFlagChatMessages, canModerateChat, canMentionChatChannelWide, canBypassChatSlowMode, canCurateChatChannels, chatOpenFlagsCount.
- User (apenas o próprio):
chatUnreadChannelsCount, chatUnreadMessagesCount, chatUnreadMentionsCount.
- Relações de User:
$user->chatChannels e $user->chatMessages.
Filtros
Usáveis como filter[…] nos endpoints de listagem.
/api/chat-channels — type, status, following, q/api/chat-messages — channel, thread, lessThan, greaterThan, updatedSince, bookmarked, pinned, q/api/chat-threads — channel, participating/api/users — chatChannel (membros de um canal)
Realtime
Com o flarum/realtime ativo, o chat envia eventos para o canal privado de cada destinatário, private-user={id}. Os destinatários são os membros do canal que podem vê-lo; nada vai para um canal público.
ramonChat.message — a mensagem completa: id, channelId, threadId, contentHtml, user, uploads, mentionedUsers, authorRank e mais. Não é enviada para o autor.ramonChat.messageChanged — mesmo formato, em edição, exclusão, restauração e fixação.ramonChat.messagePurged — {id, channelId, threadId}ramonChat.reaction — {messageId, channelId, emoji, userId, added}ramonChat.thread — {threadId, channelId, originalMessageId, title, repliesCount, lastMessageId}ramonChat.channel — {channelId, status, …}, com created: true ou deleted: true nessas mudanças.ramonChat.membership — {channelId, userId, action, actorId, userCount, …}. action é um de invited, joined, left, invite_declined, invite_cancelled, promoted, demoted, owner_changed, transfer_requested, transfer_ended.ramonChat.messagesMoved — {channelId, movedOut[]} para as origens, {channelId, movedIn[]} para o destino.ramonChat.typing — {channelId, userId, username, typing, expiresIn}ramonChat.ranks — {channelId, rankBook}ramonChat.flags — vazio; a fila de denúncias mudou. Enviado aos moderadores.
Enviando seu próprio evento para os membros de um canal
Ramon\Chat\Realtime\ChatBroadcaster reaproveita a mesma filtragem de destinatários. Ele não faz nada quando o realtime não está configurado, então é seguro chamá-lo sem condição.
use Ramon\Chat\Realtime\ChatBroadcaster;
$this->broadcaster->toChannelMembers($channel, 'acme.pollUpdated', [
'channelId' => (int) $channel->id,
'pollId' => (int) $poll->id,
], exceptUserId: (int) $actor->id);
Envie ids e deixe o cliente buscar o resto pela API, que aplica a visibilidade de novo. Outros métodos: toUser(int $userId, string $event, array $payload) e toModerators(string $event, array $payload).
// cliente
const channel = app.websocket_channels?.user;
channel?.bind('acme.pollUpdated', (data) => {
app.store.find('acme-polls', String(data.pollId)).then(() => m.redraw());
});
Webhooks de entrada
Administradores criam um webhook por canal nas configurações do chat e recebem uma URL com uma chave secreta. Qualquer serviço capaz de enviar um payload no estilo do Slack consegue publicar no canal.
curl -X POST "https://forum.example.com/api/chat/hooks/<chave>" \
-H "Content-Type: application/json" \
-d '{"text": "Build 1842 passou na main."}'
- O texto é lido de
text, depois de data.attributes.text, depois dos campos fallback, text, title e pretext de attachments[]. Um corpo de formulário com payload=<json> também funciona.
- A mensagem não tem autor, é cortada no limite de tamanho do canal e dispara
MessageWasSent com ator null.
- Limites: 120 requisições por minuto por IP e 60 por minuto por webhook. A configuração
ramon-chat.webhooks_enabled desliga todos os webhooks com um 403.
- Uma entrega bem-sucedida responde
201 com o id da nova mensagem.
Para uma extensão do Flarum no mesmo fórum, chame o MessageDispatcher. Webhook é para serviços fora do fórum.
Frontend
A maior parte da interface do chat fica em um chunk carregado sob demanda, na primeira vez que o chat abre. O extend() e o override() do Flarum 2 aceitam um caminho de módulo para esse caso e aplicam sua mudança assim que o módulo carrega.
Exemplo: adicionar um botão em toda mensagem
// js/src/forum/index.tsx
import app from 'flarum/forum/app';
import { extend } from 'flarum/common/extend';
import Button from 'flarum/common/components/Button';
app.initializers.add('acme-chat-translate', () => {
extend('ext:ramon/chat/forum/components/ChatMessage', 'actions', function (vnode, message) {
if (!vnode || message.isSystem() || message.isRedacted()) return;
vnode.children.push(
<Button
className="ChatMessage-action"
icon="fas fa-language"
aria-label={app.translator.trans('acme-chat-translate.forum.translate')}
onclick={() => translate(message)}
/>
);
});
});
actions() retorna null quando a mensagem não tem ações para quem está vendo, então cheque o vnode antes de anexar. O chat não tem ItemList próprio; os métodos abaixo são os lugares onde se enganchar. Todos os módulos ficam em ext:ramon/chat/forum/components/….
ChatMessage — content, actions, reactions, uploads, avatar, replyPreview, threadIndicator, systemRow, tombstone, editedMarkChatComposer — placeholder, sendHint, contextBar, pendingAttachments, submit, onKeyDown, insertAtCursorChannelView — header, pinnedBar, typingIndicator, scrollDownButtonChatSidebar — row(channel), createChannelChatDrawerPanel — channelMenu, floatingButton, bodyChatSelectionBar — moveControls, quote, copy, moveChannelInfoModal — content, settings, moderation, memberTab, memberBadge, memberControlsChatNavButton — view, open (no bundle principal)
Esses são métodos protegidos dos componentes do chat, não uma API versionada. Fixe ramon/chat em uma faixa de versão menor no seu composer.json e teste a cada novo lançamento.
Estado e modelos
O estado compartilhado é um singleton, usado pela gaveta, pela página inteira e pelos handlers de realtime.
import chatState from 'ext:ramon/chat/forum/state/chat';
const channel = chatState.channel(12);
await chatState.send(12, 'Daily em cinco minutos.', { threadId: null });
const stop = chatState.onMembershipChange((channelId) => {
console.debug('participação mudou no canal', channelId);
});
- Modelos da store:
chat-channels, chat-messages, chat-threads, chat-uploads, chat-message-flags, importáveis de ext:ramon/chat/common/models/…. Os métodos de atributo espelham os campos da API, mais auxiliares como Channel.isDirect(), Channel.hasUnread(), Message.isSystem() e Message.mentionsActor().
- Mensagens diretas:
startDirectMessage(user), do bundle principal, abre ou cria um canal direto com aquele usuário.
- Abrindo o chat:
ChatDrawer.open(), ou um link para as rotas /chat, /chat/c/{id} e /chat/c/{id}/t/{threadId}.
- Notificações: os tipos de notificação do chat são
chatMention (com e-mail), chatChannelInvite, chatChannelInviteDeclined, chatMessageFlagged, chatModeratorPromoted, chatOwnershipTransfer, chatOwnershipTransferDeclined e chatOwnershipInherited.
Formatação
As mensagens são parseadas e renderizadas pelo formatter compartilhado do fórum. Qualquer coisa que sua extensão adicione com Extend\Formatter (BBCode, embeds, tags customizadas) também aparece no chat. Se a renderização lançar erro, o chat cai para texto puro escapado naquela mensagem.
Configurações e payload
Valores que o fórum serializa para todo visitante, lidos com app.forum.attribute('ramon-chat.title'):
- int —
ramon-chat.maxMessageLength, ramon-chat.minMessageLength
- int, em bytes —
ramon-chat.maxUploadSize
- bool —
ramon-chat.allowUploads, ramon-chat.threadingDefault, ramon-chat.allowArchivingChannels, ramon-chat.showIcon
- string —
ramon-chat.title, ramon-chat.icon, ramon-chat.notificationSound
- string, int ou null —
ramon-chat.botName, ramon-chat.botAvatarUrl, ramon-chat.botUserId
Configurações só de servidor, lidas com SettingsRepositoryInterface: ramon-chat.channel_ownership (admin ou members), channel_retention_days, dm_retention_days, max_messages_per_second, message_edit_window_minutes, upload_storage, webhooks_enabled.
As preferências de usuário ficam sob chaves ramon-chat.* em users.preferences: enabled, sound, emailNotifications, openInDrawer, sendWithCtrlEnter, allowChannelWideMentions.
Os dados de usuários excluídos são tratados pelo tipo de dado do flarum/gdpr do próprio chat (ChatMessages). Se sua extensão guarda linhas que apontam para mensagens ou canais do chat, registre seu próprio tipo de GDPR para elas.
Limitações conhecidas
- Não há
ItemList na interface do chat. As ações de mensagem e os menus de canal são montados como arrays dentro de métodos, então você estende o vnode retornado.
- Não há registro para novos tipos de evento de realtime; envie os seus com o
ChatBroadcaster e faça o bind no cliente.
- Os campos
username e emoji de um webhook são guardados, mas ainda não aparecem nas mensagens entregues.
- Entradas em massa e automáticas não disparam
UserJoinedChannel.
- A limpeza por retenção remove mensagens antigas sem
MessageWasDeleted nem MessageWasPurged.
Cobre o código do ramon/chat em outubro de 2026. Nomes de classes, eventos e payloads foram lidos do código; nomes de métodos nos componentes de interface podem mudar entre versões menores.
