Geekly Articles each Day
📜 ⬆️ ⬇️

Developing FreePBX Modules

image

FreePBX is the most popular web interface for configuring servers based on Asterisk. FreePBX is a flexible, modular system. Offers a rich functionality for setting up stations. The best part is the open source project.


In practice, it is often necessary to solve a unique problem for which typical FreePBX features are not enough.


Within the framework of this article, I will describe the possibilities of expanding the functionality with additional modules.
I will describe the process of developing a new module ...


When do you need to develop a module?


Replicated product - in case you have to support several PBXs of the same type and the same feature is necessary for many. For example (callback, integration with Bitrix chat)


Easy configuration - it is easier and faster to load the module than to edit configs manually. Once laid the logic, and each subsequent installation requires less time.


We reduce the chance of an error - the basic settings are usually made on a test stand, and when transferring to production, there may be difficulties with dependencies. We can put all the necessary files into our module and install them with it.


GREAT OPPORTUNITIES - the development of modules allows you to more flexibly / finely adjust the PBX, for example, it is possible to redefine the diaplan, or add your own lines to the existing one with an accuracy of the priority number.


Asterisk - FreePBX - DB operation scheme



Asterisk can use a database to store call history.
FreePBX - interacts with the database, saves and receives settings. FreePBX modules can access the database to analyze call history.


One of the functions of FreePBX is the creation of configuration files and the delivery of Asterisk AGI scripts. FreePBX knows all about Asterisk system directories, Asterisk can manage.


FreePBX - modular system



The basis of FreePBX is the “ FreePBX Framework ” module (hereinafter simply the Framework). At its core, it is a module that controls other modules. The framework provides a basic web interface:




Each module can extend the functionality of FreePBX, for example, add configs and extend the web interface.
All modules essentially depend on the Framework, and may not depend at all on other modules. Examples of modules:



Saving FreePBX Configuration


After we have changed something in the FreePBX settings, the “ Apply Config ” button appears. The diagram below describes the process of generating configuration files.



The first is the Framework module.



Further the Framework addresses to additional modules, for example the core module



We, as developers, can add your module



Module structure


module.xml
This file describes the basic properties of the module.
The most important properties:



The file structure is described in detail in the documentation .
An example file is shown below:


<module> <rawname>pt1ctraining</rawname> <name>AA Training module</name> <version>2.11.0.6</version> <publisher>telefon1c.ru</publisher> <license>GPLv3+</license> <licenselink>http://www.gnu.org/licenses/gpl-3.0.txt</licenselink> <category>Applications</category> <menuitems> <pt1ctraining>AA Training module (MIKO LCC)</pt1ctraining> </menuitems> <changelog> *2.11.0.6*   </changelog> <depends> <phpversion>5.3.3</phpversion> <module>pt1c ge 2.11.3.18</module> </depends> </module>

install.php


In this file we describe the installation instructions for the module.
In this script it is possible to refer to the “global” variables of FreePBX.


The “ $ db ” variable allows you to interact with the FreePBX database.
An example of creating a table for storing module settings:


 out("  ."); global $db; $sql = "CREATE TABLE IF NOT EXISTS pt1ctraining ( id INTEGER NOT NULL PRIMARY KEY AUTO_INCREMENT, pt1ctraining_id INTEGER NOT NULL, description VARCHAR( 150 ), destination VARCHAR( 50 ), content_app text NOT NULL, path_to_php_agi VARCHAR( 50 ) );"; $check = $db->query($sql); if (DB::IsError($check)) { die_freepbx( "Can not create `pt1ctraining` table: " . $check->getMessage() . "\n"); }

Please note that there is no need to specify the parameters for connecting to the database.


The $ amp_conf variable contains FreePBX configuration parameters (usually defined in /etc/freepbx.conf and /etc/amportal.conf ). Usage example:


 global $amp_conf; out("AMPDBENGINET: " + $amp_conf["AMPDBENGINE"]);

The out () function allows you to display information about the progress of the module installation in the message window:



