User Manager Hooking and Functions

The User Manager module houses all Users that are not part of device/user mode but are still linked to extensions. These users are used around FreePBX to get or set data. They are used in iSymphony, User Control Panel, XMPP and RestAPI but any module can be extended to utilized Users without revealing any compromising information.

1 First Steps
2 GUI Hooks
3 Hooking Functions
- 3.1 Add Hook
- 3.2 Update Hook
- 3.3 Delete Hook
4 User Manager Global Functions

First Steps

Inside any module simply these lines of code to be able to utilize User Manager Functions:

if(function_exists('setup_userman')){
    $userman = setup_userman();
}

The setup_userman() function returns a static object, so it can be called more than once without having to worry about class reconstruction. You can also use the above code to detect if User Manager support is available in your instance.

GUI Hooks

This function will allow you to put html code into the user manager page. When the page has submitted this function will also be executed so as to pass any submitted data to it.

function <modulerawname>_hook_userman() {
    return 'foo'
}

Hooking Functions

Hooking functions are calls that User Manager makes when users are added or removed from either the User Manager configuration page or from the Extensions page, they are also called when user settings are changed/updated from within User Manager.

These must be placed inside of functions.inc.php to do anything useful

Add Hook

This hook is called when a user is added, either through the Device/Users, Extensions or User Manager Page

setup_userman()->registerHook('addUser','myFunctionName');
/**
 * @param int $id The User Manager ID
 * @param string $display The page in FreePBX that initiated this function
 * @param array $data an array of all relevant data returned from User Manager
 * @return bool
 */
myFunctionName($id,$display,$data) {}

Update Hook

This hook is called when a user is updated. Usually through the User manager page, however it can happen where a default extension is redefined through the Device/Users or Extensions page

setup_userman()->registerHook('updateUser','myFunctionName');
/**
 * @param int $id The User Manager ID
 * @param string $display The page in FreePBX that initiated this function
 * @param array $data an array of all relevant data returned from User Manager
 * @return bool
 */
myFunctionName($id,$display,$data) {}

Delete Hook

This hook is called when a user is deleted. The most useful data returned from here is $id, since User Manager deletes the user and relevant attached data prior to this you don't have to do anything if you stored all of your module's data inside of User Manager

setup_userman()->registerHook('delUser','myFunctionName');
/**
 * @param int $id The User Manager ID
 * @param string $display The page in FreePBX that initiated this function
 * @param array $data an array of all relevant data returned from User Manager
 * @return bool
 */
myFunctionName($id,$display,$data) {}

User Manager Global Functions

Get All Users

This function will get all users and their information (top level data only). It will return false if no users can be found

/**
 * Get User Information by the Default Extension
 *
 * This gets user information from the user which has said extension defined as it's default
 *
 * @return array A hash of users data
 */
setup_userman()->getAllUsers();

Get User By Default Extension

This function will get user information (top level data only) by which user has said extension or user (device/user mode) assigned as it's default. It will return false if no user can be found

/**
 * Get User Information by the Default Extension
 *
 * This gets user information from the user which has said extension defined as it's default
 *
 * @param string $extension The User (from Device/User Mode) or Extension to which this User is attached
 * @return array A hash of user data
 */
setup_userman()->getUserByDefaultExtension($extension);

Get User By Username

This function will get user information by username. It will return false if no user can be found

/**
 * Get User Information by Username
 *
 * This gets user information by username
 *
 * @param string $username The User Manager Username
 * @return array
 */
setup_userman()->getUserByUsername($username);

Get User By User ID

This function will get user information by the User Manager User ID. It will return false if no user can be found

/**
 * Get User Information by User ID
 *
 * This gets user information by User Manager User ID
 *
 * @param string $id The ID of the user from User Manager
 * @return array
 */
setup_userman()->getUserByID($id);

Get Assigned Devices By User ID

Get all the devices (Extensions or (device/user mode) Users) that are attached to this User Manager User

/**
 * Get the assigned User Manager Devices for this User
 *
 * Get the assigned User Manager Devices for this User as a Hashed Array
 *
 * @param int $id The ID of the user from User Manager
 * @return array
 */
setup_userman()->getAssignedDevices($id);

Set Assigned Devices By User ID

Set all the devices (Extensions or (device/user mode) Users) that are attached to this User Manager User

/**
 * Set the assigned devices (Extensions or (device/user mode) Users) for this User
 *
 * Set the assigned devices (Extensions or (device/user mode) Users) for this User as a Hashed Array
 *
 * @param int $id The ID of the user from User Manager
 * @param array $devices The devices to add to this user as an array
 * @return array
 */
setup_userman()->setAssignedDevices($id,$devices=array());

Get All Global Settings By User ID

Gets all global settings by User

/**
 * Get Globally Defined Sub Settings
 *
 * Gets all Globally Defined Sub Settings
 *
 * @param int $id The ID of the user from User Manager
 * @return mixed false if nothing, else array
 */
setup_userman()->getAllGlobalSettingsByID($id);

Get A Single Global Setting By User ID

Get a single global setting by User

/**
 * Get Globally Defined Sub Settings
 *
 * Get a Globally Defined Sub Setting
 *
 * @param int $id The ID of the user from User Manager
 * @param string $setting The setting keyword
 * @return mixed false if nothing, else array
 */
setup_userman()->getGlobalSettingByID($uid,$setting);

Set A Single Global Setting By User ID

Set a single global setting by User

/**
 * Set Globally Defined Sub Setting
 *
 * Sets a Globally Defined Sub Setting
 *
 * @param int $id The ID of the user from User Manager
 * @param string $setting The setting keyword
 * @param mixed $value Can be an array, boolean or string or integer
 * @return mixed false if nothing, else array
 */
setup_userman()->setGlobalSettingByID($uid,$setting,$value);

Get All Defined Sub Settings by Module Name and User ID

Get All Defined Sub Settings by Module Name

/**
 * Get All Defined Sub Settings by Module Name
 *
 * Get All Defined Sub Settings by Module Name
 *
 * @param int $uid The ID of the user from User Manager
 * @param string $module The module rawname (this can be anything really, another reference ID)
 * @return mixed false if nothing, else array
 */
setup_userman()->getAllModuleSettingsByID($uid,$module);

Get a single setting from a User by Module and User ID

Gets a single Module Defined Sub Setting

/**
 * Get a single setting from a User by Module
 *
 * Gets a single Module Defined Sub Setting
 *
 * @param int $uid The ID of the user from User Manager
 * @param string $module The module rawname (this can be anything really, another reference ID)
 * @param string $setting The keyword that references said setting
 * @return mixed false if nothing, else array
 */
setup_userman()->getModuleSettingByID($uid,$module,$setting);

Set a Module Sub Setting by Module and User ID

Sets a Module Defined Sub Setting

/**
 * Set a Module Sub Setting
 *
 * Sets a Module Defined Sub Setting
 *
 * @param int $uid The ID of the user from User Manager
 * @param string $module The module rawname (this can be anything really, another reference ID)
 * @param string $setting The keyword that references said setting
 * @param mixed $value Can be an array, boolean or string or integer
 * @return mixed false if nothing, else array
 */
setup_userman()->setModuleSettingByID($uid,$module,$setting,$value);

FreePBX Open Source