3. EWE Programming Guide

This document describes how to integrate with, and use, the EWE framework on your web page(s). Programming with EWE requires the use of PHP. It is assumed that the reader has experience programming with PHP 5, or later. Familiarity with Javascript is also necessary for certain features.

3.1. Concepts

This section describes the general concepts of EWE.

3.1.1. Introduction

EWE consists of a group of PHP classes that interface with the database and provide basic features. Also provided are a group of PHP files which serve as an interface to that functionality. None of these files should be modified. Doing so can result in your site breaking when a new version of EWE is installed.

EWE supports multiple concurrent sites, each of which can have separate settings, users, etc. Site 0 indicates EWE itself. For instance, EWE supports users that can access various features of EWE, but not necessarily any of the features of any of the sites. Likewise, a site may have users which have no access to EWE. The users (and other features) for each site are segregated from each other, although they can be set up to be shared between them as well. As a consequence, EWE features can operate within the context of a given user, who exists within the context of one or more sites (or only within EWE itself).

Note: Do not modify the provided EWE pages themselves. If you do, your changes will be lost upon the next update. Instead, use the modules feature to extend or alter the Admin Panel look and behavior.

3.1.2. Directory structure

The EWE directory structure on the server can be installed anywhere inside the HTML document folder. Within the EWE folder (by default, the root document folder), there are several files and the following folders.

3.1.3. Errors

3.1.3.1 Database, function and method errors

It is important to note that EWE returns errors as arrays that contain a module identifier and an error code. This supports dynamically installed extensions (modules) in EWE. Use the functions in the Errors.php file to create, examine, and/or translate these errors to text.

Error results are returned by many class methods. These results are included with any other data that the method may return. The actual implementation of errors is hidden behind a series of functions in Common.php, as described below. Error results consist of a module and an error code. Thus the same code (an integer) can be used in multiple modules and mean something completely different.

base/Errors.php includes EWE error constants and the functions for handling errors:

is_error($r) - returns TRUE if the result $r is (or contains) an error, and FALSE otherwise.

ert($r) - returns error text for the passed error in the current language. If parameter is not an error, a null string is returned.

make_error($module,$code) - returns an error result for the specified module and error code.

make_SQL_error($code,$text) - returns an error result for an SQL error. $code is the SQL error number. $text is the SQL error text.

get_error_text() - returns last error text for the session

clear_error() - clear last error text for the session

set_error_text($e) - set last error text for the session

set_error($e) - set last error text from the passed EWE error code

3.1.3.2 PHP/Server Errors

EWE provides support for errors due to PHP code, including logging of errors. There are some global variables that allow you to customize how EWE responds to such errors. Errors are handled by the EWE custom error handler in Errors.php called eweErrorHandler(). This error handler is set up as soon as EWE code begins to execute. Setting your own error handler will disable the logging of errors to the error table.

3.1.3.2.1 $ewe_error_reporting

In the _ewe.php file there is a variable named $ewe_error_reporting which is set to FALSE by default. However, you can modify this to set it to TRUE to enable full debugging output including the backtrace. This should only be used during development and not enabled on production servers, because it could reveal information to attackers that might compromise the security of your site. Make sure to only turn it on temporarily. You can also leave the file as it is and change the value of the variable in your code, however the purpose of this variable is to enable debugging error reports as soon as EWE code begins to execute in order to catch early errors - including ones which prevent any of your EWE pages from showing. These errors are not logged to the EWE error table.

3.1.3.2.2 $handle_errors

In the Errors.php file, there is a variable named $handle_errors that defaults to FALSE. If left as FALSE, nothing is shown to the user by EWE and normal PHP error handling happens. If set to TRUE, an error message (containing only the text of text ID 465) is shown to the user and PHP execution is terminated. In either case, the full error and backtrace are logged to the EWE error log for later examination.
Note: you should never change the Errors.php file. If you want to enable this error handling, change the value of the variable in your code.

3.1.3.2 HTML errors

EWE provides error handling pages for the various 4xx and 5xx HTML web site errors. For instance 404.php handles 404 ("page not found") errors. You may need to configure your web server software (Apache, IIS, Nginx, etc) to redirect to these files when errors occur. You should not modify these pages to customize your sites' behavior. Rather, you can create a file in the same document root folder with the name "customXXX.php", where "XXX" is the error code. For instance, "custom404.php" allows you to alter the handling of 404 errors. In these files, after you do your custom processing, you can allow the normal 404 handling to occur or you can override it completely by using the PHP exit command (or redirect with header() and then exit) to end the processing.

3.1.4. Privileges

Each user can have one or more privileges assigned to him which allow access to specific features. This allows the administrator to specifically allow or disallow access for each user for each feature for each module. See the Administrators Handbook for more information.

