omnisense/omnimeet Référence de l’API

Omnimeet

Config class

final class Config extends ArrayObject Config.php:13

A gateway's configuration while its factory builds it: the options given, the factory's defaults under them, and the keys that must be filled.

Config::defaults()

public function defaults(array $defaults): self

Sets each key not set yet.

Config::validateNotEmpty()

public function validateNotEmpty(array $keys): void

Config::get()

public function get(string $key, mixed $default = null): mixed

Config::list()

public function list(string $key): array

A list given as one environment variable arrives as a single comma-separated string: split here, at run time.

Gateway class

final class Gateway implements GatewayInterface Gateway.php:15

A gateway's actions behind one door: the first action supporting a request answers it.

Gateway::__construct()

public function __construct(readonly string $name, readonly string $title, readonly Capabilities $capabilities, readonly array $actions)

Gateway::getName()

public function getName(): string

Gateway::getTitle()

public function getTitle(): string

Gateway::capabilities()

public function capabilities(): Capabilities

Gateway::supports()

public function supports(string $request): bool

Gateway::execute()

public function execute(Request\Request $request): Request\Request

Gateway::open()

public function open(Meeting $meeting): Meeting

Gateway::join()

public function join(Meeting $meeting, Participant $participant): Access

Gateway::close()

public function close(Meeting $meeting): Meeting

Gateway::fetch()

public function fetch(Meeting $meeting): Meeting

Gateway::notify()

public function notify(string $body, array $headers = []): Notification

GatewayFactory class

abstract class GatewayFactory implements GatewayFactoryInterface GatewayFactory.php:20

The Omnibus way: a gateway's factory fills a Config - its name, title, capabilities, the options it needs, its client ("omnimeet.api", a closure of the Config: a provider's API, a token signer, a store) and its actions ("omnimeet.action.<name>") - and the gateway is those actions, the client handed to the ones that ask for it.

Nothing here calls anything: a factory whose provider is reached over HTTP takes its client in its own constructor.

GatewayFactory::getName()

public function getName(): string

GatewayFactory::create()

public function create(array $options = []): GatewayInterface

GatewayFactory::createConfig()

public function createConfig(array $options = []): Config

GatewayFactoryInterface interface

interface GatewayFactoryInterface GatewayFactoryInterface.php:6

