Location: PHPKode > projects > Obsessive Website Statistics > ows/include/plugin_interfaces.inc.php
<?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);
	

}


?>
Return current item: Obsessive Website Statistics