Fasáda Messages

Celé API tvoria tri vrstvy, ktoré spúšťajú ten istý kód: fasáda Messages, MessagesManager za ňou, ktorý si môžete vložiť cez DI, a triedy akcií so samotnou logikou. Fasáda je najkratšia cesta a odporúčaná voľba. Alias Messages sa registruje automaticky; ak chcete predísť kolízii, importujte plný názov triedy:

use RoundlyConsulting\Messages\Enums\ParticipantRole;
use RoundlyConsulting\Messages\Facades\Messages;

// Start a conversation — the first participant owns a group thread
$thread = Messages::start('Launch')
    ->public()                 // ->private(), ->direct(), ->everyoneCanJoin()
    ->withParticipants([$alice, $bob])
    ->create();

// Direct messages: one thread per pair, found or created
$dm = Messages::direct($alice, $bob);

// Send
Messages::to($thread)->from($alice)->send('Hello');   // + replyingTo(), withAttachment(), attach()
Messages::send($thread, $alice, 'Hello');             // plain text shortcut

// Read state, inbox and listings
Messages::markRead($thread, $bob);
Messages::unreadCount($bob);                  // across all threads, or pass a thread
Messages::inboxFor($bob, perPage: 20);        // see Inbox & read receipts
Messages::threads($bob, perPage: 25);         // $bob's threads + public ones; threads() = public only

// One thread
Messages::thread($thread)->rename('Launch crew', by: $alice);
Messages::thread($thread)->archive(by: $alice);
Messages::thread($thread)->markRead($bob);
Messages::thread($thread)->typing($bob);      // broadcast-only, see Broadcasting
Messages::thread($thread)->messages(perPage: 25);   // newest first, senders eager loaded

// One message
$message = Messages::send($thread, $alice, 'Helo');
Messages::message($message)->edit('Hello', by: $alice);   // author only
Messages::message($message)->delete(by: $alice);          // author, or a manager

// Its participants
Messages::thread($thread)->participants()->add($carol, ParticipantRole::Admin, by: $alice);
Messages::thread($thread)->participants()->setRole($carol, ParticipantRole::Member, by: $alice);
Messages::thread($thread)->participants()->transferOwnership(from: $alice, to: $bob); // $alice → admin
Messages::thread($thread)->participants()->remove($carol, by: $bob);
Messages::thread($thread)->participants()->leave($alice);   // the owner hands over before leaving

// Housekeeping
Messages::prune(days: 30);                    // defaults to messages.prune.days

by: je účastník, ktorý akciu vykonáva; musí byť vo vlákne a jeho oprávnenie sa overí podľa rolí vlákna (pozri Roly a oprávnenia). Pri dôveryhodných serverových volaniach ho vynechajte — žiadna kontrola sa nespustí.

Odosielateľ musí byť vo vlákne

Každé odoslanie — to()->from()->send(), send(), sendMessageTo(), akcia SendMessage — odmietne odosielateľa, ktorý nie je aktuálnym účastníkom (nikdy sa nepridal, odišiel alebo bol odobratý), výnimkou UnauthorizedMessagingAction; typing() ho odmietne výnimkou ParticipationException. Systémová správa nemá odosielateľa a je povolená vždy. Dôveryhodný serverový kód, ktorý píše za niekoho mimo vlákna — bota či agenta podpory — sa musí z kontroly vyňať výslovne:

Messages::to($thread)->from($supportBot)->withoutParticipationCheck()->send('We are on it.');

Metódy fasády

