Host Web-based Surveys Using phpESP

—by David O’Donnell, atropos@afp548.com

30 October 2002

Although it might not be immediately apparent, surveys can be helpful to Web site hosts, community managers, and more. They are an effective way to gauge interest in a topic, or gather a wide range of information from willing participants. You could spend a significant amount of money to a vendor to host surveys through them, or use an Open Source program like phpESP to develop and host your own surveys.

You will need to enable PHP in Web Service, if you have not already. There are clear directions on how to do it in /etc/httpd/httpd.conf; search on “PHP” in your favourite command line editor to speed the process. Don’t forget to restart Web Service after you do this! You will need access to MySQL to complete this process. If you aren’t familiar with MySQL, I recommend you read Darian Lewis' introductory article first. Then start MySQL using the MySQL Manager application (in /Applications/Utilities). Lastly, obtain and install a GUI-based MySQL manager, like Webmin or phpMyAdmin.

phpESP lets you design, post, and manage multiple surveys. It uses a MySQL database to manage the processes. The first step in installing phpESP is to create a new MySQL database and a new MySQL user, then give the new user access rights to the database. The user will need Select, Insert, Update, and Delete privileges at minimum. I tend to find it easy to remember database information if I make the database and user match the name of the project; make sure to assign the user a good, secure password, however.

Next, obtain a copy of the software. As of publication, phpESP was at version 1.5 RC3; it is close to a 1.5 release, so you should point a Web browser at their site on SourceForge to obtain the latest stable version (I built 1.5 RC3, and it appears stable). Because of the way it’s built, you do not want to decompress phpESP into your Web site directly. The authors recommend decompressing it in /usr/local/lib/php/contrib/phpESP; however, since Apple doesn’t ship PHP in a “standard” configuration, that location doesn’t make a lot of sense. I built my copy at /usr/local/phpesp, but you can place it nearly anywhere you have write access. Keep note of the location, as you will need it later.

Under the decompressed source tree is a directory called images. You will need to symlink the directory to the location on your Server where phpESP will exist. For example, on our test Server, I wanted phpESP to run under the default virtual host, so I symlinked it under /Library/WebServer/Documents/phpESP:

sudo mkdir -p /Library/WebServer/Documents/phpESP 
ln -s /usr/local/phpesp/images /Library/WebServer/Documents/phpESP/phpespimg

The Web server will also need access to the 'public' directory, where surveys are stored:

ln -s /usr/local/phpesp/public /Library/WebServer/Documents/phpESP/public

Next, you will need to edit phpESP’s configuration files. Change to the source directory, then edit admin/phpESP.ini using your favourite command line editor. You will need to change the value of $ESPCONFIG['prefix'] to match the base path to the source tree; using our test example, you would change the value to /usr/local/.

Change the values for $ESPCONFIG['include_path'], $ESPCONFIG['image_path'], $ESPCONFIG['handler'], $ESPCONFIG['handler-prefix'], and $ESPCONFIG['survey_css'] to match your settings.

Set the four database variables (db_host, db_user, db_pass, and db_name) to the values you assigned when creating the phpESP database in MySQL.

Again using your favourite command line editor, modify the path value assigned to $CONFIG in admin/manage.php. This tells phpESP where its initialization file resides. Now, symlink admin/manage.php to where phpESP will live on your Web server, and change its name to index.php. Using the example from our test server, the command would be:

ln -s /usr/local/phpesp/admin/manage.php /Library/WebServer/Documents/phpESP/index.php

You can give this file a different name if you prefer, but as it is the central management function for both administrators and survey managers, I recommend sticking with index.php.

There are three files in the public directory that will need editing: handler-prefix.php, handler.php, and survey.php. Near the top of each file is a require directive that contains the system file path to phpESP.ini; modify the path to match the actual location on your system.

Last but not least, you need to execute the phpESP.sql file within MySQL to set up the initial values within your phpESP database. Use your preferred GUI tool for this, or execute the command at the command line if you are a MySQL master; either way, once that SQL code has been executed, you’re all set up. Point your Web browser at the URL for phpESP and log in as root, password esp. Change the password immediately to prevent unauthorized access, and then you can start adding Survey Manager users, and playing around with Surveys!