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

General Module Hooks

Any code calls in FreePBX can be hooked by other calls. Let's say you have a module called "Pony" but you want to expose a method that other modules could call

Setup the Hook Call

In the PHP function we need to add a function call to the method(s) we want to expose. In the below function we are getting a list of Pony colors but because we are calling processHooks we are letting any other module in FreePBX return data here as well

public function ponyColors($adaptor) {
    \FreePBX::Hooks()->processHooks(); 
}

We can pass processHooks any data we want such as booleans, objects, arrays:

public function ponyColors($adaptor) {
    $data = array("this is my data array");
    \FreePBX::Hooks()->processHooks($data);
}

Process Hooks will then call all modules which have requested to hook into this method (see below). It will return an array like so:

public function ponyColors($adaptor) {
    $data = array("this is my data array");
    $out = \FreePBX::Hooks()->processHooks($data); 
    /**
     * $out will look like:
     * array(
     *     "FreePBX\Modules\Sipstation" => array("stuff"), //see below as to why this is output
     *     "calledModuleClassName1" => data,
     *     "calledModuleClassName2" => data

Setup the Hook Processor

To be able to hook into the Pony module from other modules you need to tell FreePBX about yourself and what you are trying to request. Here is an example from the AmericanQuarterPony module

First start off by modifying module.xml

  <hooks>
    <pony namespace="FreePBX\modules" class="Pony"> <!-- calling class -->
      <method namespace="FreePBX\Modules" class="AmericanQuarterPony" callingMethod="ponyColors">myPonyColors</method> <!-- method to execute -->
    </pony>
  </hooks>

Let's break this apart, every hook will have a declaration, you define that with this line:

<pony namespace="FreePBX\modules" class="Pony">

If the module you are trying to hook into doesn't have a namespace you can omit that, however you can NOT omit class (which is case sensitive)

<pony class="Pony">

To add a priority to your call just add a "priority" attribute. If no priority attribute is added the priority will be set at 500

<pony namespace="FreePBX\modules" class="Pony" priority="100">

Next we declare who we are and the method we want to hook into ("callingMethod").

  • namespace: The namespace of this module
  • class: The class file inside of this module
    • After FreePBX 15+ you have two choices here either the module name (Americanquarterpony which means Americanquarterpony.class.php) or any file that can be autoloaded from within that module's directory. (Colors which means Colors.php)
  • callingMethod: The method we want to hook into from the Pony class
  • static: should this method be called statically
<method namespace="FreePBX\Modules" class="AmericanQuarterPony" callingMethod="ponyColors" static="false">

or

<method namespace="FreePBX\Modules\AmericanQuarterPony" class="Colors" callingMethod="ponyColors" static="false">

Finally we add our method name (which is the method that will be called from within Pony), which we have named "myPonyColors":

<method namespace="FreePBX\Modules" class="AmericanQuarterPony" callingMethod="ponyColors">myPonyColors</method>

In Americanquarterpony we have now added our method to either Americanquarterpony.class.php or Colors.php:

public function ponyColors($data) {
    //From above, $data would be: array("this is my data array")
    return array("stuff");

After all of this is through you'll then need to run retrieve_conf so the caching engine will pickup on your changes.

  • No labels