The Quick Start chapter tries to give you a ten-minute introduction to PHPLIB installation, outlines a few simple testing procedures and closes with an overview of PHPLIB features.
PHPLIB targets the PHP application developer. You need to have good knowledge of the PHP language, at least basic SQL database knowhow and at least basic knowledge on how to operate your web server to be able to use the library.
The library will help you to write medium to large sized data-driven web applications. "Medium to large sized applications" are applications that consist of multiple database queries, have to generate tables from database data, need a user interface that generates SQL queries or need a comfortable and user-friendly way to protect pages or functionality on pages. "Data-driven" applications are applications that make use of a supported SQL-database to create HTML content and that use HTML forms to drive database transactions.
To make use of the library you obviously need access to a web
server with a working installation of a current PHP interpreter
(we recommend 3.0.5 or newer for this release of the library)
and access
to a supported SQL database (currently, PHPLIB supports MySQL,
PostgreSQL, Oracle and ODBC databases). You need to be able to
create and drop database tables in that database and your web
server must be able to execute SELECT
, INSERT
,
UPDATE
and DELETE
statements on these tables.
Throughout this manual, we assume that you are using the MySQL database server. PHPLIB will run with any supported SQL server, but we are using MySQL in the development of PHPLIB.
PHPLIB can be used in conjunction with the CGI version of PHP and
with mod_php
, integrated into Apache. Usage of the CGI
version has an impact on overall speed, because you cannot take
advantage of persistent database connection. We recommend
the Apache module over the CGI version.
Before installing PHPLIB, get your web server up and running and
have it executing files with the extension .php3. Check that
with a simple <?php phpinfo() ?>
script. Make sure
the web server accepts index.php3
as well as index.html
as a default file for URLs ending in "/" (Apache:
DirectoryIndex index.html index.php3
).
Get your MySQL database server up an running. Create an empty
database for your application and make sure the owner of your
web server processes can access this database with SELECT
,
INSERT
, UPDATE
and DELETE
access. Don't forget
the mysqladmin reload
after changing the user and db tables.
Create an include directory named php
parallel to your
web servers document root directory.
Unpack your PHPLIB distribution. Move the contents of the
php
distribution directory into the php
directory
you just created.
Get to the php3.ini
file for your web servers PHP
interpreter and update the include_path
statement so
that it points to that php
directory. Update the
auto_prepend
statement so that it points to the
prepend.php3
file in that include directory.
Also check that track_vars
are enabled and that you have
enabled magic_quotes_gpc
. While you are at it, you might
want to check sendmail_path
, if you plan to send mail from
your application. It has to be set to /usr/lib/sendmail -t
on most UNIX systems to work.
cd into the php
include directory. Edit local.inc
.
In class DB_Poe
supply the appropriate parameters for
your database connection.
For this database, run create_database.mysql
from the
distribution to create active_sessions
and
auth_user
. auth_user
will be populated with a
sample user named kris
with a password test
.
Move the contents of the pages
directory and all its
subdirectories into your document root directory.
Access the "/" URL of your web server with cookies enabled. If
no index.html
is present, index.php3
will be displayed.
If you reload that page, the number shown must increment.
Access your database with the mysql command client and select
* from active_sessions
. Check that there is a single session
record for your browser and see how the text in val
changes when you reload the page and select * from
active_sessions
again. If this works, the session class is
functional with cookie mode.
Now access showoff.php3
. Try to login as kris
,
password test
. Check active_sessions
again. You now
should have a Poe_Session
entry (see the name
column) and a Poe_User
entry in your table. Both should
increment on reload.
Try again with cookies disabled. You should get a new session (the cookie is lost) and you should be able to see your session id as the get parameter part of your URL.
Many applications don't use PHPLIB's advanced features, but see PHPLIB as a convenient way to protect pages or functionality with passwords. This section covers such core functionality usage of PHPLIB.
Edit loginform.ihtml
in the include directory to suit
your needs.
Edit local.inc
and change the class Poe_Perm
to
enumerate your permissions. Your users in auth_user
must
have one or more comma separated permission names from that
list. Edit perminvalid.ihtml
for a suitable error message.
Use new_user.php3
from the pages/admin
directory
of the distribution. If you followed the installation
instructions, it should be available under the
/admin
URL of your web server.
To manually create a user, run print md5(uniqid("some magic
string")
to get a user id. insert into auth_user values (
"that userid", "username", "password", "permissions");
.
Begin that page with
<?php page_open(array("sess" => "Poe_Session")); ?>
End that page with
<?php page_close(); ?>
Begin that page with
<?php
page_open(
array("sess" => "Poe_Session",
"auth" => "Poe_Auth",
"perm" => "Poe_Perm"));
$perm->check("desired protection");
?>
and end that page with
<?php page_close(); ?>
Begin that page with
<?php
page_open(
array("sess" => "Poe_Session",
"auth" => "Poe_Auth",
"perm" => "Poe_Perm"));
?>
and end that page with
<?php page_close(); ?>
Enclose the protected functionality in
<?php
if ($perm->have_perm("desired protection")):
?>
Put protected HTML or PHP here
<?php
endif
?>
Note: desired protection
is any combination of
permissions from Poe_Perm
. Using the default values from
Poe_Perm, "user
", "user,author
" or "admin
" are all
valid sample values. A user can access a page, if that user has
all permissions that are being requested in a
$perm->check() or $perm->have_perm() call.
Note: Users can have multiple permission in their perms
column of auth_user
. A user with perms
"user,author,editor
" can access all pages requesting any
combination of these permissions.
Note: Don't use spaces. "user,author,editor
" works.
"user, author, editor
" does not.
Note: If $auth->auth["uid"]
is set on a protected
page and if (time < auth->auth["exp"])
, then and
only then the authentication is valid. You may then use
$auth->auth["uname"]
as the user name,
$auth->auth["uid"]
as a unique user id and
$auth->auth["perm"]
for the current permissions of that
user. Actually, you never want to touch
$auth->auth["perm"]
manually, but use
$perm->have_perm("...")
for that.
Read on. Then read the source. Read it again - Session->serialize() and Auth->start() are ugly. Get a CVS account. Contribute. Become famous. Buy a ferrari.
Note: You want to understand what registered variables are. You want to understand in what order form variables and session variables are imported into your page. You want to understand how to copy values from form values into session values without killing yourself. You do not want to make form variables persistent, ever. Then you will live happily thereafter...
This section offers an incremental approach to find installation problems, should the above installation process fail.
Make sure your web server is up and serving the virtual host you
just set up. To do this, construct a small file test1.html
in your DocumentRoot and access test1.html
through your
web server.
Make sure your web server is up and does run CGI. Check the current directory, the UID/GID it is running programs under and have a look at the environment variables. Install the shell script
#! /bin/sh --
echo "Content-Type: text/plain"
echo
id
echo
pwd
echo
env | sort
echo
in your cgi directory under the name of cgi-test
and in
your document root under the name of cgi-test.cgi
. Make it
executable. Try to access
/cgi/cgi-test?par1=one&par2=two
and
/cgi-test.cgi?par1=one&par2=two
and check the
output. What UID/GID are you running under, what is the output
of pwd
and what environment variables are set? What does
QUERY_STRING
look like? What does the PATH
variable look like, what does the
LD_LIBRARY_PATH
variable look like and are
all libraries needed by PHP accessible to PHP running in the CGI
environment (Check by running the Unix ldd
command on PHP).
In particular, if you built Oracle support into PHP and linked
libclntsh
dynamically: Can it be loaded from the CGI environment? If
not, PHP will not come up later in the next step.
Copy your PHP binary into the cgi binary directory (which should
NOT be below DocumentRoot!) and make it executable. Copy
php3.ini
into the same directory. In DocumentRoot, create a
test2.php3
and put <?php phpinfo() ?> into it.
Are you running Apache? Add
Action php3-script /cgi/php
AddHandler php3-script .php3
DirectoryIndex index.php3 index.html index.htm
FancyIndexing on
to your config. This will map all requests to files ending in
.php3
to the php3-script
handler and define
/cgi/php
as the URL handling php3-script
requests
internally.
Request /test2.php3
and see that it is being executed.
Make changes to your php3.ini
(preferable some color
definitions) and reload. Are they reflected in the output of
phpinfo()
? If not, your php3.ini
is not being found
and your are having a problem. Recompile with proper settings.
Check the output of phpinfo()
carefully! Is your PHP
version current (We have tested and developed this release with
PHP 3.0.5)? Are your database interfaces present in the output
of phpinfo()
? If not, recompile again.
Can you access /test2.php3
under the URL
/cgi/php/test2.php3
as well? If so, you did not compile
your PHP interpreter with --enable-force-cgi-redirect
.
PHPLIB will not work with this interpreter. Recompile with the
switch being set.
Assuming your server is already correctly setup
(don't forget to activate the PHP lines in srm.conf
!),
enter the following file and save it as test2.php3
under your DocumentRoot.
<? phpinfo() ?>
If you access this using a web browser now, it should spit out much info about PHP, Apache and its environment.
Does you PHP include PHPLIB properly? Check your
php3.ini
file. It must include the following settings:
include_path = <em/pathname to directory with all the .inc files/
auto_prepend_file = <em/path to prepend.php3/
track_vars = On
It should contain the following settings, too:
magic_quotes_gpc = On
If PHPLIB is included properly by your setup, the following page will execute without errors:
<?php
$db = new DB_Sql;
?>
PHPLIB installation requires that you adapt local.inc
properly. Particularly, the provided class DB_Poe
must be
customized for your database connection. Test that your
web server can access the database with the following page:
<?php
include("table.inc"); // requires include_path to be functioning
$db = new DB_Poe;
$db->query("select * from active_sessions");
$t->heading = "on";
$t->show_result($db);
?>
When executing properly, this page will show you the user entry
for kris
, password test
, permissions admin
from
the auth_user
table. If this does not happen, your
DB_Poe
definition in local.inc
is broken.
Access the page /index.php3
that has been provided
with the distribution. This page will try to set a cookie in
your browser. Allow that cookie to be set.
The page will display a headline with a counter. Reload that
page. The counter must increment. If not, either your browser
cannot deal properly with cookies or PHPLIB cannot properly read
or write the table active_sessions
in your database. Check
that the cookie is being set by viewing the output of
phpinfo()
(the fourth table will report the cookie and
other per-call data). Check your database permissions with your
database command line interface.
Try loading /showoff.php3
that has been provided
with the distribution. This page will require a login. Login as
kris
, using a password of test
. If the login is
successful, you will see the per-session counter and a per-user
counter again. Reload that page: The counters must increment.
If you can't login, you probably have a problem with cookies.
Check again that your browser accepts and sends session cookies.
Another problem may be access to the auth_user
table. You
must be able to SELECT
on that table and there must be at
an entry for the user you are trying to login.