AWStats logfile analyzer 7.0 Documentation

  


Plugin Development

AWStats has a very flexible plugin architecture that is easy to use and allows for powerful extensibility. Here is the information you need to get started rolling your own. In this documentation, the terms plugin and module will be used interchangeably.


Plugin Files, Location
AWStats plugins are implemented as Perl modules with a file extension of .pm. Every time you run AWStats, either in update mode or HTML output mode, the configuration file will be parsed for the names of plugins to load. Then AWStats will scan the plugins folder for matching modules and load them into memory, executing hooks at the appropriate time during a run. Thus, when you create a plugin, you have to store the file in the plugins directory under the folder where awstats.pl resides.

Hooks
In order to be useful, your plugin must implement any number of different "hooks" that will be called at various points during the AWStats run. A hook is simply a Perl sub routine that will receive various parameters, perform whatever actions you desire such as calculations, modifications or output, and optionally return a value.
Note: all plugins MUST implement the Init_ hook to initialize the module and determine if the plugin will run under the current version of AWStats.
For information on the available hooks, view the Hooks document.

Required Variables
Each plugin must implement three required, local variables including the name, hooks, implements and required AWStats Version. Typically you implement these at the top of your plugin file as in this example code:

#-----------------------------------------------------------------------------
# PLUGIN VARIABLES
#-----------------------------------------------------------------------------
# <-----
# ENTER HERE THE MINIMUM AWSTATS VERSION REQUIRED BY YOUR PLUGIN
# AND THE NAME OF ALL FUNCTIONS THE PLUGIN MANAGE.
my $PluginNeedAWStatsVersion="5.5";
my $PluginHooksFunctions="GetCountryCodeByAddr GetCountryCodeByName ShowInfoHost";
my $PluginName = "geoipfree";
my $PluginImplements = "mou";
# ----->

The $PluginNeedAWStatsVersion indicates the minimum version of AWStats that your plugin requires to run properly. If a user attempts to implement your plugin with an older version of the program, the plugin will not load.

$PluginHooksFunctions is a space delimited list of the different hooks that your plugin will implement. This list should only include names defined in the hooks list. You should not list any private module functions or the Init_ hook in this list. The naming convention for all hooks is HookName_PluginName. The hooks like only includes the hook name without the underscore.

$PluginName is simply the name of your plugin, exactly as it appears in the hooks and file name. This will be used by AWStats on load.

$PluginImplements is a list of letter codes mapped to operations that your plugin performs. Without at least one of these letter codes, your plugin will never run. The codes are:
Accessible Variables
Your plugin has access to all of the global variables declared at the top of the AWStats.pl program. While you can write to these variables, it's best to only read them as another plugin may make unexpected modifications. However you can declare global variables within your own plugin and share those across other plugins. Just declare them inside the normal use vars qw/ ... / block within your own module.

Thus you can (and should) use settings from the configuration file and determine the debug level.

Accessible Functions
Plugins have access to all of the functions declared in the main AWStats.pl file. For debugging and error handling, you should use the debug and error functions. Below are some common functions that plugins take advantage of (remember you don't have to re-invent the wheel):

debug("debug message", debug_level) - Writes the "debug message" to the standard output if the (integer) debug_level is lower or equal to that set by the user at runtime. The higher the debug level, the less important or more informational the message. After outputting the message, the program continues running.

error("error message") - Writes the "error message" to the standard output and halts program execution.

Format_Bytes(bytes) - Converts the incoming decimal value to Kilobytes, Megabytes, Gigabytes and so forth. So if you put in 1024.5 it will spit out "1 KB"

Format_Date(YYYYMMDDHHMMSS) - Converts the incoming timestamps to something like 30 Apr 2010 - 16:55

Format_Number(number) - Adds commas or a user defined character where appropriate to separate numbers for easier reading.