Privileges are tokens that can be associated with a user to grant them permission to perform certain actions on the server. Privileges are granted to a user/site/module combination. Thus a given user may have permission to add users to one site, but not to another. Modules may define their own privileges or may make use of the pre-defined EWE privileges, although retasking the pre-defined privileges may lessen the flexibility and resolution of privilege assignments. Rather than have dozens of priveleges, each for a discrete operation, or only one to allow all operations, most modules are best served by segregating related operations into a manageable set of privileges. This strikes a balance between ease-of-administration and the flexibility of restricting what a given user can do. Pre-defined privileges (defined in base/_privileges.php) are described in the EWE Administrator document.

The EWE classes provide security checks for all attempted operations. This is provided as a service for code that uses these classes - it will not prevent problems caused by malware. Only install EWE modules from trusted sources. To keep your own code from being insecure, be sure to access EWE tables and functionality only through the provided classes.

3.1.4.1 Privilege Support Functions

• Enforce_Login() - this function will redirect to the login page if the user isn't logged in.
• Enforce_Privilege($priv,$module,$site) - when called, this function will redirect to the login page if the user isn't logged in. Otherwise, the current user is verified to have the passed privilege for the passed module and site. To check against multiple privileges, use the User::Has_Privilege() method for each privilege.

3.1.5. Text and Translations

EWE provides a means of customizing pages for different languages. Text displayed on PHP pages can display in the language of the user's choice. If the text has not been defined for the current language, it will default to the English text. The Texts class is used to support this. The text can also be customized via the Admin panel. Each site and module have separate text sets.

To support customization and translation of text, each module should define its text such that it is added to the text tables during installation. This will allow for customization and user-added translations for languages not provided by the module writer.

Substitution
It is important not to construct text from multiple strings, such as:
$text = $Text->Get_Text(THE_COMPANY_NAME_IS,0) . $company_name;
In different languages the position of the company name will differ in the text. Therefore, it is better to construct the table text with the place for the company name indicated by a dollar sign. For instance, the actual text would be defined like this:
The company name is $
Then the PHP code would use something like this:
$text = $Text->Get_Substituted_Text(THE_COMPANY_NAME_IS,0,$company_name);
In this case, the dollar sign is subsituted with the company name and the entire combined text is returned. Thus, when another translation or customization is defined, they can place the dollar sign in whatever position makes sense for that language, so the resulting text will be correct.

Another consideration is text that differs by amount. For example, let's say you have text that indicates the number of matches found for a query. In English, there are two or three variations of this:
No matches were found
1 match was found
3 matches were found
which is better than a single text which would read something like:
1 matches were found
or
3 match was found
In such cases, the different texts should be defined and the appropriate one used with or without substitution, as appropriate. For instance:
No matches were found
$ match was found
$ matches were found
One could assume that in the second case, there is no need for substitution since it could be hard-coded to 1. However, then the text is not suitable for cases where another variant is used - such as "One" instead of "1".

Note that Get_Text will treat any contained dollar signs as literal dollar signs.

3.1.6. Logging

EWE can log events and errors of various categories. This is supported by the User class.

3.1.7. Hooks

EWE provides customization of existing behavior by means of "hooks". Hooks are associations between modules and behaviors. When a behavior is about to happen - or has already happened - any associated hooks result in calls to the hooked module where it has a chance to modify, replace, or augment the behavior. Some behaviors have multiple associated hooks: the most common are an "early" hook, and a "late" hook. Early hooks happen before the behavior and Late hooks happen after. Hooks can perform actions via PHP and/or insert HTML or javascript code into other pages. Validation hooks can return a success/failure code in addition, or instead of. Validation hooks typically return > 0 for success, 0 for N/A, and < 0 for failure, although the actual values may differ for some hooks. Unless explicitly stated as being a javascript hook, any text output by the hook is assumed to be HTML. Multiple modules can hook the same behavior. Hook calls can also be passed some additional information. Unless otherwise stated, most hooks pass an empty string.

The following standard hooks (for module 0) are provided (they are defined in base/_hooks.php):

3.1.6. Preferences

Preferences can be persisted in a preference table, keyed by site and preference name. Note that all EWE reserved preference names begin with a dollar sign ($). Any module storing preferences should not begin any preference with a dollar sign.

3.1.7. Database Access

EWE is not inherently bound to a particular database. The Database class (in Database.php) defines the database interface used by EWE, but the actual database access occurs in descendents of that class. By default, EWE uses the MySQL database for its database operations. Whichever database system is actually used, it must be defined as a descended of Database. All database access must be done through an instance of the Database descendent. This supports the database explorer, and allows redirection (see below), monitoring database activity, logging of errors, etc.

EWE allows tables to be spread among several database servers, if desired, for performance. The tables are grouped by general functionality. The database sets are:

By default, all tables are assumed to be in the same database, but all database access code should be sure to ask for an instance of the appropriate database from Databases::get_database before doing database operations. Code should never access the database outside of the database instance returned by that method. Any number of database set names can be used without problem: if redirected by the admin, database I/O will be redirected as the admin desires. If not defined/redirected, the table will be created and accessed in the default database. Low-use database tables can be associated with one of the above defined set names, but if the database is large or heavily-used you should provide the admin with the option of placing the tables on a database of their choice by using a custom database set name.