Example of adding settings to the “ Settings - Advanced Settings ” section:



 $freepbx_conf =& freepbx_conf::create(); if (!$freepbx_conf->conf_setting_exists('pt1ctraining_test')) { $set = array(); $set['value'] = 'all'; $set['defaultval'] = &$set['value']; $set['readonly'] = 0; $set['hidden'] = 0; $set['level'] = 3; $set['module'] = 'pt1ctraining'; $set['category'] = 'AA Test Module'; $set['emptyok'] = 0; $set['sortorder'] = 11; $set['name'] = 'Test settings.'; $set['description'] = 'Description test settings.'; $set['type'] = CONF_TYPE_TEXT; $freepbx_conf->define_conf_setting('pt1ctraining_test',$set,true); }

Etc and agi-bin directories

When installing the module, the contents of the directories will be copied to the corresponding asterisk directories:



Uninstall.php

The script describes the instructions for removing the module. Clean for yourself.


 <?php if (!defined('FREEPBX_IS_AUTH')) { die('No direct script access allowed'); } sql('DROP TABLE pt1ctraining'); ?>

The example above describes an example of using a global function named “ sql ”. As an argument, we pass a test query to delete the table.


In addition, the interesting call “ defined ('FREEPBX_IS_AUTH') ” is used, check whether the user is authorized. It is better to use it for all php scripts.


All scripts and files named index.php are published on the web server and accessed from outside.


If the user tries to access the script without authorization, he will receive a notification “ No direct script access allowed ”



The heart of the module is functions.inc.php


In this file we implement the functions of our module, the key features:



In functions.inc.php hook functions can be defined that will be called by the framework module when generating configs.


