<?php
/*
$Id: plugin_interfaces.inc.php 112 2007-11-21 14:27:19Z randomperson83 $
Obsessive Web Statistics
Copyright (C) 2007 Dustin Spicuzza <hide@address.com>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
This contains the interfaces that can be implemented by any plugins. All plugins
MUST implement iPlugin
*/
// list of all the interfaces this file defines (except and iPlugin)
global $ows_plugins;
$ows_plugins['plugin_interfaces'] = array(
'filter' => 'iFilterPlugin',
'analysis' => 'iAnalysisPlugin',
'installable' => 'iInstallablePlugin',
'reject' => 'iRejectPlugin',
'limit' => 'iLimitPlugin'
);
/*
All plugins must implement this interface
*/
interface iPlugin{
// this should return a unique ID identifying the plugin, should start with an alpha,
// should use basename instead of just __FILE__ otherwise it could expose path information
public function getPluginId();//{
// return 'p'. md5(basename(__FILE__) . get_class());
//}
// returns an associative array describing the plugin
public function getPluginInformation();
/*
return array(
'pluginName' => 'Name of plugin',
'aboutUrl' => 'http://information.about.plugin'
'author' => 'author',
'url' => 'http://developers.website'
'description' => 'Description of what plugin does',
);
}
*/
}
/*
iFilterPlugin
These plugins are shown to users, and then run at the users request.
*/
interface iFilterPlugin{
// returns name of filter to show to user
public function getDisplayName();
// this function outputs html which is displayed inside of a form
// submit button is already defined for you. Call show_common_limits
// to use the standard limit section (by date, by time, exclude bots, etc)
public function showOptions();
// this function shows the filtered results
public function showResults($domain);
}
/*
iLimitPlugin
These plugins implement common limits for all any filter plugins that
use the SQLSelect class to do SQL queries. It allows the limit plugins to do
anything it wants to with the SQL queries.
*/
interface iLimitPlugin{
// this function outputs html which is displayed inside of a table with two columns, inside of a
// form. The plugin output should begin with <tr> and end with a </tr>. The form variables
// that you use should always begin with a unique identifier. For example,
// echo "Form variable: <input name=\"" . md5(__FILE__) . "_form_variable_name\" value=\"\"/>";
public function showLimits();
// this function modifies the filter's SQL query. This function should look for
// form variables set by showOptions
public function limitResults($domain,&$query);
}
/*
iAnalysisPlugin
These plugins are ALWAYS run when a database upload is performed. They are
also used to define dimensions and their usage. Refer to dimensions.txt for
more information on dimension structure.
Analysis is run in a number of rounds (process stages), at the end of which
the current data is committed to the database.
If any of them return false, then the current transaction is scrapped.
*/
interface iAnalysisPlugin{
// this function should return a set of arrays that define the dimensions
// and attributes that this plugin defines. You should not specify an attribute
// that another plugin defines. This is not website dependent.
public function define_dimensions();
/*
return array(
'dimension1' => array(
'pnode_is' => string of the logfile field (returned by the apache log parser) that the
primary node of the dimension is directly, without modification. Set this to
null if you do not directly store a logfile field without modification.
'attribute1' => attribute_defn(...),
'attribute2' => ...
),
'dimension2' => array(
...
)
);
*/
/*
Treat this like a constructor. This is called before all phases of
analysis, and is only called once per website. It should be used to
clean up website-specific variables. Like SQL id's.
*/
public function InitializeAnalysis($website);
/*
This function is called before the phase of analysis starts. It gets called
many times, once per phase.
$ids An array of all the current ID's for every dimension. If you
insert new rows into the dimension table, you MUST use and increment
the ID in the appropriate dimension.
*/
public function preAnalysis($website,&$ids);
/*
This function is called for each line grabbed from the logfile.
$website The current website being worked on
$dimension This parameter defines which dimension is being analyzed
at the moment. The function may be called multiple times
for a row with different dimensions as arguments.
$line This contains an array of data that was retrieved
from the logfile.
This function should return an item that is the 'primary node' of the
dimension (defined as an attribute with the same name as the dimension).
You should return false if you do not define a primary node for that dimension,
or if there is an error.
*/
public function getPrimaryNode($website, $dimension, $line);
/*
This function is called for each line grabbed from the logfile.
$website The current website being worked on
$dimension This parameter defines which dimension is being analyzed
at the moment. The function may be called multiple times
for a row with different dimensions as arguments.
$pnode This contains the primary node of the dimension.
The plugin should only return attributes that are defined in the
define_dimensions function. This function should return an array
in the form of
array('attribute' => 'value', ...)
which defines values to be uploaded to the SQL database. It should NOT return
the primary node. Please note that the returned values can be cached, so this
function may NOT always be called for each row.
You should ALWAYS return an array with the same keys each time, in the same order
that the keys were defined in define_dimensions. Otherwise, things will break.
If you do not define any attributes in the current dimension, or if there is
an error, then return false.
*/
public function getAttributes($website, $dimension, $pnode);
/*
This function is called after the round of analysis is complete. Called many times.
$ids An array of all the current ID's for every dimension. If you
insert new rows into the dimension table, you MUST use and increment
the ID in the appropriate dimension. $ids[$dimensionname] is how it would
be referenced.
*/
public function postAnalysis($website,&$ids);
}
/*
iInstallablePlugin
This is for plugins that require extra information such as tables, field
alterations, and such to be created for their proper operation. Note that
while this is useful for analysis plugins, they do NOT have to implement this
in order to add new dimensions or modify existing ones.
*/
interface iInstallablePlugin{
// This should create tables and/or alter rows. Useful especially for analysis plugins.
// Return true if success, false otherwise. It should handle its own transactions.
// Should NOT create dimensions. Dimensions are created after this function is called.
// Suggestion: use set_config_var(get_class() . '_installed') for this
//
// @param $website Any tables created should be in the form of $website . _keyname
function install($website);
// returns true or false. suggestion: use get_config_var(get_class() . '_installed') for this
function isInstalled($website);
// this should remove any information from the database. Return true if success, false otherwise.
function uninstall($website);
}
/*
iRejectPlugin
This aids analysis, in that it is used to make the size of the database smaller
depending on characteristics of the log line. This is useful if you want to write plugins to
exclude things such as spam, bots, whatever. Its also useful if you get tons of hits each day
and only want OWS to keep the history for the last 15 days, or something to that effect.
Rejection plugins should probably just DELETE records from the main fact table. After an analysis,
if the user sets $cfg['cleanup_stale'], then the analysis engine will try to automatically resolve
all dimension records to see if there is matching data in the main fact table, and delete the
dimensional data if it isn't referenced by anything else. It is set to false by default.
*/
interface iRejectPlugin{
/*
Treat this like a constructor. This is called before all phases of
analysis, and is only called once per website. It should be used to
clean up website-specific variables. Like SQL id's.
*/
public function InitializeRejection($website);
/*
This function returns true or false. If it returns true, analysis is not performed on
the line. If false, the analysis engine performs analysis on the line.
*/
function RejectLine($website, $line);
}
?>