Metóda	Vracia	Akcia
`start(?string $name)`	PendingThread → create(): Thread	StartThread
`to(Thread)`	PendingMessage → send(?string $body): Message (odosielateľ musí byť účastníkom)	SendMessage
`direct(Model, Model)`	Thread	FindOrCreateDirectThread
`send(Thread, ?Model $sender, string $body)`	Message	SendMessage
`markRead(Thread, Model)`	Participant	MarkRead
`unreadCount(Model, ?Thread)`	int	—
`inboxFor(Model, perPage, ?page, pageName)`	LengthAwarePaginator<Thread>	—
`threads(?Model $for, perPage, ?page, pageName)`	LengthAwarePaginator<Thread>	—
`thread(Thread)`	ThreadHandle	—
`thread()->rename(?string, by:) / archive(by:)`	Thread	RenameThread / ArchiveThread
`thread()->markRead(Model)`	Participant	MarkRead
`thread()->typing(Model)`	void	SignalTyping
`thread()->messages(perPage, ?page, pageName)`	LengthAwarePaginator<Message>	—
`thread()->message(Message)`	MessageHandle	— (odmietne iné vlákna)
`thread()->participants()->add(Model, ?ParticipantRole, by:)`	Participant (existujúci záznam, ak už je vo vlákne)	AddParticipant
`thread()->participants()->remove(Model, by:) / leave(Model)`	void	RemoveParticipant / LeaveThread
`thread()->participants()->setRole(Model, ParticipantRole, by:)`	Participant	SetParticipantRole
`thread()->participants()->transferOwnership(from:, to:)`	Participant	TransferOwnership
`message(Message)->edit(string, by:) / delete(by:)`	Message	EditMessage / DeleteMessage
`prune(?int $days, ?Thread)`	int	PruneMessages
`fake()`	MessagesFake	— (pozri Testovanie)

Metódy na čítanie (unreadCount, inboxFor, threads, thread()->messages()) sa pýtajú databázy priamo a žiadnu akciu nemajú. Všetky tri zoznamy čítajú aktuálnu stránku z požiadavky (?page=, resp. ?{pageName}=) rovnako ako paginate() v Eloquente; konkrétnu stránku zafixujete parametrom page:. Uprednostňujete DI alebo samostatné akcie? Pozri DI, akcie, DTO a výnimky.

Handly obmedzené na vlákno odmietnu iné vlákna

Messages::thread($thread)->message($message) vyhodí MessageException, ak správa patrí inému vláknu, a každá metóda participants() prijme model účastníka alebo jeho záznam Participant — záznam z iného vlákna vyhodí ParticipationException. Ak vlákno aj správa prichádzajú z požiadavky, uprednostnite tento obmedzený tvar:

// PATCH /threads/{thread}/messages/{message}
Messages::thread($thread)->message($message)->edit($request->body, by: $request->user());

Oba handly majú metódu model(), ktorá vráti Thread alebo Message, na ktoré sú obmedzené.

Builder vlákna

Messages::start() vracia PendingThread:

Messages::start()                   // the name is optional
    ->named('Launch planning')      // set or change it later
    ->private()                     // or ->public()
    ->withParticipant($alice)       // appends — the first participant becomes the owner
    ->withParticipant($bob)
    ->create();                     // Thread — fires ThreadCreated + ParticipantJoined

named(?string) — nastaví názov (prijíma ho aj start()).
public() / private() — prepíše predvolenú verejnosť.
everyoneCanJoin() — nastaví príznak „ktokoľvek sa môže pridať“.
direct() — vytvorí priame vlákno (vždy nové).
withParticipants(iterable) nahradí zoznam; withParticipant(Model) doň pridá.
create() — terminálna metóda; vráti Thread.

Builder správy

Messages::to($thread) vracia PendingMessage:

use RoundlyConsulting\Messages\Enums\MessageType;
use RoundlyConsulting\Messages\Facades\Messages;

Messages::to($thread)
    ->from($alice)                        // the sender (omit for a senderless message)
    ->withoutParticipationCheck()         // trusted code only — let a non-participant send
    ->ofType(MessageType::Text)           // Text (default) or System
    ->replyingTo($original)               // quote a message in the same thread
    ->withMeta(['client_id' => 'web-42']) // merged into the meta JSON column
    ->withAttachment($draftToken)         // a media-library draft token
    ->attach($request->file('photo'))     // an UploadedFile
    ->send('On it');                      // Message — fires MessageSent

from(Model) — odosielateľ; musí byť aktuálnym účastníkom vlákna.
withoutParticipationCheck() — dovolí písať odosielateľovi, ktorý vo vlákne nie je (alebo už nie je); len pre dôveryhodný serverový kód.
ofType(MessageType) — Text (predvolené) alebo System.
replyingTo(Message) — odpoveď s citáciou správy v tom istom vlákne (pozri Odpovede a citácie).
asSystem(string $key, array $params = []) — preložiteľná systémová správa; odstráni odosielateľa (pozri Úpravy a systémové správy).
withMeta(array) — zlúči ľubovoľné údaje do stĺpca meta.
withAttachment(string) / withAttachments(array) / attach(UploadedFile) — prílohy (pozri Prílohy).
send(?string $body = null) — terminálna metóda; vráti Message a spustí MessageSent.

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky