README

This library provides a comprehensive suite of tools for generating various Agora authentication tokens within your PHP applications. Agora tokens are essential for securely authenticating users before they access Agora services or join RTC channels.

Overview

Agora uses tokens to ensure that only authorized users can access its services, such as Real-Time Communication (RTC), Real-Time Messaging (RTM), Chat, and more. This SDK simplifies the process of generating these tokens by providing:

• Builders for different Agora services: Easily generate tokens for RTC, RTM, Chat, FPA, APaaS, and Education services.
• Support for multiple token versions: Includes implementations for both older (e.g., AccessToken, DynamicKey) and newer (AccessToken2) Agora token specifications.
• Clear separation of concerns: Core token logic is handled by classes like AccessToken and AccessToken2, while service-specific builders offer a straightforward API.

Supported Tokens and Services

This library supports generating tokens for a variety of Agora services:

• RTC (Real-Time Communication):
  • RtcTokenBuilder: For older RTC token generation (based on AccessToken).
  • RtcTokenBuilder2: For newer RTC token generation (based on AccessToken2), supporting user accounts, UIDs, and fine-grained privileges.
• RTM (Real-Time Messaging):
  • RtmTokenBuilder: For older RTM token generation (based on AccessToken).
  • RtmTokenBuilder2: For newer RTM token generation (based on AccessToken2).
• Chat:
  • ChatTokenBuilder2: For Chat service tokens (user and app tokens, based on AccessToken2).
• FPA (Full-Path Acceleration):
  • FpaTokenBuilder: For FPA service tokens (based on AccessToken2).
• APaaS (Application Platform as a Service) / Education:
  • ApaasTokenBuilder: For APaaS tokens (room user, user, app tokens, based on AccessToken2).
  • EducationTokenBuilder: Functionally identical to ApaasTokenBuilder, provided for semantic clarity in education scenarios (based on AccessToken2).
• Legacy/Specific Tokens:
  • DynamicKey4 and DynamicKey5: For older recording and media channel keys.
  • SignalingToken: For Agora Signaling services (legacy).

The newer AccessToken2 (version "007") and its associated builders (e.g., RtcTokenBuilder2, ChatTokenBuilder2) are generally recommended for most use cases due to their enhanced flexibility and support for multiple services within a single token.

Installation

The recommended way to install this library is via Composer:

composer require ecoleplus/agora

Usage

To use the library, you'll need your Agora App ID and App Certificate. All token generation classes are within the Ecoleplus\Agora\Token namespace.

Example: Generating an RTC Token (using RtcTokenBuilder2)

This example shows how to generate an RTC token that allows a user to join a channel and publish streams.

<?php

require 'vendor/autoload.php';

use Ecoleplus\Agora\Token\RtcTokenBuilder2;

// Required:
$appId = "YOUR_APP_ID";
$appCertificate = "YOUR_APP_CERTIFICATE";
$channelName = "yourChannelName";
$uid = 0; // UID for the user. Use 0 for any user if your app doesn't require specific UIDs.
// Or use user account (string):
// $userAccount = "yourUserAccount";

// Token expiration time in seconds (e.g., 1 hour)
$tokenExpirationInSeconds = 3600;
// Privilege expiration time in seconds (e.g., 1 hour).
// For RtcTokenBuilder2, this is the expiration for all added privileges.
// Set to 0 if privileges should be valid for the entire token duration.
$privilegeExpirationInSeconds = 3600;

// Role (Publisher or Subscriber)
$role = RtcTokenBuilder2::ROLE_PUBLISHER;

// Build token with UID
$token = RtcTokenBuilder2::buildTokenWithUid(
    $appId,
    $appCertificate,
    $channelName,
    $uid,
    $role,
    $tokenExpirationInSeconds,
    $privilegeExpirationInSeconds
);
echo 'RTC Token with UID: ' . $token . PHP_EOL;

// Or, build token with User Account
// $tokenWithUserAccount = RtcTokenBuilder2::buildTokenWithUserAccount(
//     $appId,
//     $appCertificate,
//     $channelName,
//     $userAccount, // Use $userAccount instead of $uid
//     $role,
//     $tokenExpirationInSeconds,
//     $privilegeExpirationInSeconds
// );
// echo 'RTC Token with User Account: ' . $tokenWithUserAccount . PHP_EOL;

// Example: Generating an RTC token with specific privilege expiration times
$joinChannelPrivilegeExpire = 3600;    // Expires in 1 hour
$pubAudioPrivilegeExpire = 3600;       // Expires in 1 hour
$pubVideoPrivilegeExpire = 3600;       // Expires in 1 hour
$pubDataStreamPrivilegeExpire = 3600;  // Expires in 1 hour

