Skip to content

PHP#

Source code

This is a minimal server application built for PHP that allows:

It internally uses LiveKit PHP SDK.

Running this tutorial#

1. Run LiveKit Server#

You can run LiveKit locally or you can use their free tier of LiveKit Cloud.

Alternatively, you can use OpenVidu, which is a fully compatible LiveKit distribution designed specifically for on-premises environments. It brings notable improvements in terms of performance, observability and development experience. For more information, visit What is OpenVidu?.

  1. Download OpenVidu

    git clone https://github.com/OpenVidu/openvidu-local-deployment

  2. Configure the local deployment

    cd openvidu-local-deployment/community
.\configure_lan_private_ip_windows.bat

    cd openvidu-local-deployment/community
./configure_lan_private_ip_macos.sh

    cd openvidu-local-deployment/community
./configure_lan_private_ip_linux.sh

  3. Run OpenVidu

    docker compose up

To use a production-ready OpenVidu deployment, visit the official OpenVidu deployment guide.

Configure Webhooks

All application servers have an endpoint to receive webhooks from LiveKit. For this reason, when using a production deployment you need to configure webhooks to point to your local application server in order to make it work. Check the Send Webhooks to a Local Application Server section for more information.

Follow the official instructions to run LiveKit locally.

Configure Webhooks

All application servers have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit locally you need to configure webhooks to point to your application server in order to make it work. Check the Webhooks section from the official documentation and follow the instructions to configure webhooks.

Use your account in LiveKit Cloud.

Configure Webhooks

All application servers have an endpoint to receive webhooks from LiveKit. For this reason, when using LiveKit Cloud you need to configure webhooks to point to your local application server in order to make it work. Check the Webhooks section from the official documentation and follow the instructions to configure webhooks.

Expose your local application server

In order to receive webhooks from LiveKit Cloud on your local machine, you need to expose your local application server to the internet. Tools like Ngrok, LocalTunnel, LocalXpose and Zrok can help you achieve this.

These tools provide you with a public URL that forwards requests to your local application server. You can use this URL to receive webhooks from LiveKit Cloud, configuring it as indicated above.

2. Download the tutorial code#

git clone https://github.com/OpenVidu/openvidu-livekit-tutorials.git

3. Run the server application#

To run this server application, you need PHP and Composer installed on your device.

  1. Navigate into the server directory 
    cd openvidu-livekit-tutorials/application-server/php
  2. Install dependencies 
    composer install
  3. Run the application 
    composer start

Warning

LiveKit PHP SDK requires library BCMath. This is available out-of-the-box in PHP for Windows, but a manual installation might be necessary in other OS. Run sudo apt install php-bcmath or sudo yum install php-bcmath

4. Run a client application to test against this server#

To run the client application tutorial, you need an HTTP web server installed on your development computer. A great option is http-server. You can install it via NPM:

npm install -g http-server

  1. Navigate into the application client directory:

    cd openvidu-livekit-tutorials/application-client/openvidu-js

  2. Serve the application:

    http-server -p 5080 ./src

Once the server is up and running, you can test the application by visiting http://localhost:5080. You should see a screen like this:

Accessing your application client from other devices in your local network

One advantage of running OpenVidu locally is that you can test your application client with other devices in your local network very easily without worrying about SSL certificates.

Access your application client through https://xxx-yyy-zzz-www.openvidu-local.dev:5443, where xxx-yyy-zzz-www part of the domain is your LAN private IP address with dashes (-) instead of dots (.). For more information, see section Accessing your app from other devices in your network.

For more information, check the JavaScript tutorial.

To run the client application tutorial, you need Node installed on your development computer.

  1. Navigate into the application client directory:

    cd openvidu-livekit-tutorials/application-client/openvidu-react

  2. Install dependencies:

    npm install

  3. Run the application:

    npm start

Once the server is up and running, you can test the application by visiting http://localhost:5080. You should see a screen like this:

Accessing your application client from other devices in your local network

One advantage of running OpenVidu locally is that you can test your application client with other devices in your local network very easily without worrying about SSL certificates.

Access your application client through https://xxx-yyy-zzz-www.openvidu-local.dev:5443, where xxx-yyy-zzz-www part of the domain is your LAN private IP address with dashes (-) instead of dots (.). For more information, see section Accessing your app from other devices in your network.

For more information, check the React tutorial.