Builds a gateway from its options (an instance's address, a secret, a relay...).

GatewayFactoryInterface::getName()

public function getName(): string

The name gateways are configured with: "direct", "jitsi".

..

GatewayFactoryInterface::create()

public function create(array $options = []): GatewayInterface

GatewayInterface interface

interface GatewayInterface GatewayInterface.php:22

One way to hold a meeting, configured - the two browsers themselves, or a conferencing service: the same questions for all of them. Each typed method is a shortcut for execute() with its request; a gateway that does not do something throws NotSupportedException, and supports() says so beforehand.

A gateway opens a room and lets someone in. It does not decide who may enter, nor when: the application did, before asking.

GatewayInterface::getName()

public function getName(): string

GatewayInterface::getTitle()

public function getTitle(): string

GatewayInterface::capabilities()

public function capabilities(): Capabilities

What its meetings are: how many people, through whom, with what.

GatewayInterface::supports()

public function supports(string $request): bool

GatewayInterface::execute()

public function execute(Request $request): Request

Returns

answered

Throws

Exception\NotSupportedException

Throws

Exception\ProviderException

GatewayInterface::open()

public function open(Meeting $meeting): Meeting

Open the meeting: it comes back with its reference on this gateway, to keep.

GatewayInterface::join()

public function join(Meeting $meeting, Participant $participant): Access

How this participant enters the (opened) meeting, now: an engine, a frame or an address.

GatewayInterface::close()

public function close(Meeting $meeting): Meeting

Nobody gets in any more; what the gateway kept of the meeting goes.

GatewayInterface::fetch()

public function fetch(Meeting $meeting): Meeting

The meeting as the gateway has it now: its status, who is in.

GatewayInterface::notify()

public function notify(string $body, array $headers = []): Notification

What the provider is telling us (a webhook): checked against its signature, read as one event about one meeting.

Throws

Exception\InvalidNotificationException when the signature does not hold

Registry class

final class Registry Registry.php:16

The application's gateways by name, each built once from its factory and options:

new Registry([new DirectGatewayFactory($signals), new JitsiGatewayFactory()], [ 'direct' => ['factory' => 'direct', 'options' => ['turn_secret' => '...', 'turn_urls' => ['turn:turn.example.org:3478']]], 'group' => ['factory' => 'jitsi', 'options' => ['domain' => 'meet.example.org']], ]);

Registry::__construct()

public function __construct(iterable $factories, readonly array $config)

Registry::get()

public function get(string $name): GatewayInterface

Registry::has()

public function has(string $name): bool

Registry::options()

public function options(string $name): array

Returns

the options a gateway is configured with

Registry::create()

public function create(string $name, array $overrides = []): GatewayInterface

A gateway built afresh, its configured options with $overrides over them - an instance typed in a back office, say. Not kept: get() still gives the configured one.

Registry::names()

public function names(): array

Returns

the configured gateways' names

Registry::all()

public function all(): array

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

Omnimeet\Action

ActionInterface interface

interface ActionInterface ActionInterface.php:8

One thing a gateway does: answers the requests it supports.

ActionInterface::supports()

public function supports(Request $request): bool

ActionInterface::execute()

public function execute(Request $request): void

Sets the request's result, or throws an Omnimeet\Exception\OmnimeetException.

ApiAwareInterface interface

interface ApiAwareInterface ApiAwareInterface.php:6

An action that works through the gateway's own client: a provider's API, a signer, a store.

ApiAwareInterface::setApi()

public function setApi(object $api): void

ApiAwareTrait trait

trait ApiAwareTrait ApiAwareTrait.php:10

ApiAwareTrait::setApi()

public function setApi(object $api): void

Omnimeet\Bridge\Symfony

OmnimeetBundle class

final class OmnimeetBundle extends AbstractBundle OmnimeetBundle.php:43

Omnimeet in a Symfony application: the gateway packages installed (omnimeet/direct, omnimeet/jitsi) registered, the gateways built from configuration and injectable by their name:

omnimeet: gateways: direct: factory: direct options: { turn_secret: '%env(TURN_SECRET)%', turn_urls: '%env(TURN_URLS)%' } group: factory: jitsi options: { domain: meet.example.org, app_id: '%env(JITSI_APP_ID)%', app_secret: '%env(JITSI_APP_SECRET)%' }

public function __construct(GatewayInterface $direct, GatewayInterface $group) }

Nothing is built, nor checked, when the container compiles: a gateway is built the first time it is asked for, and an option left empty only shows then (InvalidConfigException).

A factory is autowired: what its constructor asks for - omnimeet/direct's SignalStoreInterface, an HTTP client - is the application's service of that type, when it has one. An application's own factories (a GatewayFactoryInterface) are registered too, autoconfigured.

OmnimeetBundle::configure()

public function configure(DefinitionConfigurator $definition): void

OmnimeetBundle::loadExtension()

public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void

Omnimeet\Exception

InvalidConfigException class

final class InvalidConfigException extends LogicException implements OmnimeetException InvalidConfigException.php:6

A gateway misconfigured: an option missing, an unknown factory, a meeting not opened yet.

InvalidModelException class

final class InvalidModelException extends InvalidArgumentException implements OmnimeetException InvalidModelException.php:11

A model built with what it cannot hold: a meeting without a key or ending before it starts, a participant without an identifier, an access without its script or its address. An \InvalidArgumentException, as the models threw before.

InvalidNotificationException class

final class InvalidNotificationException extends ProviderException InvalidNotificationException.php:6

A callback that is not the provider's: its signature does not hold, or it is too old.

NotSupportedException class

