Published on
29. January 2010 by
Michael Friedrich in
API, Core, Development, Documentation, Technical and Webinterface.
Tags: API, Database, Development, Docbook, Documentation, Fork, git, Icinga, IDOUtils, oracle, PostgreSQL, release, team, tracker, web.
Closing into the 14 day rush to the next Icinga release 0.8.2, we had a moment to reflect on our coding madness. As a developer, the one thing that makes such work easier is the choice of a good framework. And that is why we take our hats off to our trusty Agavi framework.
Why Agavi? It was no hard choice. As an open source, PHP 5, object oriented framework, it met all our web interface needs.
Thanks to its very strict Model-view-controller architectural pattern, we have very clean, testable and easily extensible code. By separating user input from application actions and from the interface view, there is much less complexity in the design architecture which leads to greater flexibility and easier extension. Less complexity and not to mention PHP open Icinga to a much larger developer community.
Extensibility is also built in through its modular structure which is perfect for all the Icinga addons that will no doubt come in time. Addons can be easily integrated into the frontend, added on as modules.

Icinga Web Architecture – a home for an Addon
Unlike other frameworks which restrict which components can be used, Agavi is highly flexible and leaves most implementation choices the developer. So at the end of the day we have complete control over the code. It’s independence from database abstractions and multi-language support further enhances to Icinga’s flexibility, making it accessible to diverse users.
As Agavi is an active project, we trust it can only get better. Most recently, Agavi’s improvements to its build system and its integration of the Phing (Phing is not GNU make) makes coding that bit faster. And if you notice that ever ticking counter on the right, you would understand why.
Since Icinga-API is finally capable of supporting developers with
data we are going to blog a little to make coders out there feel
comfortable with this wonderful piece of work. 
Here you can see the current progress of the API and related interfaces:
- API overall: 50%
- IDO interface: 50%
- file interface: 25%
If you want to fetch data from the IDO you have to take care about the
following requirements:
- PHP5
- web-server module for PHP PDOs
Enough talking… let’s see some code!
1.) configuration
Configuration is simply done by using an associative array.
$idoConfig = array (
‘type’ => ‘<Type of database>’,
‘host’ => ‘<Database hostname>’,
‘database’ => ‘<Databasename>’,
‘user’ => ‘<Username>’,
‘password’ => ‘<password>’,
‘persistent’ => <true | false>,
‘table_prefix’ => ‘<table prefix>’,
);
Example:
$idoConfig = array (
‘type’ => ‘mysql’,
‘host’ => ‘localhost’,
‘database’ => ‘ido’,
‘user’ => ‘idouser’,
‘password’ => ‘idopassword’,
‘persistent’ => true,
‘table_prefix’ => ‘icinga_’,
);
2.) fetching data: hostnames and corresponding states
Create an instance of class IcingaApi:
$api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig);
Create your search:
$apiRes = $api->createSearch()
->setSearchTarget(IcingaApi::TARGET_HOST)
->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’))
->fetch();
By using setSearchFilter() you can define filters to narrow down the result set:
$apiRes = $api->createSearch()
->setSearchTarget(IcingaApi::TARGET_HOST)
->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’))
->setSearchFilter(HOST_NAME, ‘Switch%’, IcingaApi::MATCH_LIKE)
->fetch();
3.) processing result
foreach($apiRes as $apiHandle){
echo ‘Host ‘.$apiHandle->host_name.’ has state ‘.$apiHandle->host_current_state.’<br />’;
}
Output without filter:
Host localhost has state 0
Host MySql has state 0
Host router-01 has state 0
Host windows100 has state 0
Host Apache_01 has state 0
Output with filters:
Host switch70 has the current state 0
Host switch71 has the current state 0
Host switch72 has the current state 0
Host switch73 has the current state 0
Host switch74 has the current state 0
Host switch75 has the current state 0
Host switch76 has the current state 0
Host switch77 has the current state 0
4.) complete code without use of filters:
<?
// Path to icinga api file
$apiFile = ‘icinga-api/IcingaApi.php’;
// Database connection
$idoConfig = array (
‘type’ => ‘mysql’,
‘host’ => ‘localhost’,
‘database’ => ‘ido’,
‘user’ => ‘idouser’,
‘password’ => ‘idopass’,
‘persistent’ => true,
‘table_prefix’ => ‘icinga_’,
);
// Include required files
require_once($apiFile);
// Instance the class
$api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig);
// Create search
$apiRes = $api->createSearch()
->setSearchTarget(IcingaApi::TARGET_HOST)
->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’))
->fetch();
// Create output
foreach($apiRes as $apiHandle){
echo ‘Host ‘.$apiHandle->host_name.’ has the current state ‘.$apiHandle->host_current_state.’<br />’;
}
?>
That’s all folks but there’s more to follow!
Please have a look at the git repository for further information:
https://git.icinga.org/index?p=icinga-api.git;a=summary
Have fun!