Note: Some content on this site, including this article, is more than a decade old, and may not accurately reflect the author's current feelings or writing style. More information here.

This document details the usage, installation, and configuration of the PHP-based modular site framework designed by Natasha L., with gracious assistance and guidance from William Harris. This system was designed to be lightweight, highly portable between sites, easily expandable, and non-restrictive to designers implementing it while making the site as user-friendly as possible to visitors as well as site owners maintaining their website.

History

The Blackwolf PHP framework was a long-term project, initially developed for Lupinia.net in 2006. In 2008, I started turning it into a more robust platform to use in clients' websites, and development of new extensions and features continued until 2012.

Requirements

This framework requires PHP 5.1.x or greater to work properly. Converting it to run on PHP 5.0.x may be possible, but attempts to port it to PHP 4.x have been unsuccessful, due to the amount of re-coding required. It has not been tested on versions greater than 5.2.x, as of this writing. The database interface currently is written for MySQL, but can be easily converted to other engines.

Files And Directories

This system can function properly with a small fileset. The files required for operation are:

Directory structure is fairly simple. This framework expects all classes to be in /INC/, with one file per class, and the names to be in the form "class_{CLASSNAME}.php". This is done so that PHP's auto-load function can initialize them properly. This can be modified if needed, as long as the changes occur across all necessary files. Also, if using the Flash auto-embed function in class_main_old.php, all Flash files must be stored in /SWF/. This can also be changed by modifying the code responsible for it. And, most of the functions/files dealing with output assume that CSS files will be in /CSS/, and images will be in /images/.

Configuration

To reduce page generation times, and improve security, this system lacks a separate configuration file. Instead, the configuration variables are stored in class_core.php, in a well-marked area of the file. The configuration area is denoted by these comment lines. The wording was chosen because a client may need to edit the config information themselves (server moves, title adjustments, etc), so this is worded in such a way to set the user-changeable portions apart from the rest of it (which is fair game for developers using this system).

//	@@@@	DO NOT EDIT ANYTHING ABOVE THIS LINE!	@@@@
...
//	@@@@	DO NOT EDIT ANYTHING BELOW THIS LINE!	@@@@

With the exception of database credentials, all configuration variables are stored in a public associative array called config, which can be expanded as-needed. To increase security, the database credentials are stored in a protected array called db, which cannot be accessed outside of the core/main classes.

Many of the elements of the config array are dynamically generated, but some are set manually in the configuration area of the core class. The following elements are present in the config array once the constructors for main and core have been executed.

Global Variables

To streamline the configuration process and extend the usability of this system while minimizing redundant code, this framework uses global variables to set various pre-load options for the main object. These can be tailored to a site's specific needs, and must be set before class_main_old.php is included. These should only be used to handle exceptions and special cases that vary from page to page. For properties that should apply site-wide, changes should be made to the main code of the site.

Functions

The files used by this system have a number of public functions available, to simplify various tasks used within a site, and create a unified environment for other applications/scripts. The following public functions are built into the system. Please note that parameters surrounded by brackets are optional.

load_flash($flash_src, 
           $flash_height, 
           $flash_width,
           [$flash_loop],
           [$flash_title])

Usage

This system is meant to be easy to deploy, and easy to work with once it's deployed. The original application for it was a site with individual pages for content, and was designed to simplify the process of adding new pages to the site. It was later used to rapidly deploy client websites, and build them in ways that someone with even the most rudimentary knowledge of HTML could perform most of their own maintenance. So, the starting point for a new page using this system should look something like this:

<?php
{GLOBAL VARIABLES}
require './INC/class_main.php';
?>

Page content goes here.

No additional functions are required after the content of the page; all final output by page_footer is handled by the main object's destructor function. However, if the page uses the no_header global variable, be sure to add "${MAIN}->page_header();" before any output, where {MAIN} is the variable name of the main object (set at the very bottom of class_main_old.php, to simplify the per-page PHP coding required for simple pages).

User Management Systems

One of the integral features of this framework is its user management system. Designed to be both simple and powerful, it provides the basis necessary for dynamic applications, as well as providing site administrators with the tools necessary to manage the site and its users.

The user systems are meant to handle multiple levels of security, and/or multiple types of accounts. The most notable implementation of this is the default designation of admin accounts vs. user accounts, using the 'isAdmin' database value. This allows any user to be granted administrative privileges without sharing credentials, a rather dangerous security practice. This also allows for administrative controls to be added throughout the site, as well as having them in a protected control panel.

Login/Logout
These functions are, by default, both handled by login.php, though an AJAX-based interface, or a small login form, can be added to any page with ease. The login form features a "Remember" checkbox, so that users don't have to login next time they visit the site. When checked, this stores a cookie on the visitor's computer containing hashed data uniquely identifying them for their next login for 30 days, and is renewed every time they visit the site. In order to make this a secure system, the hash is created from the user's IP address, last login time, and a number of browser-specific headers, as well as some user-specific data, and the user ID stored in plain-text (which can't be used in any form of login attempt). When visiting, if this cookie is present, the site forms a new hash based on the current visitor's information (browser, IP, etc), and a third hash based on information stored in the database from the user's last successful login. If all three hashes match, the user is logged in as normal. If not, the cookie is deleted, and the user's stored login information is invalidated, preventing any further attempts. This is, admittedly, an "overkill" level of security for most sites, but it was originally conceived as part of a rather secure site, and it has proven to be highly effective.

If the Remember checkbox is not checked, the user's login is session-based as normal. The ability to remember logins cannot easily be removed/disabled at this time, but for a site requiring it to be omitted, the code can be edited to reflect this change.

