The FMK Framework API

SnortSMS uses an Application Programming Framework. This document covers how to utilize the FMK framework so developer can modify and troubleshoot SnortSMS's application. The framework looks complicated, but it’s actually very very easy to learn, and once you do you will find it hard to program in any other way!

Framework Concept

Rapid Application Development: The main goals of the framework are to encourage code re-use, split the web application into logical sections which allow re-use in other projects, and to provide a means for quickly creating rich applications under a standard API. The framework also helps obfuscate web pages for better security and lays the grounds for logical application development in a team environment. Strict rules and guidelines insure every developer can quickly understand the whole project and coding conventions.

The framework operates by calling a single php script ( {webroot}/index.php ) and passing a “zone action” value. The framework will then locate and execute the proper sequence of php scripts needed to satisfy the requested action.

Core Framework Files [webroot]

Core files in the framework begin with the “FMK_*” file naming convention.

FMK_FrameworkDriver.php (required)
This file lives in the webroot directory. It is the main script which brings all the configuration files and other scripts together. It is the main framework file that shouldn’t need any modification.

FMK_lib/FMK_FrameworkDriver.class (required)
The Class object used by the framework. Shouldn’t need any modification.

FMK_lib/FMK_XMLParser.class (required)
Used by the Framework for parsing XML config files. Shouldn’t need any modification.

FMK_Application.xml.php (required)(modified by developer)
Config File. Defines the web application. Defines the “Zones” ( I’ll explain later ). Defines the php session vars and any default values.

FMK_Zones.xml.php (required)(modified by developer)
Defines all Zones and there relative directory paths.

FMK_Templates.php (required)(modified by developer)
Defines what default layout file to use (or multiple). You could define a separate look and feel for separate Zones of your application.

FMK_Layouts/Layout-Default.php (required)(modified by developer)
This is the web application’s template file for web page layout and CSS. Everything in this file can be static HTML except one single call to “<?=$obj_FMK->strokeBody()?>” which is responsible for inserting the dynamic content of your application.

FMK_Hooks.php (optional)(modified by developer)
Allows the developer to add in extra code, functions, or “includes”. This file can exist in the webroot and inside Zone sub-directories.

index.php (required)
This is the main php script that is *always* called. All it does is launches the Framework system. Zone sub-directories also have and index.php however it is only used to prevent directly accessing the sub-dir.

Zones

These are considered sections within an application. We try to group common tasks within an application. For example, in an “online store” application you might have a zone processing accounts, and another zone for tracking inventory, while yet another zone to handle billing. All php code that does these tasks are place in separate directories. Since zones are sub-applications within themselves, it’s easy to assign separate development teams their own zones to develop.

Core Framework Files [zone sub-directories]

{zone_dir}/FMK_Handler.php (required)(modified by developer)
This file “combines” other php scripts within the Zone’s sub-directory based on the Framework’s zone action variable. See below for description of “zone actions”. This is the heart of the framework as it is responsible for building the web pages that will execute. It is simply a big “switch” that “includes” php code pieces to create a linear php script. These scripts are executed behind an output buffer. The buffer is flushed by the call to <?=$obj_FMK->strokeBody()?> within your Template file.

This is why separation of code is important to encourage code re-use. You will also notice that very little code is in here other than a ‘switch’ and ‘include’s.

{zone_dir}/FMK_Hooks.php (optional)(modified by developer)
Similar to above Hooks file. This allows you to insert extra code that should execute every time the zone is referenced.

{zone_dir}/index.php (required)
Prevents web-access to zone index.

{zone_dir}/dsp_????.php (created by developer)
{zone_dir}/act_????.php (created by developer)
{zone_dir}/qry_????.php (created by developer)
These are “developer’s” files (see below) which contain the actual php for you web application. Every php file the developer writes must begin with either act_, qry_, or dsp_.

Developer files.

These are “user-defined” files created by you (the developer). You can create as many as you like but you must adhere to a strict file naming convention and separate your code based on its function/purpose. These files live within the Zone sub-directories. There are 3 primary “categories” that code can serve:

Display Code:
{zone_dir}/dsp_*.php
This code displays to the browser. Mostly HTML code should go here.

Action Code:
{zone_dir}/act_*.php
This is code that does something (action). Mostly any code that processes form submissions, save files or data, launches a sub-process, etc...

Query Code:
{zone_dir}/qry_*.php
Any time you need to access the database, it is best to put SQL code in these separate files. This way you can easily re-use these queries for other web pages.

Zone Actions

Now let us put everything you have learned so far together.

The “zone action” is a variable parameter passed in every url page request. For example:

/index.php?fmk=users.login

The zone action has two parts separated by a period. Left of the period is the zone, and to the right is the action for that zone. In the example above, the framework will go to the Handler file for the “users” zone which is located in the ‘webroot/users’ directory (as defined in FMK_Zones.xml.php”). The Handler will then execute only the files designated for the “login” action, which is just the “dsp_login.php” script. This script simply renders the login page.

Another example:

/index.php?fmk=events.sigsum

First we lookup the “events” zone in ‘FMK_Zones.xml.php’.

We find that it points to ‘{webroot}/events’ directory.

Now we look at the ‘{webroot}/events/FMK_Handler.php’ file and look for “sigsum” case statement.

We see the following files are included:

include ("dsp_header.php");

include ("qry_sig_summary.php");

include ("dsp_home.php");

Therefore the signature summary page is rendered by only the above three files, then the framework ends.

Conclusion

This framework makes it very easy to find the code you need simply by tracing the “zone action” to it’s files. Since every zone is defined in this manor, you can find any page’s php scripts fast.