BrowserHawk PHP - Installation and Usage Guide

The following document explains how to install and use BrowserHawk for PHP.
For background information on what BrowserHawk is and what it does, see
http://www.cyscape.com/products/bhawk


Introduction
------------

BrowserHawk for PHP enables you to harness the full power of the BrowserHawk4J
(BH4J) Java library directly and seamlessly from your PHP environment, even
though BH4J runs within a Java environment.

This is accomplished by leveraging the open source "PHP/Java Bridge" to connect
your PHP environment to the Java environment where BH4J resides.  The Bridge
exposes BH4J's classes and methods directly your PHP environment, like so:

[browser] <--> [Web server w/PHP] <--> [PHP/Java Bridge] <--> [BH4J in Java env]


Once BH4J and the Bridge are configured on your server, you can natively use
BH4J from any PHP page simply by referencing the browserhawk.php library file
from your PHP page.

The browserhawk.php library file manages communication between BH4J and the
PHP environment.  It exposes to PHP several variables and functions helpful in
communicating with BH4J:

$info
  An instance of the BrowserInfo class, exposing statically determinable
  features about the client browser.

$options
  An instance of the ExtendedOptions class, used to configure extended
  property detection.

bhextended($options)
  A function call that returns an ExtendedBrowserInfo object, built using the
  options specified by $options.

$UNSUPPORTED
  A particular ExtendedBrowserInfo object, returned when the client browser
  does not support extended detection (such as web crawlers or mobile devices).

$BrowserHawk
  A reference to the BrowserHawk class instance, used for calling static
  methods on the class.

boolprint($var)
  A utility function for printing boolean values that prints as "true" or
  "false", rather than PHP's normal "1" or "".

The examples directory shows these variables and functions in use.



Necessary files
---------------

The following libraries will be required for installation.  We'll walk you
through the installation of each.

* A PHP engine, version 4.3.2 or later
* A Java runtime, version 1.2 or later
* The PHP/Java Bridge, version 3.0.8 EXACTLY
* BrowserHawk4J, version 9.01 or later


Installing PHP
--------------

Many Unix systems come with PHP pre-installed.  Those that don't often have
distribution-specific mechanisms to install PHP (fink, yum, rpm, etc).  We
recommend you install PHP in whatever way is customary for your system.

If you need to download PHP for Windows or want the latest PHP release, you
can find distributions and instructions from http://www.php.net/downloads.php.

You need PHP 4.3.2 or later.  Running "php -version" will tell you the version
you have.


Installing Java
---------------

As with PHP, many systems also come with Java pre-installed, and those that
don't often have distribution-specific mechanisms to install Java.  We
recommend you install Java in whatever way is customary for your system.

If you need to download Java or want the latest Java release, you can find
installers from http://java.com.

You need Java 1.2 or later.  Running "java -version" will tell you the Java
version you have installed.  We do not recommend using the GNU Java runtime,
as it's not a supported Java platform for BrowserHawk4J.  Make note of your
Java install location; you'll need it later.


Installing the PHP/Java Bridge
------------------------------

The next step is to download and install the PHP/Java Bridge.  The PHP/Java
Bridge itself is an open source project from SourceForge.net.  You should be
sure to download the 3.0.8 release.  Later versions are not recommended.
Links to the project home page, project page, and 3.0.8 download pages:
  http://php-java-bridge.sourceforge.net/
  http://sourceforge.net/projects/php-java-bridge/
  http://sourceforge.net/project/showfiles.php?group_id=117793&package_id=170256&release_id=402825
  http://sourceforge.net/project/showfiles.php?group_id=117793&package_id=128366&release_id=402826

The PHP/Java Bridge can operate in five different modes, as explained in its
Overview document.  We recommend deploying in Mode #3, standalone, for best
performance and reliability:

 "3. Permanently activated in the global php.ini file with an external Java
 process. Recommended for production systems. This mode is used by the RPM
 package available for Red Hat Enterprise Linux. In this mode the bridge
 starts and stops as a system service."

To setup for Mode #3, you'll need to download the "standalone" binary as well
as the main PHP/Java Bridge binary, as explained in the platform-specific
install instructions above, and the special notes below.


Notes for PHP/Java Bridge Users under Linux
-------------------------------------------

The INSTALL.LINUX instructions (included with the bridge download) provide the
details of getting the bridge to work under Linux.  Pay particular attention
to the beginning of the file and the "Standalone back-end" section.

Here are some helpful instructions, to supplement those found in INSTALL.LINUX:

