Table of Contents

## Using the Automated Installer

For easy installation, use the graphical web-based installer.

1. Make sure you have PHP 4.0.6 or later installed, with sessions properly configured, and your database userid and password ready.

2. Unpack the files into a directory in your webserver, say /htdocs/phplens.

3. Point your web browser to phplens/installer/index.php and follow the instructions.

## Upgrading phpLens

To upgrade phpLens

1. First backup the previous version of phpLens by renaming the directory to phplens.old (or some similar name).

2. Unpack the new version of phpLens into the phplens directory.

3. Copy the following from the phplens.old backup:
   a. All files in the directory phplens.old/config to phplens/config.
   b. The applets in phplens.old/builder/applets/objs to phplens/builder/applets/objs.

## Manual Installation

If you prefer to setup manually, use the following instructions instead:

1. These instructions assume that you are familiar with setting up your Web server, have access to a database such as MySQL, and you know how to install and code in PHP.

2. You need PHP 4.0.6 or later and the free Zend Optimizer installed.

3. To check whether the Optimizer is available, create a test.php file on your server with the following script:

           <?php phpinfo();?>

   Run the script from your Web browser and check the output of test.php for the version number of PHP that the Zend Optimizer is installed. The following picture shows you what to search for:

4. Make sure you have PHP4 sessions enabled. Check in the above phpinfo() output for the string `Session Support` and see if it is enabled.

5. Unpack and move all the files so that you can access the files from `http://yourserver/php/phplens`. This means the phplens-*.inc.php files are in this directory. Make sure that that if you are using unzip or ftp that you use the binary safe mode otherwise the Zend encoded .php files will be corrupted.

6. Create a database called phplens and then use the phplens.sql script to create the required tables. For Microsoft SQL Server use the mssql.sql file instead of phplens.sql.
   MySQL instructions. PostgreSQL instructions. Oracle oci8 instructions.

7. Rename phplens/config/sample-phplens.config.inc.php to phplens/config/phplens.config.inc.php, then modify the file contents to match the above phplens database settings. This means modifying all the PHPLENS_SESS_* variables. Some examples.

   Make sure that PHPLENS_PATH (in .inc.php) is set to URL path to the phplens directory (without trailing /). Eg:

           $PHPLENS_PATH = "/php/phplens";

8. To test phpLens try testphplens.php. Also see debugging below. If this file is not found, try testtext.php, which is old name of this file.

9. Try the Grid Builder. With the Grid Builder you can quickly create a data grid for browsing and editing with a few mouse-clicks and then generate all the required PHP source code. Paste the code into a .php file and you have a working data grid. This is great time saver because no typing is required!

   Read the Grid Builder setup instructions to add more databases to the Grid Builder. The Grid Builder also has a SQL query tool included.

## Debugging your Installation

We provide three debugging scripts:

- testzendopt.php is an encoded file that tests whether the Zend Optimizer is working correctly, running phpinfo() (see testzendopt.src.php for source).
- testconfig.php tests to see if phplens.config.inc.php is properly setup. You can view the source code of this file.
- testphplens.php tests to see if you can run phplens using the text driver. You can view the source code of this file.

### MySQL Instructions

You can place the phpLens tables in an existing database or create a new database from the command line (assuming that MySQL is on localhost) with:

    	mysqladmin create phplens

This will create a database named "phplens".

Create the phpLens table using the supplied phplens.sql file from the command line:

    	mysql phplens < phplens.sql

where "phplens" is the name of your database. This completes the MySQL part of the installation.

### PostgreSQL Instructions

You can place the phpLens tables in an existing database or create a new database from psql with:

    	create database phplens;
    	\c phplens
    	\i phplens.sql
    	\q

You might need to set the permissions of the tables using `GRANT ALL ON "phplens", "sessions" TO public`.

This completes the PostgreSQL part of the installation.

### Oracle Oci8 Instructions

Create the phpLens table using the supplied oracle.sql file from the command line:

    	sqlplus scott/tiger@connectstring
    	start /path/to/phplens/oracle.sql
    	quit

This completes the Oracle part of the installation.

### Access Instructions

Create the phplens table using the supplied access.sql file. From Microsoft Access, open the database you will be using and create a new SQL query with access.sql. After saving the query, execute the query to create the table. Alternately, use the Table Wizard to create an equivalent table.

### Sample PHPLENS_SESS_* Settings

When you use dynamic editing, we need to save your configuration changes in a database. We store these changes in the phplens table you created in the supplied phplens.sql file. The connection settings to connect to your database are set in the following variables in phplens.config.inc.php:

Access (using ODBC) example:

    	$PHPLENS_SESSION_DRIVER='access'; // access odbc driver
    	$PHPLENS_SESSION_CONNECT='system_DSN_name';
    	$PHPLENS_SESSION_USER ='';
    	$PHPLENS_SESSION_PWD ='';
    	$PHPLENS_SESSION_DB =''; // not used

Microsoft SQL Server example:

    	$PHPLENS_SESSION_DRIVER='mssql';
    	$PHPLENS_SESSION_CONNECT='mangrove';
    	$PHPLENS_SESSION_USER ='sa';
    	$PHPLENS_SESSION_PWD ='secret';
    	$PHPLENS_SESSION_DB ='phplens_db';

MySql example:

    	$PHPLENS_SESSION_DRIVER='mysql';
    	$PHPLENS_SESSION_CONNECT='mangrove';
    	$PHPLENS_SESSION_USER ='root';
    	$PHPLENS_SESSION_PWD ='secret';
    	$PHPLENS_SESSION_DB ='lensdb';

Postgres example:

    	$PHPLENS_SESSION_DRIVER='postgres';
    	$PHPLENS_SESSION_CONNECT='mangrove';
    	$PHPLENS_SESSION_USER ='root';
    	$PHPLENS_SESSION_PWD ='secret';
    	$PHPLENS_SESSION_DB ='pglens';

Generic ODBC example:

    	$PHPLENS_SESSION_DRIVER='odbc';
    	$PHPLENS_SESSION_CONNECT='system_DSN_name';
    	$PHPLENS_SESSION_USER ='root';
    	$PHPLENS_SESSION_PWD ='secret';
    	$PHPLENS_SESSION_DB =''; // not used

Oracle Oci8 example 1:

    	$PHPLENS_SESSION_DRIVER='oci8';
    	$PHPLENS_SESSION_CONNECT='';
    	$PHPLENS_SESSION_USER ='scott';
    	$PHPLENS_SESSION_PWD ='tiger';
    	$PHPLENS_SESSION_DB ='tnsname'; // TNSNAMES.ORA entry

Oracle Oci8 example 2:

    	$PHPLENS_SESSION_DRIVER='oci8';
    	$PHPLENS_SESSION_CONNECT='192.168.0.10'; // ip address of rdbms
    	$PHPLENS_SESSION_USER ='scott';
    	$PHPLENS_SESSION_PWD ='tiger';
    	$PHPLENS_SESSION_DB ='dbname'; // database name