final class NotSupportedException extends LogicException implements OmnimeetException NotSupportedException.php:12

The gateway does not do that: no callbacks from two browsers talking to each other, no state read from a service that publishes none. supports() says so beforehand.

NotSupportedException::for()

public static function for(Request $request, string $gateway): self

OmnimeetException interface

interface OmnimeetException extends Throwable OmnimeetException.php:6

Every exception Omnimeet throws.

ProviderException class

class ProviderException extends RuntimeException implements OmnimeetException ProviderException.php:6

The provider refused, or could not be reached.

public readonly string $provider

public readonly ?string $providerCode

The provider's own error code, when it gave one

ProviderException::__construct()

public function __construct(public readonly string $provider, string $message, public readonly ?string $providerCode = null, ?\Throwable $previous = null)

Omnimeet\Model

Access class

final readonly class Access Access.php:20

How one participant enters one meeting - what Join answers, and what the page renders. It is made for that participant at that moment (temporary credentials, a signed token): asked again each time, never stored, never shown to anyone else.

ENGINE $engine names a script of the gateway's package, $script is that file on disk (the application serves it), $options what the engine starts with; FRAME $url is the address to frame; when $engine and $script are set, that script drives the frame with $options instead; LINK $url is where to send the participant.

public AccessKind $kind

public ?string $url

public ?string $engine

the name of the script: "direct", "jitsi"

public ?string $script

its file, an absolute path inside the gateway's package

public array $options

what the script is started with: a JSON document

public array $origins

the third parties the participant's browser will talk to ("https://meet.example.org"): none when the call stays between the participants and the application

public array $permissions

what the page or the frame needs from the browser: camera, microphone, display-capture

public ?\DateTimeImmutable $expiresAt

Access::__construct()

public function __construct(public AccessKind $kind, public ?string $url = null, public ?string $engine = null, public ?string $script = null, public array $options = [], public array $origins = [], public array $permissions = ['camera', 'microphone', 'display-capture'], public ?\DateTimeImmutable $expiresAt = null)

$engine

the name of the script: "direct", "jitsi"

$script

its file, an absolute path inside the gateway's package

$options

what the script is started with: a JSON document

$origins

the third parties the participant's browser will talk to ("https://meet.example.org"): none when the call stays between the participants and the application

$permissions

what the page or the frame needs from the browser: camera, microphone, display-capture

Access::engine()

public static function engine(string $engine, string $script, array $options = [], ?\DateTimeImmutable $expiresAt = null): self

Access::frame()

public static function frame(string $url, ?string $engine = null, ?string $script = null, array $options = [], ?array $origins = null, ?\DateTimeImmutable $expiresAt = null): self

$origins

the address's own origin when left out

Access::link()

public static function link(string $url, ?\DateTimeImmutable $expiresAt = null): self

Access::isThirdParty()

public function isThirdParty(): bool

Access::isExpired()

public function isExpired(?\DateTimeInterface $now = null): bool

Access::allow()

public function allow(): string

The frame's allow attribute: "camera; microphone; display-capture".

AccessKind enum

enum AccessKind AccessKind.php:6

The three ways a gateway lets someone in.

case ENGINE = 'engine'

The page runs a JavaScript engine of the gateway's package, on the page's own markup.

case FRAME = 'frame'

The page frames the provider's own interface, and may drive it through a script.

case LINK = 'link'

The participant is sent to an address: nothing is embedded.

Capabilities class

final readonly class Capabilities Capabilities.php:10

What a gateway's meetings are, said before one is opened: how many people, through whom, with what. The operations it answers are asked of the gateway itself (supports()).

public ?int $maxParticipants

how many people one meeting takes; null: the provider's own limit, not known here

public bool $thirdParty

whether anyone but the participants and the application carries or sees the call

public bool $endToEnd

whether the media are encrypted from one participant to the other, with nobody in between able to read them

public bool $recording

whether the gateway can record a meeting

public bool $screenSharing

public bool $chat

public bool $tokens

whether each participant enters with a credential made for them