1)  To install using Mode #3, you will need to install the Bridge and the
standalone library, using commands like this:

  sudo rpm -i php-java-bridge-3.0.8-1.*.i386.rpm
  sudo rpm -i php-java-bridge-standalone-3.0.8-1.*i386.rpm

Notice the wildcard on the first line.  There are three different RPMs
available, depending on your PHP version.  Install only the appropriate RPM.

  For PHP >= 4.3.2:         php-java-bridge-3.0.8-1.RHEL.i386.rpm
  For PHP >= 5.0.x:         php-java-bridge-3.0.8-1.FC4.i386.rpm
  For PHP >= 5.1.x or 6.x:  php-java-bridge-3.0.8-1.FC5.i386.rpm

Note the wildcard on the second line.  There are two different RPMs available,
again depending on your PHP version.  Install only the appropriate RPM.

  For PHP >= 4.3.2:         php-java-bridge-standalone-3.0.8-1.RHEL.i386.rpm
  For PHP >= 5.0.x:         php-java-bridge-standalone-3.0.8-1.i386.rpm
  For PHP >= 5.1.x or 6.x:  php-java-bridge-standalone-3.0.8-1.i386.rpm

2)  Then you'll need to restart Apache and start the Bridge, using commands
like this:

  sudo /etc/init.d/httpd restart
  sudo /etc/init.d/php-java-bridge restart

Note that the official instructions don't mention the need to start the
bridge.

3)  Edit the /etc/php.d/java-standalone.ini file to configure the
"java.java_home" property to point at your Java runtime directory and the
"java.java" property to point at your Java runtime binary.  Example:

  java.java_home = /usr/local/java
  java.java = /usr/local/java/bin/java

Now testing can be done on the Bridge.

4) Copy the test.php provided with the Bridge installation to the web server
document root (the path from which your web server serves files).

5) Open the test.php file in your browser of choice.  A display of PHP's
information should display with some information about the Bridge afterward.
If this does not display, consult the INSTALL.LINUX file for suggestions on
troubleshooting.

Do not proceed until confirming success with test.php.


Notes for PHP/Java Bridge Users under Windows
---------------------------------------------

The INSTALL.WINDOWS instructions (provided with the bridge download) explain
the details of getting the bridge to work on Windows.  Pay particular
attention to the sections that assume standalone use (with Mode #3 you don't
need to worry about the servlet engine deployment details).

NOTE: the Bridge will be installed into PHP's extension directory, which is
set in the php.ini configuration file via:

  extension_dir = <php-extension-path>

If the path specified includes a space, a new path will need to be created in
which the extensions can be placed.  This is due to the Java Bridge not
reading past whitespace in the path specified by extension_dir.

For example, if PHP is installed at C:\Program Files\xampp\php\ext\ the 
Bridge will not work.  Creating C:\php\ext, setting
extension_dir="C:/php/ext/" in php.ini, and copying all of the extensions from
the old path to the new one will solve this problem.

Here are some helpful instructions, to supplement those found in 
INSTALL.WINDOWS:

1) Extract the contents of php-java-bridge_3.0.8_j2ee.zip, and locate/extract
the file JavaBridge.war to a temporary location.

2) Rename JavaBridge.war to JavaBridge.zip and extract the contents to the
temporary location (<temp>).

3) The appropriate DLL must be copied to the PHP extension directory
(<php-extension-path>).  The DLLs can be found in <temp>\WEB-INF\cgi .  From
the Bridge documentation:

  for PHP >= 4.3.4: php-4-java-x86-windows.dll
  for PHP >= 5.0.0: php-5.0-java-x86-windows.dll
  for PHP >= 5.1.0: java-x86-windows.dll
  for PHP >= 6.0.0: php-6-java-x86-windows.dll

4) Copy the DLL determined in the previous step to your PHP extension
directory and rename it to php_java.dll.  NOTE: this file may already exist.
For BrowserHawk to work, the Java Bridge needs to be the only Java extension
and should thus replace the older php_java.dll file.

5) Copy <temp>\WEB-INF\lib\JavaBridge.jar to <php-extension-path>.

6) Create the directory <php-extension-path>\lib .  Copy the contents of
<temp>\WEB-INF\lib\ to <php-extension-path>\lib\ and remove the JavaBridge.jar
file from the target directory.

These changes now need to be reflected in php.ini.  The following steps should
be made in your php.ini file.

7) Do a search for "extension=php_java.dll".  If the line exists, make sure
it is uncommented.  If it does not exist, add the line to your php.ini file,
preferably close to where the other extensions are.

