What is bootstrap.php?

Bootstrap.php is the new starting point for all things FreePBX. Think of to FreePBX as the bios is to your computer - its what jumpstarts everything else in the system. It includes all resources available to FreePBX including:

• all functions, as well as all active modules functions (configurable at runtime)
• db connections
• asterisk manager connection
• $amp_conf setting array
• debugging functions
• etc.

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.php?

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

1. locate the file on the system
2. parse the file (he need to know the file's syntax for this)
3. where applicable, default the amportal settings in case there not set

The tedious work wasn't the only problem. The KISS principle of programing is well know. Previously, there was duplicate code strewn across multiple scripts and 'entry points'. Having all 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.php 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
if (!@include_once(getenv('FREEPBX_CONF') ? getenv('FREEPBX_CONF') : '/etc/freepbx.conf')) { 
	  include_once('/etc/asterisk/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 permission 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 depreciated 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 - 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
2. $astman - 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, this variables will not be set.
3. $db - The humble database connect, used via the pear::db dal class. Please see the pear::db documentation for how to use this class.
4. 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 an .htaccess file to secure individual files. Use it as follows:

   <?php
   defined('FREEPBX_IS_AUTH') OR die('No direct script access allowed');}
   /*your code here */
   ?>
   

5. All functions from framework ({{functions.inc.php}}}). While the merits here are debatable, there is currently access to all framework functions.
6. All module functions (from their respective function.inc.php). Note page functions are called ONLY when the page is viewed and aren't available globally
7. $asterisk_conf the asterisk setting 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 a variables BEFORE bootstrap is called. Due to the unfortunate lack of really OO 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 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;
*/

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 mean time, it is suggested that you don't make any changes to the file. Instead, after running amportal command (i.e. amportal restart), you can make all changes via the advanced page in General Setting. Amportal.conf will be updated with the settings.
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. How do we handle legacy scripts (i.e. bash) and is there a way to prevent third-party script from breaking (especially considering that we want to retire amportal.conf)
   • One possibility is to have the bootstrap, when run from the cli (as ./bootstrap.php return a list of variable just as running a . some_bash_script.sh would do. Not sure if this would work though -MB

• This has been resolved, pending more testing

4. 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 when ever bootstrap is calls. The advanced developer can modify this behavior

Discussion

Status

Dec. 12 2010 - The work has been completed and, pending alpha testing, is waiting to be merged in to trunk. Oct. 13 2010 - Most of the code is written and waiting to be checked in. A lot of groundwork as been preceded via #4527

CLI Examples

Below you will find a file that can be run from CLI that bulk import extensions.
Usage: cli.bulkextensions.php input filename.csv Syntax of filename.csv is the same as for the Bulkextensions module.