public array $access

how it lets someone in

Capabilities::__construct()

public function __construct(public ?int $maxParticipants = null, public bool $thirdParty = true, public bool $endToEnd = false, public bool $recording = false, public bool $screenSharing = false, public bool $chat = false, public bool $tokens = false, public array $access = [])

$maxParticipants

how many people one meeting takes; null: the provider's own limit, not known here

$thirdParty

whether anyone but the participants and the application carries or sees the call

$endToEnd

whether the media are encrypted from one participant to the other, with nobody in between able to read them

$recording

whether the gateway can record a meeting

$tokens

whether each participant enters with a credential made for them

$access

how it lets someone in

Capabilities::takes()

public function takes(int $participants): bool

Capabilities::letsInBy()

public function letsInBy(AccessKind $kind): bool

Capabilities::toArray()

public function toArray(): array

Event enum

enum Event Event.php:6

What a provider's callback is about.

case OPENED = 'opened'

The meeting started on the provider's side: its first participant came in.

case JOINED = 'joined'

case LEFT = 'left'

case ENDED = 'ended'

The meeting is over on the provider's side: its last participant left, or it was ended.

case RECORDING_STARTED = 'recording_started'

case RECORDING_ENDED = 'recording_ended'

case RECORDING_READY = 'recording_ready'

A recording can be fetched: Notification::$data has its address.

case OTHER = 'other'

Anything else the provider says: Notification::$type has its own word for it.

Meeting class

final readonly class Meeting Meeting.php:14

A meeting, as the application describes it - its own key, when it starts and ends, a title - and, once a gateway opened it, as the gateway knows it: its reference there, where it stands, who is in. Whom it is for, who may enter and when is the application's business; nothing of it is here.

public string $key

the application's name for it: unguessable when it may reach a third party ("appointment:12" tells and can be guessed; a random token does neither)

public ?\DateTimeImmutable $startsAt

public ?\DateTimeImmutable $endsAt

public ?string $title

shown by a provider that shows one; null says nothing of what the meeting is about

public ?string $reference

the gateway's name for it, once opened: what is kept to join, close and fetch

public Status $status

public array $present

who is in, when the gateway can tell (Fetch)

Meeting::__construct()

public function __construct(public string $key, public ?\DateTimeImmutable $startsAt = null, public ?\DateTimeImmutable $endsAt = null, public ?string $title = null, public ?string $reference = null, public Status $status = Status::PLANNED, public array $present = [])

$key

the application's name for it: unguessable when it may reach a third party ("appointment:12" tells and can be guessed; a random token does neither)

$title

shown by a provider that shows one; null says nothing of what the meeting is about

$reference

the gateway's name for it, once opened: what is kept to join, close and fetch

$present

who is in, when the gateway can tell (Fetch)

Meeting::with()

public function with(?string $reference = null, ?Status $status = null, ?array $present = null): self

The same meeting as its gateway has it now.

Meeting::isOpened()

public function isOpened(): bool

Meeting::reference()

public function reference(): string

The gateway's reference, which only an opened meeting has.

Notification class

final readonly class Notification Notification.php:9

What a provider told the application (a webhook), read as one event about one meeting, its signature checked.

public Event $event

public string $type

the provider's own name for the event

public ?string $reference

the meeting, as Open named it

public ?Participant $participant

public ?\DateTimeImmutable $at

public ?string $id

the same for a callback sent twice: what to deduplicate on

public array $data

the provider's payload

Notification::__construct()

public function __construct(public Event $event, public string $type, public ?string $reference = null, public ?Participant $participant = null, public ?\DateTimeImmutable $at = null, public ?string $id = null, public array $data = [])

$type

the provider's own name for the event

$reference

the meeting, as Open named it

$id

the same for a callback sent twice: what to deduplicate on

$data

the provider's payload

Participant class

final readonly class Participant Participant.php:13

Someone in a meeting, as little as a gateway needs: a role, the name shown to the others, and an identifier that says nothing by itself - never the application's account. A provider on the other side of the network sees exactly this, and no more.

