FreePBX API: Modules v2

Part of the ApiDocs

The module system is designed to allow distinct modules to provide specific behaviour and enhancements to FreePBX, allowing users to mix and match specific functionality they want without having to have extra "bloat".

Modules are stored in individual directories inside the webroot/admin/modules directory. They must be 'enabled' in the module administration page in the web GUI after being placed (or downloaded via the GUI) into this directory. This runs install scripts, and records the currently installed version into the database (for upgrade purposes).

Version 2

Version 2 revamps the GUI code for modules, and was added shortly after 2.2.0. The primary goal is to make writing GUIs dirt-simple, and address some shortfalls of the previous modules.

• Unified API for building both forms and non-form pages
• GUIs are built with classes, and hooks use classes that closely mirror the original (hook target) class structure
• PEAR's QuickForm library is used to generate forms
  • Mature library that's maintained upstream by PEAR
  • Implements both server-side and (optionally) client-side validation - one line of code is all it takes
• Helper class to generate tables to list items
• Helper functions to insert/update database entries from forms
• Provide a unified API for both Admin and UserPortal interfaces

Files

module.xml

This file defines the basic module information. See module.xml

functions.inc.php

This file is always included when running any part of freepbx, including generating configuration. This allows modules to optionally include functionality from other modules.

This file contains functions called by various parts of the module to save/add/load the items it creates (eg, in the case of a ringgroup module, it has functions like ringgroup_add() ringgroup_load() etc). These must always be prefixed with the module name followed by an underscore. This avoids conflicts with other modules.

It also contains various other functions:

modulename_destinations()

Returns a 2-dimensional associative array of destinations this module provides, for things like inbound routing, IVR, ring group failover, etc.

Note that the 'destination' this module provides is really a 'destination hash', that is, it has no real meaning except as a unique identifier to this module. modulename_translate_destination() (see below) is what takes that hash, and returns the actual engine-specific destination that is used in the backend configuration.

This array is as follows:

  return array(
    array(
      'destination' => 'app-blackhole,hangup,1', 
      'description' => 'Hangup',
    ),
    array(
      'destination' => 'app-blackhole,congestion,1', 
      'description' => 'Congestion'
    ),
  );

The 'destination' value must be a valid destination in the dialplan in the form context,extension,priority. The 'description' value is shown in a drop-down list in the destinations box.

modulename_get_config()

This function takes one parameter, $engine, which is the current engine being used. Currently the only engine is 'asterisk' but you should always check for this anyways.

This function should also declare $ext global, which is the extensions object that will become the dialplan. See ApiExtensions for more detailed information about using the extensions API.

Example:

function mymodule_get_config($engine) {
  global $ext;
  switch($engine) {
    case 'asterisk':
      // "blackhole" destinations
      $ext->add('app-blackhole', 'hangup', '', new ext_noop('Blackhole Dest: Hangup'));
      $ext->add('app-blackhole', 'hangup', '', new ext_hangup());

      $ext->add('app-blackhole', 'congestion', '', new ext_noop('Blackhole Dest: Congestion'));
      $ext->add('app-blackhole', 'congestion', '', new ext_answer());
      $ext->add('app-blackhole', 'congestion', '', new ext_playtones('congestion'));
      $ext->add('app-blackhole', 'congestion', '', new ext_congestion());
      $ext->add('app-blackhole', 'congestion', '', new ext_hangup());
    break;
  }
}

modulename_translate_destination($engine, $destination_hash) (proposed*)

Takes a destination hash ($destination_hash, as modulename_get_destinations() provided, see above) and returns the real dialplan application string to use based on the backend engine ($engine) in use. This is used to support multiple backend engines that don't necessarily use the same syntax for destinations, as well as to allow for greater flexibility in a module changing destination information (rather than other modules storing the exact destination string in their tables).

modulename_active_destinations() (proposed*)

Returns an array, listing all the destinations currently in use by this module. This is used by a freePBX API function get_active_destinations(), that allows modules to check if there are any other modules using something they provide before deleting it (eg, you so you can't delete a ring group while it is assigned as one of the options in an IVR).

The array returned is a 2-dimensional associative array, eg:

ivr_active_destinations() {
  return array(
    array('destination'=>'ringgroup-1', 'desc' => 'Digital receptionist menu 2, key 1', 'link'=>'type=setup&display=ivr&id=2'),
    array('destination'=>'announcement-5', 'desc' => 'Digital receptionist menu 2, key 2', 'link'=>'type=setup&display=ivr&id=2'),
  );
}

• destination is the name of the destination_hash, as returned by the module's _get_destinations() function
• desc is an optional description to be shown to the user when they try to delete the object that provides the destination in question. If ommitted, only the modulename is used
• link is an optional link to use to the item in question, so the user can go directly and remove the dependency if desired. If omitted, no link is used.

install.sql

A straight SQL file that is run (if it exists) during installation and upgrade.

install.php

A PHP script that is run (by being include()'ed) during installation and upgrade.

It is possible for this script to use the database and access other parts of the system. todo: document this more

uninstall.sql

A straight SQL file that is run (if it exists) during uninstallation.

uninstall.php

A PHP script that is run (by being include()'ed) during uninstallation.

admin.menuitem.php

user.menuitem.php

These two files are used to build the admin and UserPortal (respectively) interfaces. For more information see ApiModulesGui

page.menuitem.php

This file is depreciated in version 2, please refer to ApiModules#page.menuitem.php

Installing system files

It is possible for a module to include files that go to other areas of the system, such as an agi script.

See ModuleSubdirectories for more information.

Functions

See ModuleSystemApi?