3.2. Using EWE in PHP pages

3.2.1. Basics

The following files are included directly or indirectly by prepare.php:
/eweroot.php
base/_ewe.php
base/_prepare.php
base/connect.php
base/Common.php
base/Errors.php
base/ewe.php
base/Utility.php
classes/Geolocation.php
classes/Sessions.php
classes/Sites.php
classes/Server.php
classes/User.php

The following code should be at the top of all PHP files that make use of EWE.

	$root = $_SERVER['DOCUMENT_ROOT'];
	if(substr($root,strlen($root)-1)!=DIRECTORY_SEPARATOR)
	{
		$root .= DIRECTORY_SEPARATOR;
	}
 	require_once( $root . 'eweroot.php' );
	require_once( $ewepath . "base/prepare.php" );

If you include prepare.php at the start of your page, you should also include:

include "pageend.php";

3.2.2. Database access

• db_query($sql) - Execute SQL statement.
• db_insert_id() - ID of after db_query is used to insert a row.
• db_real_escape_string($s) - Return escaped string version of $s.
• db_num_rows($r) - returns number of rows affected by last operation on context $r.
• db_fetch_assoc($f) - returns associate array of columns from next row in results.
• lock_table($t1,$t2) - Locks tables $t1 and $t2 ($t2 may be null to only lock a single table).
• unlock_tables() - Unlock locked tables.

3.2.3. Restricting access to pages

You can also verify that a user posesses certain privileges to access the page by using the Enforce_Privilege() function (see section 3.1.4.1 Privilege Support Function), which will first make sure that the user is logged in and then check the user's privileges. If they don't have the specified privilege, they are redirected to the login page. Multiple calls to this function can be used to ensure that the user posseses several different privileges. For more complicated scenarios (such as having one of several possible privileges) you can use the User::Has_Privilege function in an expression.

3.2.4. Logging Page Views

If you wish to use the Page View feature for a given page, include the following PHP code after including prepare.php:

if($uuid>0)
{
	$S->Mark_File_View(__FILE__,true);
}

3.2.5. Sessions and Global Variables

Using prepare.php will make sure that you have a session properly configured and available for use. The PHP session ID will change for a given session, but a unique user ID (uuid) is created for each accessor, which can be used to identifier someone who is accessing the site, even if they change the user ID (uid) by logging out and logging in as another user. prepare.php sets $uuid to the session UUID, as well as setting other PHP variables as described above. In addition, the following session variables are set up and available for use.

3.3. Style sheets

The standard EWE style sheets are defined in css/ewe.css. This file should not be modified since any update to EWE will overwrite it. However, you can provide your own style sheets in css/custom.css. This is included after ewe.css, so it can override the ewe.css styles where desired.

3.4. Classes

EWE provides several classes that allow PHP code to access the EWE. The class files are found in the EWE classes folder.

3.5. Customizing your EWE installation

EWE is intended to provide a framework for a web site(s), doing much of the support work for maintaining that site. However, not every feature of EWE will meet the needs of every site. EWE provides numerous ways to seamlessly integrate with a web site. In many cases, simply choosing the desired server or site preferences will be adequate. In other cases, installing or uninstalling optional modules will provide the ideal control. The ability to define translations of text used in EWE may provide sufficient customization. However, if none of these options meets your needs, you can customize EWE via your own PHP code.

You should never modify any of the supplied EWE pages, since an update to EWE may cause those changes to be lost. However, many EWE pages provide a way to insert your PHP code in place of standard functionality. The easiest means of customization may be to write your own module(s) and install them (see Modules documentation), which allow you to hook into many parts of various EWE pages to customize their operation.

If modules don't provide for your needs, many EWE pages allow the inclusion of custom PHP files which can be used to supplement or replace those EWE files. The following sections describe these customization points. These files must exist in the same folder as the file to be customized, and their names start with "custom". See section 3.1.3.2 for a discussion of how to customize HTML error response (such as 404 errors).

3.5.1. Sessions

Session use is wrapped in the Session class (Sessions.php). If you wish to alter Session behavior, you can write a descendent or replacement class in customsesssion.php, set the global $session variable to a new instance of that class, and use exit() to prevent the global $session variable from being assigned an instance of the standard Sessions class. If you create a descendent class, be sure to include "session.php" to bring the standard class definition into your code. If you are creating a complete replacement, be sure to descend it from the EWE_Sessions abstract class, defined in Sessions.php, prior to including customsession.php.

EWE doesn't create any session save handlers, so you can safely use session_set_save_handler() to customize that aspect of sessions.

3.5.2. PHP errors

EWE catches and handles most PHP source and execution errors with its own error handling, however, you can override this in your code by creating your own handler and using set_error_handler() to point to it. You should call the original handler after the processing in your own handler so that logging, etc. can be done.

3.6. Class and Function Reference

Continue to Modules