Broadcasting

Broadcasting je predvolene vypnutý — bežné udalosti sa spúšťajú tak či tak. Zapnite ho, ak chcete zmeny posielať naživo cez broadcasting v Laraveli (Reverb, Pusher, Ably, …):

REALTIME_MESSAGES=true

Po zapnutí používajú modely Thread, Participant a Message trait BroadcastsEvents z Laravelu pri vytvorení, úprave, zmazaní a obnovení. Nové vlákno sa ohlási až vtedy, keď sú v ňom jeho účastníci, takže súkromné vlákno sa dostane ku každému z nich. Mäkké zmazanie — zrušenie odoslania či odchod — spustí v Laraveli udalosti modelu trashed aj deleted, no vyšle sa len raz, ako trashed; trvalé zmazanie sa vyšle raz, ako deleted.

Vlákno vysiela len svoje vytvorenie: premenovanie, archivácia ani zmazanie sa nevysielajú. Ak ich chcete posielať, reagujte na udalosti ThreadRenamed a ThreadArchived — alebo zapnite systémové správy, ktoré do vlákna vložia (vysielanú) správu o premenovaní.

Kanály

Autorizácia kanálov

Balík sám žiadne autorizačné callbacky kanálov neregistruje. Zapnete ich cez Messages::channels()->register() — raz, z routes/channels.php alebo z boot() service providera —, prípadne súkromné kanály autorizujete sami v routes/channels.php. Messages::channels() vráti aj názvy kanálov, ktoré odovzdáte klientovi:

use RoundlyConsulting\Messages\Facades\Messages;

// routes/channels.php (or a service provider's boot()) — call it once
Messages::channels()->register();                   // authenticate with the default guard
Messages::channels()->register(['web', 'admin']);   // …or through these guards

// Hand the client the names to subscribe to — without the private- prefix,
// the way Echo.private() and routes/channels.php spell them:
Messages::channels()->participant($user);   // 'messaging.participant.user.5' — new threads for $user
Messages::channels()->thread($thread);      // ['messaging.thread.42'] — messages, reads, typing

• Každý kanál vlákna (broadcasting.messages.channel a broadcasting.participants.channel — predvolene oba messaging.thread.{id}) pustí len aktuálnych účastníkov vlákna.
• Kanál účastníka pustí len model, ktorému patrí — overený používateľ je zúčastnený model.
• register($guards) overí používateľa cez tieto guardy; prázdny zoznam znamená predvolený guard.
• Šablóna vlákna bez {id} nepomenúva žiadne vlákno a callback nedostane a kanál so zastaraným symbolom {type} sa vzorom kanála zachytiť nedá — broadcaster oba odmietne.
• Pri pochybnostiach odmieta: neznáme vlákno, id, ktoré nemôže byť kľúčom nakonfigurovaného typu (overí sa ešte pred dotazom), používateľ, ktorý nie je model, aj hodnota, ktorú váš vlastný route binding zmenil na objekt.
• Pri {name} zdieľajú dve triedy s rovnakým krátkym názvom stále jeden kanál a pustia sa navzájom — použite {alias}.

participant($model) a thread($thread) vracajú názvy bez predpony private-, tak ako ich píšu Echo.private() aj routes/channels.php; thread() vráti zoznam — pri predvolenej konfigurácii jeden názov, dva, ak správam a účastníkom nastavíte rozdielne kanály. Ten istý handle má aj injektovaný manažér a register() spúšťa akciu RegisterBroadcastChannels:

use RoundlyConsulting\Messages\Actions\RegisterBroadcastChannels;
use RoundlyConsulting\Messages\MessagesManager;

app(MessagesManager::class)->channels()->participant($user);   // the injected manager
app(RegisterBroadcastChannels::class)->execute(['web']);       // the action behind register()

Názvy kanálov a udalostí

Každý názov kanála aj udalosti je konfigurovateľný:

