Framework for Classes

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

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.

/*****************************************************************************/
/* D E P E N D E N C I E S                                                   */
/*****************************************************************************/

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

List constants that you require.  The constants should be defined using the following guidelines: - format: <classname>_<type>_<description> - example: BANDWIDTH_FILE_CONFIG The <type> can be FILE, PATH, DEFAULT (for default value) or something that just makes sense.

/*****************************************************************************/
/* C O N S T A N T S                                                         */
/*****************************************************************************/

define(BANDWIDTH_FILE_CONFIG, "/etc/sysconfig/cbq/interfaces");
define(BANDWIDTH_PATH_CONFIG, "/etc/sysconfig/cbq");
define(BANDWIDTH_DEFAULT_EXTERNAL, "eth0");
define(BANDWIDTH_DEFAULT_INTERNAL, "eth1");
define(BANDWIDTH_DEFAULT_SPEED, 10);

There are quite a few base classes that you can extend.  For install All daemons on the system (Apache, Squid, etc) should extend the Daemon class.  You can view the class hierarchy here. For the Java developers out there, you will notice the documentation style... it's Javadoc!  By following the documentation style, the documentation can be output in HTML here.

/*****************************************************************************/
/* C L A S S                                                                 */
/*****************************************************************************/

/**
 * Bandwidth limiter.
 *
 * @author   Point Clark Networks
 * @version  2.0, 5-16-2003
 */

class Bandwidth extends Daemon
{

Some gotchas about the constructor: in PHP 4.x, the call to the parent constructor must be done explicitly, e.g. this->Daemon(...). Try to avoid potential fatal errors in the constructor; PHP is not a real object oriented language and can't deal with it in a sane way.  If you are including locale support, add the two required lines in the constructor.

	/*************************************************************************/
	/* M E T H O D S                                                         */
	/*************************************************************************/

	/**
	 * Bandwidth constructor.
	 */

	function Bandwidth()
	{
		$locale = new Locale();
		require_once($locale->GetLanguageTemplate(__FILE__));
		$this->Daemon("bandwidth");
	}

All methods should use the &$errmsg passed by value.  When an error occurs, return an error message of some kind in errmsg.  This is a silly way to create a Java-like exception. For consistency, try not to use booleans to return a status (success or failed).  This way, we know that all methods with an errmsg failed, and all methods without errmsg succeeded.  We can then use booleans to return other logic (for instance, in the IsValidIP(...) routine.

	/**
	 * Add bandwidth limits by IP address (LAN or DMZ).
	 *
	 * @param   ip        IP address
	 * @param   up        upload speed
	 * @param   down      download speed
	 * @returns void
	 */

	function AddIp($ip, $up, $down, &$errmsg)
	{
		...
	}
 

	function ....
	{
		...
	}

Validation routines should use the IsValidXyz method naming convention.  The routine will return true if valid, false if invalid, and something in $errmsg if an error occurs.  The IsValidXyz is the one place where you might not see $errmsg in the method.  That's simply because most validation routines are merely a couple of regular expressions and string length checks -- external errors (like a file open error) just don't happen.

	/*************************************************************************/
	/* V A L I D A T I O N   R O U T I N E S                                 */
	/*************************************************************************/

	/**
	 * Validation routine for IP addresses.
	 *
	 * @param   ip        IP address
	 * @returns boolean
	 * @return  true if IP is valid
	 */

	function IsValidIp($ip, &$errmsg)
	{
		...
	}
 
}