Page tree
Skip to end of metadata
Go to start of metadata

This only applies to FreePBX 2.9+. Trying to use this on FreePBX 2.8 or lower will end up causing you headaches. This is because the entire backend system was re-written in 2.9.

What is bootstrap?

Bootstrap is the new starting point for all things FreePBX. Think of bootstrap in regards to FreePBX as the BIOS is to your computer - it's what jumpstarts everything else in the system. It includes all resources available to FreePBX. Here is a listing of the most important features that are available to you:

  • All framework functions and methode, as well as all active modules functions and methods, declared in each module's functions.inc.php/Modulename.class files (configurable at runtime)
  • PearDB Emulation  $db as an object or FreePBX::Database(); for direct PDO access
  • The Asterisk Manager Connection (AMI) using $astman as an object or FreePBX::astman;
  • FreePBX Configuration Settings using $amp_conf as an array
  • Debugging Functions

The web framework includes bootstrap.php as the very first thing it does. Any agi/system script can simply include bootstrap.php and have access to all the above resources!

Why bootstrap?

Bootstrap was created to address fragmentation across scripts, and to bring together all of FreePBX's resources to one central location. Previously, developers that needed any resources had to manually create a 'bootstrap' as well as maintain it for each version of FreePBX. For example, if a developer needed access to the amportal.conf setting, they needed to:

  1. Locate the amportal.conf file on the system
  2. Parse the file (In which they'd have to know the proper syntax needed)
  3. Where applicable, default missing amportal.conf settings if not setting AND know of any new settings that had been added/depreciated or removed during the last upgrade

The tedious work above wasn't the only problem. The KISS principle of programing is well known. Previously, there was duplicate code strewn across multiple scripts and 'entry points'. Having all of the resources available in one central location makes for code that is both cleaner and simpler to maintain.

How it works

Working with the new bootstrap in your script/project is extremely simple - just add an include to the bootstrap file, and you can access all of FreePBX's resources. Here is the code that needs to be added:

<?php
include '/etc/freepbx.conf';


/* your code here */

Please note: the second line of code is to work around an issue where we can't migrate properly, due to a lack of permissions found in most distro's. There is code in place to move freepbx.conf to /etc whenever certain commands are run as root (such as amportal). Hence, the /etc/asterisk/freepbx.conf should be considered deprecated and cannot be relied upon. Hence, the above should be used using /etc/asterisk/freepbx.conf only as a fallback.

What it provides (resources)

Bootstrap provides access to the following resources. These resources are crucial building blocks in FreePBX and will be critical to most third-party modules/addons:

  1. $amp_conf (array)- This is an array with all the (formerly) amportal.conf settings. (Note, these settings have been moved to the databases, and amportal.conf has been depreciated.). These settings also include some defaults that in the past were set by another function. This array is ready to use and requires no further modifications

    $amp_conf example
    <?php
    include '/etc/freepbx.conf';
    
    global $amp_conf;
    echo $amp_conf['AMPWEBROOT']; //Echoes the webroot
    //OR//
    echo FreePBX::Config()->get('AMPWEBROOT');
  2. $astman (object) - An instantiation of the PHP Asterisk Manager class. Use this to access anything directly in access, like to get information, run a command, or originate a call. If bootstrap cannot connect to asterisk, these variables will not be set. Please see the documentation here: Asterisk Manager Class

    $astman example
    <?php
    include '/etc/freepbx.conf';
    if($astman->connected()) {
    	$out = $astman->Command('sip show registry');
    	echo $out['data'];
    } else {
    	echo "no asterisk manager connection";
    }
  3. $db (object) - The humble database connect, used via the PearDB class. Please see the documentation here: PearDB

    $db example
    <?php
    include '/etc/freepbx.conf';
    global $db;
    $sql = "SELECT * FROM sip WHERE keyword = 'account'";
    $results = $db->getAll($sql, DB_FETCHMODE_ASSOC);
    /* $results is either an array or a PearDB Error Object
    +------+---------+------+-------+
    | id   | keyword | data | flags |
    +------+---------+------+-------+
    | 1000 | account | 1000 |    25 |
    | 1002 | account | 1002 |    25 |
    +------+---------+------+-------+
    2 rows in set (0.00 sec)
    */
  4. The Constant FREEPBX_IS_AUTH - This constant can be used to verify if a file has been accessed directly or via proper authentication. It saves the developer the need to have a .htaccess file to secure individual files. Use it as follows:

    FREEPBX_IS_AUTH Example
    <?php
    defined('FREEPBX_IS_AUTH') OR die('No direct script access allowed');}
    /*your code here */
    
  5. All functions from framework functions.inc.php.
  6. All module functions (from their respective function.inc.php).
  7. $asterisk_conf the asterisk settings from asterisk.conf 

Fine tuning access