'broadcasting' => [
    'enabled' => env('REALTIME_MESSAGES', false),

    'threads' => [
        'public-channel' => 'messaging',
        'per-participant-channel' => 'messaging.participant.{name}.{id}',   // {name}, {alias}, {id} — {type} is deprecated
        'events' => [
            'created' => 'messaging.thread.created',
        ],
    ],

    'participants' => [
        'channel' => 'messaging.thread.{id}',
        'events' => [
            'created' => 'messaging.participant.joined',
            'updated' => 'messaging.participant.read',
            'trashed' => 'messaging.participant.left',
            'restored' => 'messaging.participant.joined',
            'deleted' => 'messaging.participant.left',
        ],
    ],

    'typing' => [
        'event' => 'messaging.participant.typing',
    ],

    'messages' => [
        'channel' => 'messaging.thread.{id}',
        'events' => [
            'created' => 'messaging.message.sent',
            'updated' => 'messaging.message.updated',
            'trashed' => 'messaging.message.unsent',
            'restored' => 'messaging.message.restored',
            'deleted' => 'messaging.message.unsent',
        ],
    ],
],

Zástupné symboly kanála účastníka

Kanál pre každého účastníka prijíma tieto zástupné symboly: {id} je kľúč účastníka; {name} názov jeho triedy malými písmenami (App\Models\User → user); {alias} jeho morph alias, ak typ aliasom je (a obsahuje len znaky, ktoré segment kanála unesie), inak 16-znakový hash typu. Bez morph mapy zdieľajú dva modely s rovnakým názvom triedy — App\Models\User a App\Models\Admin\User — jeden kanál {name} a každý dostáva ohlásenia thread.created toho druhého. {alias} ich oddelí a ku klientovi sa nedostane žiadny názov triedy:

// config/messages.php — 'broadcasting' => [ 'threads' => [ … ] ]
'per-participant-channel' => 'messaging.participant.{alias}.{id}',

// Under a morph map, {alias} is the alias itself:
Relation::morphMap(['diner' => User::class]);
Messages::channels()->participant($user);   // 'messaging.participant.diner.5'

// Without one, it is the first 16 hex characters of the type's SHA-256 — so
// App\Models\User #5 and App\Models\Admin\User #5 get two different channels,
// and neither name contains a class name.

Klienta prihláste na názov, ktorý vráti Messages::channels()->participant($user), namiesto toho, aby ste ho skladali sami — bude tak vždy zodpovedať šablóne. {type} — celý morph typ malými písmenami, s \ nahradeným bodkou — je zastaraný: dáva názov triedy do názvu kanála, ktorý klient vidí, a register() ho autorizovať nedokáže.

Prechod na verziu 2.1

Verzia 2.1.0 nepridáva migráciu a nemení žiadnu predvolenú hodnotu — per-participant-channel zostáva messaging.participant.{name}.{id}. Prepnite ho už teraz na messaging.participant.{alias}.{id}: nasledujúca hlavná verzia z neho urobí predvolenú hodnotu a {type} odstráni. Klienti, ktorí sa prihlasujú na názov z Messages::channels()->participant($user), budú fungovať aj po zmene.

Payloady

• Thread — id, name, is_public, everyone_can_join.
• Participant — id, participant (participateAs()), read_at, joined_at, left_at.
• Message — id, sender (participateAs()), message (po zrušení odoslania null), sent_at, updated_at, deleted_at.
• Písanie — thread_id, participant (participateAs()).

Indikátor písania

Na kanál vlákna vyšlete živý indikátor písania — len sa vysiela (nikdy neukladá), rešpektuje broadcasting.enabled a každého, kto nie je aktuálnym účastníkom, odmietne výnimkou ParticipationException, či je broadcasting zapnutý, alebo nie:

use RoundlyConsulting\Messages\Facades\Messages;

Messages::thread($thread)->typing($user);   // broadcasts ParticipantTyping — never persisted
$thread->typing($user);                     // the same, from the model