To run the client application tutorial, you need Node installed on your development computer.

  1. Navigate into the application client directory:

    cd openvidu-livekit-tutorials/application-client/openvidu-angular

  2. Install the required dependencies:

    npm install

  3. Serve the application:

    npm start

Once the server is up and running, you can test the application by visiting http://localhost:5080. You should see a screen like this:

Accessing your application client from other devices in your local network

One advantage of running OpenVidu locally is that you can test your application client with other devices in your local network very easily without worrying about SSL certificates.

Access your application client through https://xxx-yyy-zzz-www.openvidu-local.dev:5443, where xxx-yyy-zzz-www part of the domain is your LAN private IP address with dashes (-) instead of dots (.). For more information, see section Accessing your app from other devices in your network.

For more information, check the Angular tutorial.

To run the client application tutorial, you need Node installed on your development computer.

  1. Navigate into the application client directory:

    cd openvidu-livekit-tutorials/application-client/openvidu-vue

  2. Install dependencies:

    npm install

  3. Run the application:

    npm start

Once the server is up and running, you can test the application by visiting http://localhost:5080. You should see a screen like this:

Accessing your application client from other devices in your local network

One advantage of running OpenVidu locally is that you can test your application client with other devices in your local network very easily without worrying about SSL certificates.

Access your application client through https://xxx-yyy-zzz-www.openvidu-local.dev:5443, where xxx-yyy-zzz-www part of the domain is your LAN private IP address with dashes (-) instead of dots (.). For more information, see section Accessing your app from other devices in your network.

For more information, check the Vue tutorial.

To run the client application tutorial, you need Node installed on your development computer.

  1. Navigate into the application client directory:

    cd openvidu-livekit-tutorials/application-client/openvidu-electron

  2. Install the required dependencies:

    npm install

  3. Run the application:

    npm start

The application will seamlessly initiate as a native desktop program, adapting itself to the specific operating system you are using. Once the application is open, you should see a screen like this:

Running your application client from other devices in your local network

One advantage of running OpenVidu locally is that you can test your application client with other devices in your local network very easily without worrying about SSL certificates. For more information, see section Accessing your app from other devices in your network.

For more information, check the Electron tutorial.

To run the client application tutorial, you need Node installed on your development computer.

  1. Navigate into the application client directory:

    cd openvidu-livekit-tutorials/application-client/openvidu-ionic

  2. Install the required dependencies:

    npm install

  3. Serve the application:

    You have two options for running the client application: browser-based or mobile device-based:

    To run the application in a browser, you will need to start the Ionic server. To do so, run the following command:

    npm start

    Once the server is up and running, you can test the application by visiting http://localhost:5080. You should see a screen like this:

    Mobile appearance

    To show the app with a mobile device appearance, open the dev tools in your browser and find the button to adapt the viewport to a mobile device aspect ratio. You may also choose predefined types of devices to see the behavior of your app in different resolutions.

    Accessing your application client from other devices in your local network

    One advantage of running OpenVidu locally is that you can test your application client with other devices in your local network very easily without worrying about SSL certificates.

    Access your application client through https://xxx-yyy-zzz-www.openvidu-local.dev:5443, where xxx-yyy-zzz-www part of the domain is your LAN private IP address with dashes (-) instead of dots (.). For more information, see section Accessing your app from other devices in your network.

    Running the tutorial on a mobile device presents additional challenges compared to running it in a browser, mainly due to the application being launched on a different device, such as an Android smartphone or iPhone, rather than our computer. To overcome these challenges, the following steps need to be taken:

    1. Localhost limitations:

      The usage of localhost in our Ionic app is restricted, preventing seamless communication between the application client and the server.

    2. Serve over local network:

      The application must be served over our local network to enable communication between the device and the server.

    3. Secure connection requirement for WebRTC API:

      The WebRTC API demands a secure connection for functionality outside of localhost, necessitating the serving of the application over HTTPS.

    If you run OpenVidu locally you don't need to worry about this. OpenVidu will handle all of the above requirements for you. For more information, see section Accessing your app from other devices in your network.

    Now, let's explore how to run the application on a mobile device:

    Requirements

    Before running the application on a mobile device, make sure that the device is connected to the same network as your PC and the mobile is connected to the PC via USB or Wi-Fi.

    npm run android

    You will need Ruby and Cocoapods installed in your computer.

    The app must be signed with a development team. To do so, open the project in Xcode and select a development team in the Signing & Capabilities editor.

    npm run ios

    The script will ask you for the device you want to run the application on. You should select the real device you have connected to your computer.

    Once the mobile device has been selected, the script will launch the application on the device and you will see a screen like this:

    This screen allows you to configure the URLs of the application server and the LiveKit server. You need to set them up for requesting tokens to your application server and connecting to the LiveKit server.

    Once you have configured the URLs, you can join a video call room by providing a room name and a user name. After joining the room, you will be able to see your own video and audio tracks, as well as the video and audio tracks of the other participants in the room.