Such functions are usually referred to as follows:


 function ModuleName_FunctionName($engine) { // // }

Real function example

Define dialplan in extensions_additional.conf


 function pt1ctraining_get_config($engine) { global $ext; switch ($engine) { case 'asterisk': //   . $context = 'ext-pt1ctraining'; $exten = '_X!'; $ext->add($context, $exten, '', new ext_agi('pt1ctraining_AGI.php')); $ext->add($context, $exten, '', new ext_hangup('')); } }

The “ get_config ” function will be called when creating configuration files when the “ Apply Config ” button is pressed.
The string “ $ engine ” - the name of the engine, usually “asterisk” will be passed as a parameter.


The global variable “ $ ext ” was used to create dialplan, contains an instance of the class “ extensions ”, the class is defined in the file “ /var/www/html/admin/libraries/extensions.class.php ” and provides us with a set of tools for generating dialplan.


The result of the work will be added to extensions_additional.conf :


 [ext-pt1ctraining] exten => _X!,1,AGI(pt1ctraining_AGI.php) exten => _X!,n,Hangup

The classes ext_agi and ext_hangup are also defined in extensions.class.php .


Example of adding to the “[globals]” section of the extensions_additional.conf file

 global $ext; //      "global" $ext->addGlobal('PT1C_TR', 'test'); $ext->addGlobal("#include extension_add_pt1c.conf"."\n;", '\n');

Result of work:


 [globals] CFDEVSTATE = TRUE CAMPONTOGGLE = *84 DNDDEVSTATE = TRUE FMDEVSTATE = TRUE PT1C_TR = test #include extension_add_pt1c.conf ; = \n QUEDEVSTATE = TRUE

To connect an additional file I used a trick in the form of a line break - there is no other solution yet.


Use the setting from " Advanced Settings "


Getting global FreePBX configuration.


 $freepbx_conf =& freepbx_conf::create(); $pt1c_events = $freepbx_conf->get_conf_setting('pt1ctraining_test',true); //  dialplan $ext->add('ext-pt1ctraining-test', '_X!', '', new ext_noop("$pt1c_events")); $ext->add('ext-pt1ctraining-test', '_X!', '', new ext_hangup(''));

The result in the extensions_additional.conf file:

 [ext-pt1ctraining-test] exten => _X!,1,Noop(Privet!!!) exten => _X!,n,Hangup

Edit res_odbc_additional.conf

We use the core module functionality:


 global $core_conf, $amp_conf; $section = 'PT1C_asteriskcdrdb'; $core_conf->addResOdbc($section, array('enabled' => 'yes')); $core_conf->addResOdbc($section, array('dsn' => 'MySQL-asteriskcdrdb')); $core_conf->addResOdbc($section, array('pooling' => 'no')); $core_conf->addResOdbc($section, array('limit' => '1')); $core_conf->addResOdbc($section, array('pre-connect' => 'yes')); $core_conf->addResOdbc($section, array('username' => $amp_conf['AMPDBUSER'])); $core_conf->addResOdbc($section, array('password' => $amp_conf['AMPDBPASS']));

Result of work in res_odbc_additional.conf:

 [PT1C_asteriskcdrdb] enabled=>yes dsn=>MySQL-asteriskcdrdb pooling=>no limit=>1 pre-connect=>yes username=>freepbxuser password=>d52d251931c2

Create your config

You may need to create your own configuration files.
For this purpose, we must define a class with the name “ ModuleName_conf ”. An example of a class is shown below:


 //       . class pt1ctraining_conf { function get_filename() { $files = array( 'extension_additional_pt1ctraining.conf', ); return $files; } function generateConf($file) { switch ($file) { case 'extension_additional_pt1ctraining.conf': return $this->generate_conf(); break; } } function generate_conf() { $output = "[test] ; row 1 \n; Privet"; return $output; } }

The “ get_filename ” method returns an array of files to be created.
The “ generateConf ” method takes the file name as a parameter and returns the text content of this file.


Define your destination


Everyone who worked with FreePBX saw the Set Destination field. Each module can add its own point of destination. To do this, you must define two procedures:


 //         destination. // function pt1ctraining_getdest($exten) { return array('pt1ctraining,'.$exten.',1'); } //   "application"      . // function pt1ctraining_destinations() { $extens[] = array('destination' => 'ext-pt1ctraining,${EXTEN},1' , 'description' => 'IVR'); $extens[] = array('destination' => 'ext-pt1ctraining_2,${EXTEN},1', 'description' => 'IVR_2'); $extens[] = array('destination' => 'ext-pt1ctraining_3,${EXTEN},1', 'description' => 'IVR_3'); return $extens; }

The “ pt1ctraining_getdest ” function should return an array with a single “ drain ” value. The format is “ array ('ModuleName,'. $ Exten. ', 1') ”


The function “ pt1ctraining_destinations ” should return an array with destination points.
Each array element is an associative array with two keys:
' Destination ' - contains Goto compatible parameters, further redirection will be carried out to dialplan using Goto
' Description ' contains the name of the destination point, this is how the value will be presented to the user.


Module pages


Any number of files with the format name “ page.ModuleName.php ” can be defined in the module directory, an example is “ page.pt1ctraining.php ”.


In these files we can define the html form for user interaction.


In order for the web interface to “learn” about the existence of a page, we must indicate the page identifier in the file “ module.xml ” in the “ menuitems ” tag with the page name tag:


 <menuitems> <pt1ctraining>AA Training module (MIKO LCC)</pt1ctraining> </menuitems>

Sample page

 <form autocomplete="off" name="edit" action="<?php $_SERVER['PHP_SELF'] ?>" method="post" onsubmit="return edit_onsubmit();"> <input type="hidden" name="itemid" value="<?php echo $itemid?>"> <input type="hidden" name="action" value="<?php echo ($itemid ? 'edit' : 'add') ?>"> <table> <tr><td colspan="4"><h5> <hr></h5></td></tr> <tr> <td><a href="#" class="info"><span> </span></a></td> <td><input type="text" name="description" class="" value="<?php echo($thisItem['description']); ?>"></td> </tr> <tr> <td><a href="#" class="info">Dialplan:<span>Text dialplan application.</span></a></td> <td><textarea name="content_app" cols=50 rows=5><?php echo($thisItem['content_app']); ?></textarea></td> </tr> </table> </form>

Module assembly


Everything is simple, the module should be packed using tar tools:


 tar -czf pt1ctraining “pt1ctraining-2.11.0.6.tgz";

If the module is prepared for FreePBX 12+, then it is desirable to sign the module with a digital signature by the developer, details are described in the official documentation .


You can sign the module using the devtools utility package :


 sign.php pt1ctraining "KEY"

Where, “ pt1ctraining ” is a directory with a module.


Conclusion


FreePBX is an interesting platform. Offers extensive functionality to configure PBX.
For the case when the FreePBX function is not enough, it is possible to expand the set of functions by means of an additional module.


Own module will allow to get more fine tuning of PBX:



As sources of knowledge I recommend using:



')

Source: https://habr.com/ru/post/308614/

More articles:


All Articles