The following sections discuss the layout of PHPLIB: Which functionality and class definitions are contained in which files? How do you layout a web server with PHPLIB installed? Which installation options are available and how do these affect performance?
PHPLIB contains a set of core classes and functions that offer session tracking, per-session and per-user persistent variables, user authentication and permission checking. Building upon this core functionality, PHPLIB offers a set of commonly needed "background" classes and a set of "HTML widgets", classes that allow you to quickly generate HTML based user interfaces.
All PHPLIB definitions are designed that you don't need to
change any of these files. Your customization of PHPLIB can be
contained in two or three files, depending on the setup:
local.inc, setup.inc and, in some cases,
prepend.php3. Details are outlined below.
The following three files are the only files from PHPLIB that require changes in normal PHPLIB applications.
local.inc:Your application will almost certainly not work with the default values supplied by the above classes. You are supposed to extend the classes described below as you see fit.
In your subclasses, you only have to specify what is different in your application. These are things like database host names, database names, table names and username/password combinations. You need to provide login screen definitions (HTML) and user validation functions (SQL) to make the example work.
The distribution provides a local.inc to illustrate
a typical setup. These definitions are also needed to get
the administration and testing scripts provided with the
distribution to run.
The file is required and you must change it for your setup.
setup.inc:The Session class provides the ability to execute
initialization code at session setup. See the class
description for instructions on how to set this up.
Per convention, we store such code in setup.inc
in the include directory. The code is being executed
whenever a new user connection to out application and
a new session is started.
The file is optional. No default is provided.
prepend.php3The file prepend.php3 determines which code is being
loaded for all PHP3 interpreted pages. Normally, we include
the class definitions for all core classes in this file:
db_mysql.inc, session.inc, auth.inc,
perm.inc, user.inc, then your local customizations
from local.inc and the page management functions from
page.inc.
You must change prepend.php3 to reflect the database
interface that you are using: Change the require
statement for db_mysql.inc appropriately.
If you are not using some core features from PHPLIB in your
application or if you want some other features to be present
on all your pages, you can delete or add require
statements for their respective include files here.
The file is required. You must change it for your setup, unless you are using MySQL.
The following files are included from prepend.php3 and
provide definitions for the core classes of PHPLIB. We recommend
that you always include all of them, as they are a tightly
integrated set of classes with many dependencies among them.
DB_Sql defined in exactly one of
db_mysql.inc, db_pgsql.inc,
db_odbc.inc or db_oracle:
A database access class for your database server. PHPLIB
depends on the presence of a SQL database server. Depending
on the type of your database server, you have to select the
appropriate include file. The file contains the definition of
a class DB_Sql suitable for your database server.
The class manages a database connection (connection setup is implicit) and result memory is managed automatically.
An independent class.
Session defined in session.inc:Manages an arbitrary amount of arbitrarily named session
variables of scalar, array and object types (Object support
requires that you implement two instance variables in your
classes). Tracks sessions via cookies or a get-variable
appended to each URL.
Depends on DB_Sql.
Auth defined in auth.inc:Manages session authentication. Sessions are authenticated against usernames and passwords in a database. Authentication can be time limited.
Depends on Session and DB_Sql.
Perm defined in perm.inc:Manages permission checks on authenticated session pages. Protected pages are only accessible to users with the specified rights.
Depends on Auth, Session and DB_Sql.
User defined in user.inc:Manages user dependent variables. Unlike session variables these are bound to a user id, not to a session id. They are persistent over multiple sessions, but are only available after a user has been authenticated.
Depends on Auth, Session and DB_Sql,
extension of Session.
page_open() and page_close()
defined in page.inc:Setup and Shutdown functions, must be present on any session page.
Depend on Session.
The extended functionality classes offer GUI-less background features that are commonly needed in HTML-applications. They may make use of core functionality (indicated for each class below).
Cart in cart.inc:Manages a simple shopping cart. Items can be put into the cart, taken out of the cart and the carts contents can be enumerated.
Depends on Session to be useful. Requires that you add the
statement require("cart.inc") to prepend.php3.
HTML widgets are classes that generate some HTML-code (often forms or tables) to display GUI-elements. We try to provide functionality commonly used in applications, in a way that the actual look of the GUI-elements can be easily customized.
CSV_Table in csv_table.inc:Creates a dump of a two dimensional array or a query result in CSV format, suitable for loading into a database or a spreadsheet program.
Depends on Table, extension of Table.
Graph in graph.incCreate a linegraph gif image from some array data.
An independent class.
Sql_Query in sql_query.inc:Create a selection widget that allows a user to choose arbitrary conditions on one or more table columns. SQL is being created from these selections that can be used in the where-clause of a larger SQL select statement.
Depends on Session and DB_Sql. Requires that
you add the statement require("sqlquery.inc") to
prepend.php3.
Table in table.inc:Creates HTML tables from two dimensional arrays or from database query results. The class can either filter out the desired columns from an array or you can explicitly name which columns to show. A heading can be turned on if desired. All generated HTML elements are tagged with a classname you specify for stylesheet support, if needed. When used in a form tag, each table row can be prefixed with a checkbox input element to allow for row selection.
An independent class.
Form in oohforms.inc:Creates HTML forms from feature->value arrays. This provides a single syntax for creating all of the different types of form elements. The class provides easy access to Javascript and server side validation, and supports 'freezing' some or all of the form elements to display static data. In addition, the library relies on object oriented implementations for the various form elements and these can easily be extended and customized.
An independent class.
The base library is supplied at the PHP Base Library download location. Two different formats are provided: A tar.gz version and a shar version.
If you are on a windows system, you can use phplib.tar.gz, if you have WinZIP installed. Current versions of WinZIP know how to handle compressed tar archives. The uncompressed files may be installed on your windows system or transferred to your Unix system.
If you can't handle binary files, you may download phplib.shar.
This is a pure ASCII file containing a self extracting shell
script. Just save the file, make it executable and feed it to
your Unix shell (for example, by typing sh phplib.shar).
The PHP base library requires a working web server with CGI capability and the CGI version of PHP 3.0.5 or higher installed. Lower versions of PHP may work (at least PHP 3.0 is required), but have not been tested and are not supported. mod_php is supposed to work and has been tested.
Note: As of PHPLIB release-5, PHPLIB's Auth class uses the
internal variable $PHP_SELF to reference the page it was
called from. This variable is produced incorrectly in older
versions of CGI PHP. It is correct in mod_php and in version
3.0.5 or newer of CGI PHP. If you are using CGI PHP, it
must have been compiled with the
--enable-force-cgi-redirect switch for
$PHP_SELF to have the correct value.
Basically, if PHP_SELF is the exact local part of your $URL, all is well. If it instead contains the modified URL with /your cgi-bin/php prefixed, you have a buggy version of CGI PHP. Either upgrade your version of PHP or replace all occurrences of $PHP_SELF with $PATH_INFO in PHPLIB.
Note: PHPLIB requires that you have track_vars
compiled in and enabled.
Note: PHPLIB does not require short_open_tag to be
enabled. The library always uses <?php as the PHP
command introducer.
The PHP base library requires a database connection. Currently MySQL is fully supported and PostgreSQL, ODBC and Oracle have limited support (the limitation is only relevant if you intend to access metadata information, i.e. table definitions and the like). Database interfaces are not difficult to write and Adabas-D and Sybase are likely to be supported in the future.
You need a database server connection with select,
insert, update and delete privileges from your
CGI environment. You need create and drop privileges
from an administrative account outside your CGI environment as
well.
PHPLIB core functionality requires two tables as part of your
application table name space: active_sessions (select,
insert, update and delete privilege required for the application
user) and auth_user (select privilege required for the
application user. insert, update and delete privilege required
for the application user if user management is to be done from
within the application).
Extended functionality may require additional tables.
PHPLIB tries to be as name space neutral as possible with its
core features. Is issues no HTML by default and it occupies only
few names in the global name space. These are the class names for
the classes defined: DB_Sql, DB_SAM, Session,
Auth, Perm, User. Additionally, the classnames
DB_Poe, Poe_Session, Poe_Auth,
Poe_Challenge_Auth, Poe_Perm and Perm_User are
defined by the sample setup in local.inc, but these names
can and shall be customized by the application developer. PHPLIB
defines the function names page_open(), page_close,
sess_load() and sess_save() for the page management
functions. No global variables are taken. Only if
page_open() is being used, globals are defined by the
library by default, but one global for each "feature" requested
in the page_open() statement is taken. These are at most
$sess, $user, $auth and $perm.
Including extension functionality or HTML widgets may occupy additional classnames, function names or variables in the global name space.
PHPLIB uses date fields within the column changed in the
table active_sessions in your database. The
changed field is used in garbage collection, that is, to
clean out abandoned sessions. The date field is a 14 character
field of the format YYYYMMDDhhmmss, that is, the date field
has four digit years and will cope properly with the new
millennium.
PHPLIB sets cookies in the client browser. These cookies by default have session lifetime, that is, they do not expire but are not written to disk. Date calculations are not involved.
It is possible to have PHPLIB set cookies with a limited lifetime by defining the $lifetime slot of the Session class. If this is done, it depends on the date handling of the client browser and client operating system, if the result is Y2K compliant. There are known issues with longterm cookies and any browser on MS-DOS/Windows 3.11 systems.
PHPLIB does some date arithmetic internally that involves mktime() and date() functions of the PHP3 language and Unix time_t data types. The signed 32 bit Unix time_t data type counts seconds since 01-Jan-1970 Midnight GMT and will overflow sometime in the year 2038.
PHPLIB itself will function up to 2038 and longer, if the Unix time_t is being extended in time. PHPLIB does not protect you from date and Y2K issues in your PHPLIB application, the PHP3 interpreter, the server operating system oder server software, the client browser, the client operating system or other parts of your installation.
Create a directory php next to your cgi:
/home/www/servers/poe.shonline.de/pages <- document root
cgi <- php binary
php <- includes and prepends
Make this php directory your php include directory: Put
include_path = /home/www/servers/poe.shonline.de/php
into cgi/php3.ini. If you already have an include path
defined in your setup, add the PHPLIB include path to the
existing include path using the separator character applicable
for your operating system (":" on UNIX, ";" on Windows).
Defining an include path will not actually include code on your
pages; it only tells the PHP interpreter in which directories to
look for files referenced in require() and include()
statements.
Into the php directory go all the files from the php
directory of the distribution. Into documentroot, put all the
files and directories from the pages directory of the
distribution.
Have documentation.txt handy and read it.
The following information applies to MySQL only. No information is provided for other database servers as of now. You are encouraged to copy this section, adapt it for your database server and submit it to the authors. It will be included in further releases of PHPLIB.
Edit prepend.php3. Change the first require()
statement to require("db_mysql.inc");. This will
include the MySQL database interface (Interfaces for other
databases are provided in
db_<databasename>.inc. The require()
statement has to be adapted to reflect this).
Assuming your database server is named database.shonline.de
and your CGI user is webuser and you are accessing the
database poe_sessions, do
mysql -h database -u webuser poe_sessions
If it does not work, connect your database as administrator and
create the proper mysql access permissions. Adapt and run
create_database.mysql from the stuff
subdirectory of the distribution to create the databases
active_sessions and auth_user as well as
the sample user kris with password test. Try again to
connect like shown above. Can you do select * from
active_sessions? and insert into
active_sessions values ("1", "2", "3", "") as well as
delete from active_sessions? Can you select *
from auth_user?
Note: Additional database creation scripts are provided for
several different databases in the stuff directory of the
distribution.
Decide if you want to use include or
auto_prepend. We do use auto_prepend
here and we add the statement
auto_prepend_file =
/home/www/servers/poe.shonline.de/php/prepend.php3 to our
php3.ini.
Not all classes are included/required by prepend.php3, only
core functionality files are: db_xxx.inc, session.inc,
auth.inc, perm.inc, user.inc, local.inc and
page.inc. The library provides other, less essential
classes that can be included manually on a page-by-page basis.
Some classes make themselves persistent, if used. These classes
require that you include their definitions in the
prepend.php3 file where indicated to function correctly.
See the usage instructions for these classes for details.
Having done this, access /index.php3. The counter
should increment when that page is being reloaded. Also, checking
active_sessions in the database should reflect that
session.
Subscribe to the mailing list
phplib@shonline.de. Do so by sending a mail body of subscribe
to
phplib-request@shonline.de and follow instructions. Share your
experiences.
include() instead of auto_prepend=
If you do not want to use auto_prepend to load the
PHPLIB core functionality, you can load the class definitions
for the core manually on each page that requires them.
You will have to define a valid
include_path=-statement in your php3.ini file
as outlined previously to reflect the location of the *.inc
files. Then, all core functionality can be loaded with
include("prepend.php3") as the first statement at the top
of each page.
To further optimize performance, you can minimize the contents
of the prepend file, if you do not need all core functionality.
You may leave out auth.inc, perm.inc and
user.inc, if you do not require these features (note that
there are dependencies among these classes!).