Laravel ESL : se connecter à FreeSWITCH via l’Event Socket Layer

Le package kstmostofa/laravel-esl permet de se connecter à FreeSWITCH via ESL (Event Socket Layer) et d’envoyer des commandes (status, originate, show channels, sofia, etc.) depuis Laravel. Il fournit une Facade Esl, une gestion de connexion et d’authentification, et la possibilité d’utiliser une connexion personnalisée (host, port, mot de passe) par appel. Ce guide couvre l’installation, la configuration et l’usage de base.

Prérequis

• Laravel 10+ (ou 11/12)
• FreeSWITCH avec Event Socket activé (port 8021 par défaut, mot de passe ClueCon en dev)
• Réseau : le serveur Laravel doit pouvoir joindre le host/port ESL de FreeSWITCH

1. Installation

composer require kstmostofa/laravel-esl

Publication de la config :

php artisan vendor:publish --provider="Kstmostofa\LaravelEsl\LaravelEslServiceProvider"

2. Configuration

Fichier config/esl.php ; les valeurs sont en général surchargées par .env :

ESL_HOST=127.0.0.1
ESL_PORT=8021
ESL_PASSWORD=ClueCon

En production, ESL_PASSWORD doit être changé dans la config FreeSWITCH (event_socket.conf.xml) et dans .env.

3. Utilisation de la Facade Esl

use Kstmostofa\LaravelEsl\Facades\Esl;
use Kstmostofa\LaravelEsl\EslConnectionException;

try {
    $response = Esl::execute('status');
    // $response : corps de la réponse FreeSWITCH (format texte/plain)

    $uuid = Esl::execute('originate user/1000 &echo');
    // Déclencher un appel (ex. user/1000) et passer dans une app (echo). $uuid : identifiant de l’appel.
} catch (EslConnectionException $e) {
    Log::error('ESL : ' . $e->getMessage());
}

4. Helpers de commandes

Le package expose des méthodes pour des commandes fréquentes :

Esl::status();                    // status
Esl::showChannels();              // show channels
Esl::showCalls();                 // show calls
Esl::sofiaStatus();               // sofia status
Esl::sofiaStatusProfile('internal'); // sofia status profile internal

Pour toute autre commande : Esl::execute('ma_commande'). La réponse est le corps brut FreeSWITCH ; un parsing avancé (ex. structure pour show channels) peut nécessiter du code supplémentaire selon la doc du package et de FreeSWITCH.

5. Connexion personnalisée

Pour pointer vers un autre serveur FreeSWITCH ou un autre port/mot de passe :

$custom = Esl::connection('10.0.1.5', 8021, 'autre_mot_de_passe')->execute('status');

La connexion par défaut (config) n’est pas modifiée pour les appels suivants sans connection().

6. Injection de EslConnection

Au lieu de la Facade, vous pouvez injecter EslConnection :

use Kstmostofa\LaravelEsl\EslConnection;
use Kstmostofa\LaravelEsl\EslConnectionException;

class CallController extends Controller
{
    public function __construct(private EslConnection $esl) {}

    public function makeCall(Request $request)
    {
        try {
            $dest = $request->input('destination', 'user/1001');
            $uuid = $this->esl->execute("originate sofia/gateway/mon_gateway/{$dest} &echo");
            return response()->json(['message' => 'Appel initié.', 'uuid' => $uuid]);
        } catch (EslConnectionException $e) {
            Log::error('ESL: ' . $e->getMessage());
            return response()->json(['error' => 'Impossible d’initier l’appel.'], 500);
        }
    }
}

Dépannage

Bonnes pratiques

• Restreindre l’accès au port ESL (firewall, bind sur 127.0.0.1 si Laravel et FreeSWITCH sont sur la même machine) et changer le mot de passe par défaut.
• Logger les erreurs EslConnectionException et les commandes sensibles (originate, etc.) pour l’audit.
• Pour des flux complexes (événements en continu, dialplan), envisager un script dédié (socket, Node, etc.) ou les modules FreeSWITCH ; ESL depuis Laravel convient bien pour des commandes ponctuelles (stats, originate, show).

Ressources

• Tech Verse Daily – Laravel ESL FreeSWITCH
• Packagist / GitHub – kstmostofa/laravel-esl
• FreeSWITCH – Event Socket

Cet article s’inscrit dans notre série de guides technique et développement web. Pour un serveur ou une application sur-mesure, contact.