public string $id

opaque and stable for the meeting: "u42", a hash - what the application can find its own account by

public Role $role

public ?string $name

shown to the other participants; null: the gateway's own default, or none

public ?string $locale

the language of the provider's interface, when it has one: "fr", "de"

Participant::__construct()

public function __construct(public string $id, public Role $role = Role::GUEST, public ?string $name = null, public ?string $locale = null)

$id

opaque and stable for the meeting: "u42", a hash - what the application can find its own account by

$name

shown to the other participants; null: the gateway's own default, or none

$locale

the language of the provider's interface, when it has one: "fr", "de"

Participant::host()

public static function host(string $id, ?string $name = null, ?string $locale = null): self

Participant::guest()

public static function guest(string $id, ?string $name = null, ?string $locale = null): self

Participant::isHost()

public function isHost(): bool

Role enum

enum Role Role.php:6

What a participant is in a meeting.

case HOST = 'host'

Whoever holds the meeting: starts it, ends it, moderates it where the gateway has moderators.

case GUEST = 'guest'

Whoever is received.

Status enum

enum Status Status.php:6

Where a meeting stands, as its gateway knows it.

case PLANNED = 'planned'

Described, not opened on a gateway yet: it has no reference.

case OPEN = 'open'

Opened: participants may be let in. Nobody is talking yet, as far as the gateway knows.

case LIVE = 'live'

At least two participants are connected to each other.

case ENDED = 'ended'

Closed: nobody gets in any more.

case UNKNOWN = 'unknown'

The gateway cannot tell.

Status::isOver()

public function isOver(): bool

Status::admits()

public function admits(): bool

Whether a participant may still be let in.

Omnimeet\Request

Close class

final class Close extends Request Close.php:11

Close a meeting: nobody gets in any more, what the gateway kept of it goes. Result: the Meeting, ENDED.

public readonly Meeting $meeting

Close::__construct()

public function __construct(public readonly Meeting $meeting)

Close::getMeeting()

public function getMeeting(): ?Meeting

Fetch class

final class Fetch extends Request Fetch.php:11

The meeting as the gateway has it now. Result: the Meeting with its status and who is in.

public readonly Meeting $meeting

Fetch::__construct()

public function __construct(public readonly Meeting $meeting)

Fetch::getMeeting()

public function getMeeting(): ?Meeting

Join class

final class Join extends Request Join.php:15

Let one participant into an opened meeting. Result: the Access - an engine and its options, a frame, or an address - made for that participant, now. Whether they may enter at all was decided before, by the application.

public readonly Meeting $meeting

public readonly Participant $participant

Join::__construct()

public function __construct(public readonly Meeting $meeting, public readonly Participant $participant)

Join::getAccess()

public function getAccess(): ?Access

Notify class

final class Notify extends Request Notify.php:12

What the provider sent to the application's webhook: the raw body and the request's headers, for the signature. Result: the Notification, or InvalidNotificationException when the signature does not hold.

public readonly string $body

public readonly array $headers

Notify::__construct()

public function __construct(public readonly string $body, public readonly array $headers = [])

Notify::header()

public function header(string $name): ?string

A header, whatever the case it came in.

Notify::getNotification()

public function getNotification(): ?Notification

Open class

final class Open extends Request Open.php:12

Open a meeting on the gateway. Result: the Meeting with its reference there - what the application keeps to let people in, close and fetch.

Opening the same meeting (the same key) twice gives the same reference.

public readonly Meeting $meeting

Open::__construct()

public function __construct(public readonly Meeting $meeting)

Open::getMeeting()

public function getMeeting(): ?Meeting

Request class

abstract class Request Request.php:9

A question put to a gateway. The action that supports it answers by setting the result; the gateway hands the request back.

Request::setResult()

public function setResult(mixed $result): void

Request::getResult()

public function getResult(): mixed

Request::isAnswered()

public function isAnswered(): bool