8) The following java settings need to be in the php.ini file:

[java]
java.log_level = 2
	
Do a search for "[java]".  If the string exists, change the settings to appear
as above.  If it does not exist, insert the above in the "Module Settings"
section of the file.

9) Save and close.

10) Restart the web server for the changes to take effect.

Once the web server has been restarted, testing can be done on the Bridge.

11) Copy test.php found in <temp> to a location that the web server can load
and serve.

12) Open the test.php file in your browser of choice.  A display of PHP's
information should display with some information about the Bridge afterward.
If this does not display, consult the INSTALL.WINDOWS file for suggestions on
troubleshooting.

Do not proceed until confirming success with test.php.


Installing BrowserHawk4J (Standalone: Without a Servlet Engine)
---------------------------------------------------------------

The following instructions will setup BrowserHawk4J to run outside of a Java
servlet engine, in support of your PHP environment.  This installation should
be easier than installing the Bridge.

1) Extract the BrowserHawk4J ZIP to a temporary location (<temp>).  (You have
already done this to be reading this file.)

2) Determine your <php-extension-path>/lib directory.  Under Linux it's
/usr/lib/php/modules/lib.  Under Windows you selected it, perhaps as
"C:\php\ext\lib".  Copy the following files to the <php-extension-path>/lib
directory:

<temp>/webapps/bhawk/WEB-INF/classes/bhawk_bb.dat
<temp>/webapps/bhawk/WEB-INF/classes/bhawk_sp.dat
<temp>/webapps/bhawk/WEB-INF/classes/browserhawk.properties
<temp>/webapps/bhawk/WEB-INF/classes/maindefs.bdd
<temp>/webapps/bhawk/WEB-INF/lib/bhawk4j.jar
<temp>/webapps/bhawk/webfiles/servlet-api.jar

3) Locate your BrowserHawk license key file and copy that to
<php-extension-path>/lib as well.  You may need to edit browserhawk.properties
and configure the "license.file" property to point at your license key file.

4) With all of these files in place, restart the web server for BrowserHawk
to be accessible via the Bridge.


Running BrowserHawk Examples with PHP
-------------------------------------

The BrowserHawk distribution includes several PHP example files under
<temp>/webapps/bhawk/php.  You should now install these to test your
BrowserHawk setup:

1) Create a directory (e.g. bhawk) in your web server document root (the path
from which your web server serves files).

2) Copy all of the files in <temp>/webapps/bhawk/php to the path created in
the previous step.

3) Point your browser of choice to the URL that resolves to the directory
previously created.  It should display the index.html table of contents page.
From there you'll be able to run through all of the tests off of the main
page.

NOTE: The BH for PHP samples are well documented and serve as a great learning
aid.  View their source code to easily see how things work under the hood.

NOTE: To detect Java, the file JVMDetector.class needs to be in the same
directory as the file that uses it (for example, the java.php page used for
testing).  This file is included with the PHP examples for your convenience.
You can also call $options->setJVMCodeBase() if you want to use a global
JVMDetector.class file.

NOTE: By default PHP does not display errors within the page, and you may see
empty pages when you hit problems.  You can turn on errors by adjusting the
php.ini configuration file "display_errors" flag to "On", or you can just view
the error information in your server's error log.


Writing Your Own PHP Pages
--------------------------

When writing your own PHP files, you may want to copy one of the pre-existing
PHP sample files as a starting point.  If you're doing only basic detection,
such as checking the browser type, version, and platform, we suggest starting
with basics.php.  For extended detection, such as detecting disabled settings,
screen size, connection speed, and plug-in detection, start with popular.php
and make particular note of the optional cache token feature.

The browserhawk.php file is a PHP/Java Bridge support file, provided for you
to import and make calls to, but not modify.  Even if you don't start with the
PHP example scripts, at a minimum you'll need to add a "require" statement to
your PHP page which references the browserhawk.php library, like so:
   require 'browserhawk.php';

Last tip: When performing extended detection, don't forget that unless you've
turned on output buffering, you'll want to start your php block as the very
first thing in the file and call bhextended() from within that first block.


License notice
--------------

BrowserHawk for PHP is provided under the terms and conditions of the
BrowserHawk4J End User License Agreement (EULA), included in this distribution
in the license.txt file.  Your use of this software in any way constitutes your
full and unconditional acceptance of the terms and conditions of the EULA. If
you do not agree to these terms you must immediately cease use of the software
and remove it permanently from your system.

Copyright (c) 2006 cyScape, Inc. All rights reserved. http://www.cyscape.com

<end>