For more information, check the Ionic tutorial.

To run the client application tutorial, you need Android Studio installed on your development computer.

  1. Open Android Studio and import the project located at openvidu-livekit-tutorials/application-client/openvidu-android.

  2. Run the application in an emulator or a physical device by clicking the "Run" button in Android Studio. Check out the official documentation for further information.

The application will initiate as a native Android program. Once the application is opened, you should see a screen like this:

This screen allows you to configure the URLs of the application server and the LiveKit server. You need to set them up for requesting tokens to your application server and connecting to the LiveKit server.

Connecting real Android device to application server running in you local network

One advantage of running OpenVidu locally is that you can test your application client in a real Android device and be able to reach the application server very easily without worrying about SSL certificates if they are both running in the same local network. For more information, see section Accessing your app from other devices in your network.

Once you have configured the URLs, you can join a video call room by providing a room name and a user name. After joining the room, you will be able to see your own video and audio tracks, as well as the video and audio tracks of the other participants in the room.

For more information, check the Android tutorial.

To run the client application tutorial, you need Xcode installed on your MacOS.

  1. Launch Xcode and open the OpenViduIOS.xcodeproj that you can find under openvidu-livekit-tutorials/application-client/openvidu-ios.

  2. Run the application in an emulator or a physical device by clicking on the menu Product > Run or by ⌘R.

Emulator limitations

Publishing the camera track is not supported by iOS Simulator.

If you encounter code signing issues, make sure you change the Team and bundle id from the previous step.

The application will initiate as a native iOS application. Once the app is opened, you should see a screen like this:

This screen allows you to configure the URLs of the application server and the LiveKit server. You need to set them up for requesting tokens to your application server and connecting to the LiveKit server.

Connecting real iOS device to application server running in you local network

One advantage of running OpenVidu locally is that you can test your application client in a real iOS device and be able to reach the application server very easily without worrying about SSL certificates if they are both running in the same local network. For more information, see section Accessing your app from other devices in your network.

Once you have configured the URLs, you can join a video call room by providing a room name and a user name. After joining the room, you will be able to see your own video and audio tracks, as well as the video and audio tracks of the other participants in the room.

For more information, check the iOS tutorial.

Understanding the code#

The application is a simple PHP app with a single file index.php that exports two endpoints:

  • /token : generate a token for a given Room name and Participant name.
  • /livekit/webhook : receive LiveKit webhook events.

Let's see the code of the index.php file:

index.php
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<?php
require __DIR__ . "/vendor/autoload.php";

use Agence104\LiveKit\AccessToken; // (1)!
use Agence104\LiveKit\AccessTokenOptions;
use Agence104\LiveKit\VideoGrant;
use Agence104\LiveKit\WebhookReceiver;
use Dotenv\Dotenv;

Dotenv::createImmutable(__DIR__)->safeLoad();

header("Access-Control-Allow-Origin: *"); // (2)!
header("Access-Control-Allow-Headers: Content-Type, Authorization");
header("Content-type: application/json");

$LIVEKIT_API_KEY = $_ENV["LIVEKIT_API_KEY"] ?? "devkey"; // (3)!
$LIVEKIT_API_SECRET = $_ENV["LIVEKIT_API_SECRET"] ?? "secret"; // (4)!
  1. Import all necessary dependencies from the PHP LiveKit library.
  2. Configure HTTP headers for the web server: enable CORS support, allow the Content-Type and Authorization headers and set the response content type to application/json.
  3. The API key of LiveKit Server.
  4. The API secret of LiveKit Server.

The index.php file imports the required dependencies, sets the HTTP headers for the web server and loads the necessary environment variables:

  • LIVEKIT_API_KEY: the API key of LiveKit Server.
  • LIVEKIT_API_SECRET: the API secret of LiveKit Server.

