iono Documentation - Event Hooks
iono allows you to hook into the system without making massive code modifications, which wouldn't even be possible for some licenses. A number of hooks are available, covering many of the main features in iono, including user signups, payment reception and license installation.
Usage
The first step towards being able to use the available hooks is to load your module into iono. This involves adding a line to the events/events_loader.php file:
include_once('your_module_name/init.php');
You will need to change the path to point to whichever file you use for initialising the module. This file will need to be created by you and is used to initialise the event handling module you are writing. The conventions we use are to create a new directory based on the module name. The init.php file then creates the object for the event handler. In the Snarl example module we provide this is:
require('snarl.php');
$snarl = new iono_module_snarl($iono_events);
The event handling class (explained below) is called iono_module_snarl and is stored in the snarl.php file. The convention here is to use the module name as the unique indentifier for the class and the file.
Registering
The event system works with classes and their methods so your module will need to be a class to be able to register with the events system. Therefore, the second stage is to register the hooks your module will be responding to. To do so you need to make the following call:
$iono_events->register('hook', $this, 'method_name');
This would mean that when the hook called hook is triggered, the method called method_name in the current class ($this) would be the event handling method. That method would be called and the code contained in it executed.
A real example of registering for an event is:
$iono_events->register('user/activate', $this, 'users_activate');
Here the user/activate hook is the hook being triggered with the event handling method being $this->users_activate()
Methods
The final stage is to actually create the event handler methods. As events are triggered, the functions which have been registered are called by the events system. They are passed one argument which is an array of data for the function to use. The contents of this array will vary with the event being triggered. See below for a full list.
Example
The example module which is included in the iono distribution is for a program called Snarl. This is a Windows alternative to Growl for Mac OS X. It allows for messages to be displayed on screen by other programs.
Snarl doesn't have a proper network layer, so instead we wrote a PHP script to sit on a webserver on the machine receiving the notifications which makes system calls to the snarlmsg.exe executable. The title and message for the notification are set via GET method variables. This proxy script is bundled in the events/snarl/ directory.
Initialisation
The include call has been placed into events/events_loader.php and it loads events/snarl/init.php. This initialisation file then includes the snarl class and instantiates the module, passing $iono_events to the constructor method.
Registering
Hook registration is handled in the constructor. The Snarl module registers for 5 events.
Methods
Each event hook method sets $title and $message based on the data in the $data array passed to the function. From here it then calls the send_message() method which then dispatches the method to the Snarl proxy.
Events
user/add
Triggered when a user is created.
Array ( [user_id] => int [status] => int [admin] => int [username] => string [password] => string (raw password) [email] => string [first_name] => string [last_name] => string [company] => string [address1] => string [address2] => string [city] => string [county] => string [postalcode] => string [country] => string [phone] => string [orders_validation] => int [notes] => string [send_email] => int [validate] => int )
user/activate
Triggered when a user is activated
Array
(
[user_id] => int
[status] => int
[username]=> string
[email] => string
)
user/edit
Triggered when a user is edited. Note: The data within the array will contain the new values. Unchanged fields will be empty except for username which will always be set with the latest value from the database.
Array
(
[user_id] => int
[status] => int
[admin] => int
[username] => string
[password] => string (raw password)
[email] => string
[first_name] => string
[last_name] => string
[company] => string
[address1] => string
[address2] => string
[city] => string
[county] => string
[postalcode] => string
[country] => string
[phone] => string
[ip] => string
[orders_validation] => int
[notes] => string
)
user/delete
Triggered when a user is deleted
Array
(
[user_id] => int
[username] => string
)
error/text
Triggered when an error occurs on the site. Error message passed as a string not an array.
download/log
Triggered when a download takes place
Array
(
[download_id] => int
[user_id] => int
)
extra/add
Triggered when a product extra is created for a user
Array
(
[extra_id] => int
[product_id] => int
[product_extra_id] => int
[invoice_id] => int
[user_id] => int
[status] => int
[expires] => int
[accessed] => int
[notes] => string
)
invoice/approved
Triggered when an invoice is approved
Array
(
[invoice_id] => int
[user_id] => int
)
invoice/new
Triggered when an invoice is created
Array
(
[invoice_id] => int
[time_due] => int
[status] => int
[user_id] => int
[initial_tax_rate] => float
[items] => array
[initial_discount] => float
[initial_sub_total] => float
[initial_tax] => float
[initial_total] => float
[recurring_tax_rate] => float
[recurring_discount] => float
[recurring_sub_total] => float
[recurring_tax] => float
[recurring_total] => float
[recurring_period] => float
[generate] => int
[generate_day] => int
[subscription_active] => int
[notes] => string
)
invoice/need_approval
Triggered when an invoice is created and needs approval
Array
(
[invoice_id] => int
[user_id] => int
[approve] => int
)
payment/transaction_log
Triggered when a transaction is logged
Array
(
[invoice_id] => int
[result] => string
[currency] => string
[amount] => float
[fees] => float
[ref] => string
[notes] => string
)
licence/add
Triggered when a license is created
Array
(
[license_id] => int
[product_id] => int
[product_license_id] => int
[invoice_id] => int
[user_id] => int
[status] => int
[license_key] => string (only set if a custom license string is provided)
[hostname] => string
[ip] => string
[installs] => int
[allowed_installs] => int
[expires] => int
[accessed] => int
[notes] => string
)
license/bind
Triggered when a license is bound to a hostname/IP address
Array
(
[license_id] => int
[installs] => int
[allowed_installs] => int
[ip] => string (the bound license IP)
[name] => string (the bound license hostname)
[host_ip] => string (the accessed from license IP)
[host_name] => string (the accessed from license hostname)
)
license/install_bind
Triggered when a license is bound to a hostname/IP address upon installation
Array
(
[license_id] => int
[installs] => int
[allowed_installs] => int
[host_ip] => string (the accessed from license IP)
[host_name] => string (the accessed from license hostname)
)
license/install_limit_reached
Triggered when a license has reached its install limit
Array
(
[license_id] => int
[installs] => int
[allowed_installs] => int
[host_ip] => string (the accessed from license IP)
[host_name] => string (the accessed from license hostname)
)