In the name of efficiency, it is sometimes desirable to prevent the loading of some or all of the resources. This can be done by setting variables BEFORE bootstrap is called. Due to the unfortunate lack of real Object Orientated Programing in this framework, these resources will not be able to be called at a later time. Here is how the above resources are addressed:

  1. $amp_conf: See # 3
  2. $astman: set $skip_astman=true
  3. $db: set $skip_db=true This will prevent $amp_conf and $asterisk_conf from being set
  4. FREEPBX_IS_AUTH: You cannot prevent this from being set, but it is optional to use in your code. Nevertheless, you are encouraged to consider this check a good security practice.
  5. Framework functions: cannot be disabled
  6. Module functions: Set an array $restrict_mods with a list of modules that you want to be loaded, the rest will be skipped.

From the code comments, here are the options that can be 'passed' to bootstrap:

<?php
/* Bootstrap Settings:
 *
 * bootstrap_settings['skip_astman']           - legacy $skip_astman, default false
 *
 * bootstrap_settings['astman_config']         - default null, config arguemnt when creating new Astman
 * bootstrap_settings['astman_options']        - default array(), config options creating new Astman
 *                                               e.g. array('cachemode' => true), see astman documentation
 * bootstrap_settings['astman_events']         - default 'off' used when connecting, Astman defaults to 'on'
 *
 * bootstrap_settings['freepbx_error_handler'] - false don't set it, true use default, named use what is passed
 *
 * bootstrap_settings['freepbx_auth']          - true (default) - authorize, false - bypass authentication
 *
 * $restrict_mods: false means include all modules functions.inc.php, true skip all modules
 *                 array of hashes means each module where there is a hash
 *                 e.g. $restrict_mods = array('core' => true, 'dashboard' => true)
 *
 * Settings that are set by bootstrap to indicate the results of what was setup and not:
 *
 * $bootstrap_settings['framework_functions_included'] = true/false;
 * $bootstrap_settings['amportal_conf_initialized'] = true/false;
 * $bootstrap_settings['astman_connected'] = false/false;
 * $bootstrap_settings['function_modules_included'] = true/false true if one or more were included, false if all were skipped;
 * $bootstrap_settings['returnimmediately'] = true; //return right after freepbx.conf is loaded. Essentially only get database connection variables
 * $bootstrap_settings['report_error_link'] = true; //show the report to FreePBX link in page errors
 */ 

An Example

Adding an "Extension" (Adding a User and then Adding a Device)

<?php
$bootstrap_settings = array();
$bootstrap_settings['freepbx_auth'] = false;
include '/etc/freepbx.conf';

/*
USER VARS:
Array
(
    [extension] => 0224
    [password] => 
    [name] => Display Name
    [voicemail] => default
    [ringtimer] => 0
    [noanswer] => 
    [recording] => 
    [outboundcid] => 
    [sipname] => 
    [noanswer_cid] => 
    [busy_cid] => 
    [chanunavail_cid] => 
    [noanswer_dest] => 
    [busy_dest] => 
    [chanunavail_dest] => 
    [mohclass] => default
    [callwaiting] => enabled
    [cid_masquerade] => 0224
    [call_screen] => 0
    [pinless] => disabled
    [cfringtimer] => 0
    [concurrency_limit] => 0
    [dialopts] => 
    [recording_in_external] => dontcare
    [recording_out_external] => dontcare
    [recording_in_internal] => dontcare
    [recording_out_internal] => dontcare
    [recording_ondemand] => disabled
    [recording_priority] => 10
)
*/
$vars = array(
"extension" => 255,
"name" => "Bobby",
"password" => base64_encode(openssl_random_pseudo_bytes(30))
);
core_users_add($vars);
//core_devices_add($id,$tech,$dial,$devicetype,$user,$description,$emergency_cid=null,$editmode=false)

core_devices_add(255,'sip','','fixed',255,'Bobby'); 

 

FAQ/Resolved issues

These were moved from the discussion below.

  1. Assuming that amportal.conf goes away, how do scripts find bootstrap.php?
    • amportal.conf is staying where it is. Consider it depreciated, as we will not continue to support it for much longer. In the meantime, it is suggested that you don't make any changes to the file. Instead, after running the amportal command (i.e. amportal restart), you can make all changes via the Advanced Setting Page in the FreePBX GUI. Amportal.conf will also be updated with the settings (READ ONLY).
  2. Just like with config.php, there needs to be a way to include/exclude resources from loading (to prevent system load when scripts are loading often, i.e. an IVR).
    • See above for how to go about
  3. Due to the generally pinpointed nature of agi's/scripts we may want to default all script include to NOT include modules (and their functions) unless specifically requested and the inverse for config.php. However, this counter-intuitive.
    • For now, we will include all resources whenever bootstrap is called. The advanced developer can modify this behavior.
  • No labels