Framework for Web

Thank you to Michel Scherhage for putting the original documents together.

The framework for the PHP pages is not as strict as other coding standards.  You may find that you have to deviate from the suggested guidelines.  That's ok!

Add your copyright notice, and licensing information.  The software does not have to be GPL... this is just showing an example.

///////////////////////////////////////////////////////////////////////////////
//
// Copyright 2004 Point Clark Networks.
//
///////////////////////////////////////////////////////////////////////////////
//
// 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 2
// 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, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
//
///////////////////////////////////////////////////////////////////////////////

List any class files that you use.  If you want to include support for other languages, you will want the locale.class. In our bandwidth example, you will see firewall, network and file related class files as well.

require_once("daemon.class");
require_once("file.class");
require_once("folder.class");
require_once("network.class");
require_once("firewall.class");
require_once("locale.class");

// Retrieve language translations
$locale = new Locale();
require_once($locale->GetLanguageTemplate(__FILE__));

The standard header usually starts with three function calls: - WebAuthenticate is for authentication. - WebHeader displays the page title and menu system. - WebDialogIntro displays introduction with text and icon.

///////////////////////////////////////////////////////////////////////////////
//
// Header
//
///////////////////////////////////////////////////////////////////////////////

WebAuthenticate();
WebHeader(WEB_LANG_PAGE_TITLE);
WebDialogIntro(WEB_LANG_PAGE_TITLE, "/images/icon-bandwidth.png", WEB_LANG_PAGE_INTRO);

Next, we need to handle forms submitted by the user.  You will often see objects created ($bandwidth = new Bandwidth()) followed by a list of actions. Take note of the error handling.  When we handle an update from a form, we add error messages (usually a single sentence describing the problem) to a string array.  We can then use the WebCheckErrors() to HTML-ize the error messages.

///////////////////////////////////////////////////////////////////////////////
//
// Handle Update
//
///////////////////////////////////////////////////////////////////////////////

$firewall = new Firewall();
$bandwidth = new Bandwidth();

if ($AddIp) {
        $bandwidth->AddIp($new_ip, $new_upspeed, $new_downspeed, $errors[]);
        $bandwidth->SomethingElse($justatest, $errors[]);
} else if ($DeleteIp) {
        $bandwidth->DeleteIp(key($DeleteIp), $errors[]);
} else if ($AddPort) {
...
}

$errmsg = WebCheckErrors($errors);

If no errors have occurred, and one of the actions by the user requires a configuration reload... then this is the place to do it.  In our bandwidth example, we restart the firewall and bandwidth software when the user adds an IP (AddIP) to the limit list. $daemon->Reset() vs $daemon->Restart() -- what's the difference?  A reset performs a configuration reload if possible, while a restart performs a full stop/start on the daemon.  Most of the time, you should use the reset method.  You may find that daemons behave better with a full restart.

// Reset/Restart service on config change
//---------------------------------------

if (($AddIp || $DeleteIp || ... ) && !$errmsg) {
        $firewall->Restart($errmsg);
        $bandwidth->Restart($ignore);
}

Once all the updates are complete, we have a short and simple main section to display our page.  Keep it simple here; you should only see if statements and function names.

///////////////////////////////////////////////////////////////////////////////
//
// Main
//
///////////////////////////////////////////////////////////////////////////////

if ($errmsg)
        WebDialogWarning($errmsg);
DisplayConfig();
WebFooter();

Last but not least, we have our functions to display information to the end user.  In our example, we only have one function: DisplayConfig().  The only guideline we have here is to try and keep the logic separate from the HTML.

///////////////////////////////////////////////////////////////////////////////
// F U N C T I O N S
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//
// DisplayConfig()
//
///////////////////////////////////////////////////////////////////////////////

function DisplayConfig()
{
        global $bandwidth;
        global $firewall;

        ... do logic first ...
        ... do web output last ...
}