README

eyeson.team PHP library - create powerful video conferences on demand and easily integrate eyeson with your own PHP applications.

The library offers basic features of eyeson API. See the API documentation to get a full overview, create an issue if you found a bug or have a feature request. Feel free to add an issue at the documentation repo for any general questions you might have.

Installation using Composer

# required php version >= 5.4
$ composer require eyeson/eyeson-php

Usage

Provide your api key and quickly join any room using the join method. You can optionally provide configuration options as a 3rd argument.

$eyeson = new Eyeson('<your-eyeson-api-key>');
// Join a new eyeson video meeting by providing a user's name.
$room = $eyeson->join('Mike', 'standup meeting');
$room->getUrl(); // https://app.eyeson.team?<token> URL to eyeson.team video GUI
// If you do not provide a room name, eyeson will create one for you. Note that
// users **will join different rooms on every request**.
$room = $eyeson->join('mike@eyeson.team');
// You can add additional details to your user, which will be shown in the
// GUI. Choosing a unique identifier will keep the user distinct and ensures
// actions are mapped correctly to this record. E.g. joining the room twice will
// not lead to two different participants in a meeting.
$user = [
  'id' => 'mike@eyeson.team',
  'name' => 'Mike',
  'avatar' => 'https://mikes.website/avatar.png'
];
$room = $eyeson->join($user, 'daily standup');

$guest = $eyeson->registerGuest('John Doe', $room);

Before running any meeting related function like record, layout, or shutdown, make sure that the meeting/room is ready.

if (!$room->isReady()) {
  $room = $eyeson->waitReady($room);
}

You can control the meeting using a joined room, the actions will be triggered by the user who joined, use a control user on demand.

// Send chat message
$eyeson->sendMessage($room, 'hello world!');

// Start a video playback.
$playback = $eyeson->playback($room, [
  'url' => 'https://myapp.com/assets/video.webm',
  'audio' => true
]);
$playback->start();

// Start and stop a recording.
$recording = $eyeson->record($room);
$recording->start();
// later...
$recording->stop();
// check if recording is active
$recording->isActive();
// fetch recording details if needed
$eyeson->getRecordingById($recordingId);
$eyeson->deleteRecordingById($recordingId);
$recordingsList = $eyeson->getRecordingsList($room);

// Create a snapshot
$eyeson->createSnapshot($room);
// fetch snapshot details if needed
$eyeson->getSnapshotById($snapshotId);
$eyeson->deleteSnapshotById($snapshotId);
$snapshotsList = $eyeson->getSnapshotsList($room);

// Start and stop a broadcast.
$broadcast = $eyeson->broadcast($room, [
  'stream_url' => 'https://...'
]);
$broadcast->start();
// later...
$broadcast->stop();
// check if broadcast is active
$broadcast->isActive();

// Get list of meeting participants and filter for only active ("online")
$users = $eyeson->getUsersList($room, true);
// lock meeting room
$eyeson->lockMeeting($room);
// Force stop a running meeting.
$eyeson->shutdown($room);

$list = $eyeson->getAllCurrentMeetings();

Register webhooks to receive updates like new meetings, or recordings in your application.

// Register a webhook
$eyeson->addWebhook('https://my.application/hooks/recordings',
                    Eyeson::$webhookRecording);

// Clear webhook if not needed anymore
$eyeson->clearWebhook();

You can switch from the automatic layout handling to a custom layout and set user positions for the video podium. Note: Use an empty string for an empty position. Additionally, you can hide/show the name inserts in the video.

$layout = $eyeson->layout($room);
$layout->apply([
  'layout' => 'auto',
  'name' => 'present-lower-3',
  'users' => ["5eb3a...994", "5eb3a...d06", ...],
  'voice_activation' => true,
  'show_names' => false
]);
// switch back to automatic layout
$layout->useAuto();
// apply fixed custom layout
$layout->update($userList); // ["5eb3a...994", "5eb3a...d06"]
$layout->showNames();
$layout->hideNames();

Apply overlay and background images. You can send plain text that will automatilcally create an overlay.

$layer = $eyeson->layer($room);
$layer->apply([
  'url' => 'https://myapp.com/assets/meetingBackground.jpg',
  'z-index' => Eyeson::$layerBackground
]);

$layer->setText('Hello World!'); // DEPRECATED!

$layer->setImageURL('https://myapp.com/assets/meetingForeground.png');
$layer->setImageURL('https://myapp.com/assets/meetingBackground.jpg', Eyeson::$layerBackground);

$layer->sendImageFile('./overlay.png');
$layer->sendImageFile('./background.png', Eyeson::$layerBackground);

$layer->clear();
$layer->clear(Eyeson::$layerBackground);

Error handling

API requests can throw an EyesonApiError which is an instance of the PHP Exception. Its getMessage() method contains the API response error message and getCode() contains the API response status code.

use EyesonTeam\Eyeson\Exception\EyesonApiError;

function startRecording($accessKey) {
  try {
    $recording = $eyeson->record($accessKey);
    return $recording->start();
  } catch (EyesonApiError $error) {
    error_log($error->getCode() . ' - ' . $error->getMessage());
    return false;
  }
}

startRecording($accessKey);

Permalink API

Since v2.2.0, eyeson-php includes functions to use with Permalink API. You can read more about it here: https://docs.eyeson.com/docs/rest/advanced/permalink_api

$eyeson = new Eyeson('<your-eyeson-api-key>');

$permalink = $eyeson->permalink->create('<username>', ['name' => '<room_name>', 'widescreen' => true]);
echo $permalink->getId();
echo $permalink->getUrl();
echo $permalink->getGuestUrl();
echo $permalink->getUserToken();
echo $permalink->getGuestToken();

$permalink = $eyeson->permalink->update('<permalink-id>', ['widescreen' => false]);
$permalink = $eyeson->permalink->getById('<permalink-id>');
$permalink = $eyeson->permalink->getAll(['page' => 1, 'limit' => 50, 'expired' => false]);
$permalink = $eyeson->permalink->addUser('<permalink-id>', '<username>', ['id' => '<user-id>']);
$eyeson->permalink->removeUser('<permalink-id>', '<user-token>');
$room = $eyeson->permalink->joinMeeting('<user-token>');
$room = $eyeson->permalink->registerGuest('<username>', '<guest-token>', ['id' => '<user-id>']); # works only if $permalink->isStarted() === true
$eyeson->permalink->delete('<permalink-id>');

Forward stream

Version 2.4.0 adds forward stream support. Learn more about it https://docs.eyeson.com/docs/rest/references/forward

$eyeson = new Eyeson('<your-eyeson-api-key>');
$room = $eyeson->join('Mike', 'standup meeting');

$forward = $eyeson->forward($room);
$forward->source('<forward-id>', '<user-id>', 'audio,video', 'https://...');
$forward->mcu('<forward-id>', 'audio,video', 'https://...');
$forward->playback('<forward-id>', '<play-id>', 'audio,video', 'https://...');

$forward->stop('<forward-id>');

Change log

See CHANGELOG.md.

Development

You can use docker to run the testsuite, see the Makefile for details.

$ make build
$ make test