Registration and Activation
User registration is handled by register.php, a file that is recommended to be present even for sites that don't need it, due to the complexity involved in creating a valid password hash. The registration form uses live Javascript-based validation (currently driven by Adobe's Spry framework, but can easily be replaced with a lighter version of our own design), but to maintain functionality when Javascript is disabled, the form and processing script will still function perfectly without it. Thus, it can be omitted altogether, if desired. The form currently uses a simple math question to serve as a bot-filter, but experience has shown this to be only moderately effective. A more typical CAPTCHA script can be added in the future.

Upon successful registration, the site's primary administrator receives an email informing them that a new user has joined. This can be adjusted in the code to email all admins, or none, depending on the site. By default, admin activation is used, requiring administrators to manually approve new accounts. For more community-oriented sites, this can be switched by a config variable to allow self-activation by users based on an activation code received via email, but the ability of admin accounts to manually activate accounts is still retained. In either case, the user will receive an email upon joining, containing either instructions on account activation, or informing them that an administrator must approve their account before they can login. Another email is sent when an account is administratively approved, informing the user that their account is now active. This second email is not necessary when a user self-activates.

Account/Profile Editing
Users can edit their account information using account.php, which contains a form very similar to the registration form. This page can also be edited to show additional profile fields, if desired. The form is automatically populated with the user's account information on each load, to make sure the information is always accurate. It also provides an interface to change the user's password, which doesn't have to be entered in the form is the password is not being changed. The login username, however, cannot be changed once the account is created. Since it's used to generate the password hash, changing it via a form without breaking the user's ability to login is difficult to accomplish, and has been omitted for the time being. The login username is only used by the user to login to the system, so the ability to change it is irrelevant; the user can change their display name with ease if they wish to adjust their identity as perceived by other users. Since the login username cannot be seen by non-admins, and the display name cannot be used to retrieve any account information or login, setting a display name different from one's username is highly recommended for security reasons on community-based sites.

Any user viewing account.php will be presented with the Edit Account form for their own account. Additionally, an administrator viewing the form can edit any other user's account by supplying the GET variable "id" (linked from the user table). Non-administrators will not see this behaviour even if they supply this variable.

Advanced User Management
The users.php file is a multi-purpose page providing an interface for all other user management functions. It displays a table of users, containing a variety of information, including the user's display and usernames, last IP address and login time, email address, and a number of links to control the user's account. Administrators are displayed in bold, inactive accounts are displayed in italics, and if a user has opted to hide their email address, it will be displayed in italics instead of normal print. The Actions column contains, by default, icons to edit and delete each account, as well as text links based on the user's current status. For admins, a Revoke Admin link is displayed, a process that requires the revoking user to supply a reason for revokation, and sends an email to the former admin containing the reason, as well as the IP address and display name of the user performing the revokation. For inactive accounts, an Activate link is displayed, the process for which is explained above, under "Registration and Activation". And, for regular users, a Grant Admin link is displayed, a link that promotes the user to administrator status.

By default, users.php can only be visited by admins. However, in community-oriented sites, it can be changed to user-level (or even guest-level) security, and serve as a user directory. For non-admins, the table is generated with a different, smaller fieldset, containing only the display name, last login day (the time is omitted), and their email address (if not hidden). With the addition of the email form I've written to work with this system, the email address can be completely hidden to all non-admins; users can email each other using the form, but cannot access any other user's email address.

Due to its structure, users.php can also be tasked to display individual profiles simply by adding a function call to generate them. This versatility makes it a very powerful file for building robust community-oriented sites, and its security measures ensure that there can be no unauthorized use of administrative controls by non-admins. However, if preferred, the modular nature of the user management functions allows them to be split up and called by a number of different files, if desired.

Extensions

For a basic website, this framework will handle most scripted tasks without needing extra files. However, for a more complex site, extensions may be needed/desired, to create a more dynamic environment. Fortunately, this system was designed to be easy to expand, while keeping the special coding required for outside scripts/applications to a minimum.

Ideally, extensions should be classes, to maximise the effectiveness of the object-oriented nature of this site structure. To write a class that works as an extension to this framework, it only needs to copy (pass by reference) the current instance of the main/core objects into its own variable. For example, the starting code for an extension may look like this:

<?php
class MyExtension
{
	protected $main;
	
	function __construct()
	{
		$this->main = &$GLOBALS['MAIN'];	//	Replace MAIN with the variable name of the main class in the current site
	}
}
?>

Writing classes this way allows them to interact directly with the current instance of the main class, without redundant code, and without re-initializing it, maximizing security and efficiency. In this example, MyExtension can now use the security information, config variables, and database interface from the rest of the site without rewriting it. This also dramatically increases code portability, because the only thing that needs to be changed to move this to a new site is the name of the global variable containing the main object.

Theoretically, the core class can be re-initialized in other objects without affecting the rest of the site, but this approach is not recommended. Not only does it unnecessarily increase database and processing overhead, but the debug data (processing time, query counter) becomes useless.

New extensions can readily be added to any site containing this system. The following extensions have already been created, as of this writing:

• Multi-category links manager
• XML-based content management system (metadata/index generation only)
• MySQL-based content management system (content pages/index generation only, in progress)
• Simple image gallery
• Interface for Gallery2 (image insertion in other pages, internal links, random display, album display)
• Interface for Wordpress (post aggregation without RSS, for display elsewhere in the site)
• Interface for Simple Machines Forum (in progress)
• Timeclock application (in progress)
• FAQ Manager