FreePBX Development - Introducing Bootstrap

by: Moshe Brevda

FreePBX 2.9 introduced a radically new design paradigm as part of its core framework. The implementation design was inspired by the rapid growth of FreePBX over the years which lead to a disarray of “resources”, spewed in many different corners of its framework. In turn, this lead to frustration by developers - especially newcomers - when it came to tracking down, including and using resources in their projects. To contest this chaos, FreePBX put forward a crucial component in it’s framework: Bootstrap.

While modern frameworks almost universally begin at one central file, class, or object, FreePBX - being a relic of a previous generation of coders - is more of a reflection of the passage of time than a shining star in the arena of frameworks. To that extent, there were many different parts, or resources, that were patched in as time went on, to accommodate a growing feature set and to help evolve towards and reflect the callings of the marketplace and the community. For example, there was one file dedicated to setting up the database connection, including parsing the settings file to retrieve the database credentials. There was another file in charge of user authentication. A third would set some headers that would be sent to an end users browser. And connection to Asterisk could be found scattered in many different places throughout the code.

Bootstrap consolidates all these files in one spot, and makes it extremely simple and straight forward for any developer to include any or all resources in to their code, be it a FreePBX modules, an agi/system script, or a totally stand alone project. This is also the first step in any FreePBX module development (note: in regular modules, this is included automatically).

To include bootstrap in a project, all it takes is a few lines of code:

//include freepbx configuration 
if (!@include_once(getenv('FREEPBX_CONF') ? getenv('FREEPBX_CONF') : '/etc/freepbx.conf')) { 
    include_once('/etc/asterisk/freepbx.conf'); 
}

Once included, bootstrap will provide (by default) the following resources:

  1. $db - the database recourse, an object using the antiquated pear db dal
  2. $amp_conf - an array holding all of FreePBX’s setting, including advanced settings and seldomly set/changed settings that don’t require a dedicated gui entry
  3. $astman - a connection to Asterisks’ Manager Interface, via the php-astman object (class)
  4. $cdrdb - a database resource for accessing Asterisks CDR’s (not provided by default)
  5. All module functions - the functions.inc.php of all enabled modules
  6. $benchmark_starttime - A primitive and lightweight benchmarking variable
  7. Usage of freepbx_error_handler() which loges all of FreePBX errors to a central console, alongside with other debug output
  8. Gui authentication (or bypass) for includes done by gui-facing scripts
  9. Access to all the functions that the FreePBX framework offers, including debugging/logging, module management, gui helpers, etc. (as of FreePBX, these will be autoloaded, so you hopeful incur too much overhead…)

With an eye on efficiency, bootstrap is built in a modular way so that individual resources can be toggled from their default to enable/disable individual resources as they are needed or undesired. The above resources can be toggled as follows:

  1. $db - this is always necessary to for basic functionality of FreePBX and CANNOT be disabled
  2. $amp_conf - as above, always needed for basic functionality, CANNOT be disabled
  3. $astman - the connection to the AMI can be disabled with:
    $bootstrap_settings['skip_astman'] = true;
    
  4. $cdrdb - access to asterisk CDR’s is not something that is required for most activities, and hence is DISABLED by default. To enable, add the following before you call bootstrap:
    $bootstrap_settings['cdrdb'] = true;
    
  5. Module functions can either be restricted to any specific modules or to NO modules being included. To disable ALL modules, just set:
    $restrict_mods = true;
    
    To restrict bootstrap to just a handful of modules, add them like:
    $restrict_mods = array('module_1' => true, 'module_2' => true)
    
  6. $benchmark_starttime cannot be disabled, but really doesn’t incur too much overhead
  7. freepbx_error_handler() error handler can be replaced with an error handler of your choice, or even disabled, like:
    //use default php/apache error handler 
    $bootstrap_settings['freepbx_error_handler'] = false; 
    //will use the error handler of your choice 
    //It is not recommended to disable the error handler.
    $bootstrap_settings['freepbx_error_handler'] = 'my_error_handler';
    
  8. To force gui authentication, set:
    $bootstrap_settings['freepbx_auth'] = true;
    
    To have FreePBX assume that its already been authenticated, use:
    $bootstrap_settings['freepbx_auth'] = false;
    
  9. Skipping FreePBX’s framework’s functions cannot be disabled, it would lead to bootstrap/framework not working properly.

As you can see, bootstrap consolidates all of the important resources that enable you to build around the FreePBX framework. Happy coding, can’t wait to see what you have built!