Tutorial

This is a basic tutorial that will walk you through installing and configuring the Php Reports framework, creating a few reports, and doing some customizations.

Download Files

The easiest way to get the source files is through git. Clone the repository in your document root.

git clone git://github.com/jdorn/php-reports.git
cd php-reports
git submodule init
git submodule update

The Php Reports framework uses Flight for url rewriting. An .htaccess file is included by default, but Flight also supports Nginx. See instructions here: http://flightphp.com/install

Set Configuration Options

Use the sample configuration file as a template for creating your own.

cp config/config.php.sample config/config.php

The sample configuration file has lots of comments and should be pretty self explanatory. For this tutorial, we will make our own reports folder instead of using the sample one. Change the 'reportDir' option as follows:

return array(
//...
    'reportDir'=>'reports',
//...
);

Next, create the reports directory.

mkdir reports

Now we are ready to start creating reports.

Create Your First Report

Reports are organized in directories. If a directory contains a TITLE.txt file, it will show up in the table of contents. Report directories can also contain a README.txt file that has a short description of the directory. Let's create a report directory called "My Reports".

mkdir reports/my-reports
echo "My Reports" > reports/my-reports/TITLE.txt

To make things easy, we're going to start with a php report (vs. Mysql or Mongo). This way, we don't have to worry about setting up databases just yet.

Create the file reports/my-reports/timezones.php and add the following contents:

<?php
//Timezone List
//This lists all timezone abbreviations in CDT

//The empty line directly above this denotes the end of the header section
//and the start of the report
$timezones = DateTimeZone::listAbbreviations();
echo json_encode($timezones['cdt']);

The DateTimeZone::listAbbreviations() function is built-in to PHP and is just a quick way to get some data we can view. You can see the documentation for this function at http://www.php.net/manual/en/datetimezone.listabbreviations.php

Now, pull up the reports framework in a browser. http://localhost/php-reports/

You should see the main report list page. This page organizes and lists all your reports. When you start getting a lot of reports, you can utilize the table of contents and the report search functionality.

Click on the "Timezone List" report you just created to run it and view the output. As you can see, the report page has several elements:

• Title and description
• A database environment switcher
• Export to CSV link
• The actual report contents
• A "show query" link at the bottom that is useful for debugging.

You can filter the report by typing in the search box and sort by clicking on the column headers.

Adding Headers to a Report

A report can have special Headers that change the report appearance, add configurable parameters, display charts and graphs, etc. This is where the real power of the Php Reports framework lies.

Let's start by adding a configurable variable to our report.

<?php
//Timezone List
//This lists all timezone abbreviations in a given timezone
//VARIABLE: {name: "timezone", display: "Choose a Timezone"}

//The empty line directly above this denotes the end of the header section
//and the start of the report
$timezones = DateTimeZone::listAbbreviations();

//All VARIABLE headers are defined in php before running the report
//so we can use $timezone and it will contain the user entered value

//if an error occurs, you can throw an exception and it will be shown to the user
if(!isset($timezones[$timezone])) {
        throw new Exception("Invalid time zone");
}

echo json_encode($timezones[$timezone]);

Now, when you try to run the report, it will prompt you for a timezone to choose. Try entering "adt" for a valid timezone or "abcdefg" for an invalid one.

There are a bunch of pre-defined headers you can use. Check out the Report Headers wiki page for full documentation.

Customizing Appearance

Customizing the appearance of the Php Reports framework is easy due to the Twig templating engine.

Everything that is output to the screen is rendered by Twig and completely customizable. All of the default templates are located in templates/default. Anything you place in templates/local will be used instead of the default one.

Most templates define one or more blocks that can be over-ridden individually. This provides tremendous flexibility while also allowing you to update the core framework without worrying about overwriting local changes.

Let's start by changing the "Configure Report" title in the variable form. It often helps to look at the default template and see what blocks are available to override. The default template for the variable form is located at templates/default/html/variable_form.twig. It contains the following:

<form method='get' id='variable_form'>
	{% block variable_form_title %}
	<h2>Configure Report</h2>
	{% endblock %}
	
	<input type='hidden' name='report' value='{{report}}' />
	...

While you are free to replace the entire variable_form.twig file with a local version, it's often easier to extend the default template and just modify the blocks that you want.

Create the file templates/local/html/variable_form.twig and put in the following contents:

{% extends "default/html/variable_form.twig" %}

{% block variable_form_title %}
<h2>Report Configuration</h2>
{% endblock %}

Now, just refresh the report to see your changes take effect.

If you want to add extra css or javascript files to every page, create the file templates/local/html/page.twig and put in the following contents:

{% extends "default/html/page.twig" %}

{% block stylesheets %}
    {{ parent() }}
    <link rel='stylesheet' href='{{base}}/public/css/custom_styles.css' />
{% endblock %}

{% block javascripts %}
    {{ parent() }}
    <script src='{{base}}/public/js/custom_javascript.js'></script>
{% endblock %}

The "{{ parent() }}" tag will render everything in the default block. The "{{base}}" variable contains the root url of the report framework. It is important to always prefix internal links with "{{base}}" so your links don't break if you install in a subdirectory.

To find out more about Twig, check out their excellent documentation.