$tokenWithPrivileges = RtcTokenBuilder2::buildTokenWithUidAndPrivilege(
    $appId,
    $appCertificate,
    $channelName,
    $uid, // or $userAccount
    $tokenExpirationInSeconds,      // Overall token expiration
    $joinChannelPrivilegeExpire,    // Expiration for join channel privilege
    $pubAudioPrivilegeExpire,       // Expiration for publish audio privilege
    $pubVideoPrivilegeExpire,       // Expiration for publish video privilege
    $pubDataStreamPrivilegeExpire   // Expiration for publish data stream privilege
);
echo 'RTC Token with Specific Privileges: ' . $tokenWithPrivileges . PHP_EOL;

?>

Example: Generating a Chat User Token (using ChatTokenBuilder2)

<?php

require 'vendor/autoload.php';

use Ecoleplus\Agora\Token\ChatTokenBuilder2;

// Required:
$appId = "YOUR_APP_ID";
$appCertificate = "YOUR_APP_CERTIFICATE";
$userId = "chatUser123"; // Unique user ID for chat (string)

// Token expiration time in seconds (e.g., 24 hours)
$tokenExpirationInSeconds = 86400;

// Build Chat User Token
$chatUserToken = ChatTokenBuilder2::buildUserToken(
    $appId,
    $appCertificate,
    $userId,
    $tokenExpirationInSeconds
);
echo 'Chat User Token: ' . $chatUserToken . PHP_EOL;

// Build Chat App Token (for server-side operations, not specific to a user)
// $chatAppToken = ChatTokenBuilder2::buildAppToken(
//    $appId,
//    $appCertificate,
//    $tokenExpirationInSeconds
// );
// echo 'Chat App Token: ' . $chatAppToken . PHP_EOL;

?>

General Parameters

Most token builder methods require common parameters such as:

• $appId (string): Your Agora App ID.
• $appCertificate (string): Your Agora App Certificate.
• $channelName (string, for RTC, etc.): The name of the channel.
• $uid (int or string), $userAccount (string), or $userId (string): Identifier for the user. The specific parameter name and type vary by service and token version.
• $role (int, for RTC, etc.): Defines the user's permissions (e.g., publisher, subscriber). Constants are usually provided in the respective builder classes.
• Expiration times:
  • For builders using AccessToken2 (like RtcTokenBuilder2, ChatTokenBuilder2): These are typically durations in seconds from the time of token generation (e.g., 3600 for 1 hour). This applies to overall token expiration ($tokenExpire) and individual privilege expirations ($privilegeExpire).
  • For older builders using AccessToken (like RtcTokenBuilder): These are typically absolute Unix timestamps (seconds since 1/1/1970) for privilege expiration (e.g., $privilegeExpireTs).

Refer to the specific *TokenBuilder.php files in the src/ directory and their method docblocks for detailed signatures and parameters for each service.

Key Components

• AccessToken.php: Implements Agora's older token logic (version "006"), used by RtcTokenBuilder and RtmTokenBuilder.
• AccessToken2.php: Implements Agora's newer, more versatile token logic (version "007"). This is the core for most modern token builders (RtcTokenBuilder2, ChatTokenBuilder2, etc.) and supports adding multiple services with distinct privileges to a single token.
  • The classes ServiceRtc, ServiceRtm, ServiceFpa, ServiceChat, ServiceApaas are defined within AccessToken2.php. These represent different Agora services and their specific privileges that can be included in an AccessToken2.
• *`TokenBuilder.php files**: These provide static helper methods to simplify the creation of tokens for specific Agora services (e.g., RtcTokenBuilder2.php, ChatTokenBuilder2.php). They typically instantiate and configure AccessToken or AccessToken2` internally.
• DynamicKey4.php & DynamicKey5.php: Implementations for older Agora dynamic key generation, often used for services like recording.
• SignalingToken.php: For generating tokens for Agora's legacy Signaling service.
• Util.php: Contains utility functions for data packing and unpacking, used internally by the token generation logic.

Prerequisites

• An active Agora account.
• An App ID and App Certificate obtained from the Agora Console.
• PHP environment with support for hash_hmac, pack/unpack, DateTime, zlib, and OpenSSL (for random number generation in AccessToken.php's Message salt, though rand() is used there).

Further Information

For more detailed information on Agora tokens, including roles, privileges, and best practices, please refer to the official Agora Authentication Documentation.

This library is provided under the name ecoleplus/agora.