Integrating BIRT with PHP

Motivation

BIRT is designed to be integrated into a J2EE web application. But, what if your chosen development environment is something else, such as PHP? Can you still use BIRT? Yes, you can.  This page discusses how to use BIRT from PHP, but the techniques apply to any server-side scripting environment.

It turns out that the Eclipse website itself uses PHP for its web infrastructure. This note explains what the BIRT team discovers as we figure out how to integrate BIRT reporting with the PHP website infrastructure.

Setup

PHP has the ability to call Java classes using a PHP/Java Bridge. So, one integration option is to have the PHP engine call BIRT directly. The scenario is discussed in an article here. The examples associated with the article are posted here.

Another option is to host BIRT on its own app server, such as Tomcat, and use the BIRT Viewer URLs to work with BIRT.

The first step is to install Tomcat and the BIRT viewer. Let's assume that you've set up Tomcat on the same machine as the web server running Apache, and that Tomcat listens on port 8080. Once the setup works, we're ready to focus on the PHP side.

Running a Report

Next step is to run a report from within a PHP script. Let's assume we have a report named test.rptdesign stored in C:/temp. We use a browser redirect to run the report. The redirect appears in an HTML header. Headers must be written before adding any content to the page:

$fname = "c:/temp/test.rptdesign";
// Redirect browser
$dest = "http://localhost:8080/birt-viewer/run?__report=";
$dest .= urlencode( realpath( $fname ) );
header("Location: $dest" );
The name of the report is given as an absolute path, but a relative path is also allowed once you set up the BIRT_VIEWER_REPORT_ROOT configuration variable in the BIRT viewer web app's web.xml file. Be sure to encode the file name for use in a URL.

That's all there is to it!

Passing Parameters

Suppose your report takes parameters. The test report above has one parameter called sample. We simply add them to the report URL in the form described in Using the Report Viewer.

$fname = "c:/temp/test.rptdesign";
$paramValue = "Hi there!";
// Redirect browser
$dest = "http://localhost:8080/birt-viewer/run?__report=";
$dest .= urlencode( realpath( $fname ) );
$dest .= ";sample=" . urlencode( $paramValue );
header("Location: $dest" );
The parameter value must also be encoded when placed into the URL.

Parameter Form

Ideally, we could use PHP to create a UI form that prompts for the report parameters. The BIRT viewer creates this form in Java using information in the report design. Unfortunately, at present, there is no way to retrieve the raw parameter descriptions from the BIRT viewer using a URL. Instead, there are two alternatives we can use.

First, if we know the parameters ahead of time, we can design a custom form in PHP that prompts the user for them. This works if we have a small number of reports, or if we need to create a specialized parameter page for each report anyway.

Second, we can let the BIRT viewer display the parameter page using the frameset URL.

Generating Reports Dynamically

Finally, PHP provides one additional BIRT integration option: the ability to generate report designs dynamically for a specific task. For example, suppose you have a bug tracking system, and you'd like your user to create their own reports via the web. You can ask the user for the columns to display, then use PHP to create a BIRT report design customized to display those columns. PHP is ideal for this: it allows us to insert scripting directly into HTML. Since a BIRT design is XML, and XML is close enough to HTML for PHP, we can "trick" PHP into generating a BIRT report design instead of an HTML page.

To generate a report design, do the following:

  • Create a BIRT report design typical of the kind of report you want to create.
  • Create a PHP template file that contains this design. Insert the contents of the design file in place of the HTML you'd usually put into a PHP file.
  • Redirect PHP's output from the template file into a report design file.
  • Use PHP to generate BIRT XML for the table headings and cells the user wants. Use your report design as a template for what is needed. Consult the ROM spec for details on various elements and properties.
  • Within the data set in your template, create an SQL query that fetches the required columns. (Works with other data set types as well.)
  • Use the code above to redirect the browser to run that report using the BIRT viewer.

The following PHP code redirects the output of a PHP page, template.inc, into a report design called temp.rptdesign:

ob_start( );
require "template.inc";
$page = ob_get_contents( );
ob_end_clean( );
$fw = fopen( "temp.rptdesign", "w" );
fputs( $fw, $page, strlen( $page ) );
fclose( $fw );