Create token#

The endpoint /token accepts POST requests with a payload of type application/json, containing the following fields:

  • roomName: the name of the Room where the user wants to connect.
  • participantName: the name of the participant that wants to connect to the Room.
index.php
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<?php
if (isset($_SERVER["REQUEST_METHOD"]) && $_SERVER["REQUEST_METHOD"] === "POST" && $_SERVER["PATH_INFO"] === "/token") {
    $data = json_decode(file_get_contents("php://input"), true);

    $roomName = $data["roomName"] ?? null;
    $participantName = $data["participantName"] ?? null;

    if (!$roomName || !$participantName) {
        http_response_code(400);
        echo json_encode(["errorMessage" => "roomName and participantName are required"]);
        exit();
    }

    $tokenOptions = (new AccessTokenOptions()) // (1)!
        ->setIdentity($participantName);
    $videoGrant = (new VideoGrant()) // (2)!
        ->setRoomJoin()
        ->setRoomName($roomName);
    $token = (new AccessToken($LIVEKIT_API_KEY, $LIVEKIT_API_SECRET)) // (3)!
        ->init($tokenOptions)
        ->setGrant($videoGrant)
        ->toJwt();

    echo json_encode(["token" => $token]); // (4)!
    exit();
}
  1. Create an AccessTokenOptions object with the participant's identity.
  2. Create a VideoGrant object setting the necessary video grants options. setRoomJoin allows the user to join a room and setRoomName determines the specific room. Check out all Video Grants.
  3. We create the AccessToken providing the LIVEKIT_API_KEY and LIVEKIT_API_SECRET, initialize it with the token options, set the video grants and generate the JWT token.
  4. Finally, the token is sent back to the client.

The endpoint first obtains the roomName and participantName parameters from the request body. If they are not available, it returns a 400 error.

If required fields are available, a new JWT token is created. For that we use the LiveKit PHP SDK:

  1. Create an AccessTokenOptions object with the participant's identity.
  2. Create a VideoGrant object setting the necessary video grants options. setRoomJoin allows the user to join a room and setRoomName determines the specific room. Check out all Video Grants.
  3. We create the AccessToken providing the LIVEKIT_API_KEY and LIVEKIT_API_SECRET, initialize it with the token options, set the video grants and generate the JWT token.
  4. Finally, the token is sent back to the client.

Receive webhook#

The endpoint /livekit/webhook accepts POST requests with a payload of type application/webhook+json. This is the endpoint where LiveKit Server will send webhook events.

index.php
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
<?php
$webhookReceiver = (new WebhookReceiver($LIVEKIT_API_KEY, $LIVEKIT_API_SECRET)); // (1)!

if (isset($_SERVER["REQUEST_METHOD"]) && $_SERVER["REQUEST_METHOD"] === "POST" && $_SERVER["PATH_INFO"] === "/livekit/webhook") {
    $headers = getallheaders();
    $authHeader = $headers["Authorization"]; // (2)!
    $body = file_get_contents("php://input"); // (3)!
    try {
        $event = $webhookReceiver->receive($body, $authHeader); // (4)!
        error_log("LiveKit Webhook:");
        error_log(print_r($event->getEvent(), true)); // (5)!
        exit();
    } catch (Exception $e) {
        http_response_code(401);
        echo "Error validating webhook event";
        echo json_encode($e->getMessage());
        exit();
    }
}
  1. Create a new WebhookReceiver object providing the LIVEKIT_API_KEY and LIVEKIT_API_SECRET. It will help validating and decoding incoming webhook events.
  2. The Authorization header of the HTTP request.
  3. The raw body of the HTTP request as a string.
  4. Obtain the WebhookEvent object using the WebhookReceiver#receive method. It takes the raw body as a String and the Authorization header of the request.
  5. Consume the event as you wish.

We first create a WebhookReceiver object using the LIVEKIT_API_KEY and LIVEKIT_API_SECRET. Then we must retrieve the Authorization header and the raw body of the HTTP request. We need both of them to validate and decode the incoming webhook event.

Finally, we obtain the WebhookEvent object using the WebhookReceiver#receive method. It takes the raw body as a String and the Authorization header of the request. We can consume the event as we wish (in this case, we just log it using the error output).

Configure Webhooks

If you are using a production deployment, remember to configure the webhook URL to point to your local application server as explained in the Send Webhooks to a Local Application Server section.