-
Notifications
You must be signed in to change notification settings - Fork 235
Tutorial
This is a basic tutorial that will walk you through installing and configuring the Php Reports framework, creating a report, and customizing the appearance of the framework.
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
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.
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.
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"}
$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.
To use MySQL or MongoDB reports, you first need to define some database connection info in your config file. Edit config/config.php and add the following if it's not there already:
return array(
//...
'environments'=> array(
'main'=>array(
'mysql'=>array(
'host'=>'localhost',
'user'=>'root',
'database'=>'mydatabase'
),
'mongo'=>array(
'host'=>'localhost',
'port'=>'27017'
),
),
),
//...
);You can define multiple environments that all have their own database connection info. This is useful if you want to run the same set of reports on both a production database and a dev database. There is a drop down menu on reports that let you switch between environments.
Create the file reports/my-reports/timezones.sql and add the following contents:
-- Timezone List (MySQL)
-- This lists all timezone abbreviations in a given timezone
-- VARIABLE: {name: "timezone", display: "Choose a Timezone"}
SELECT * FROM Timezones WHERE Timezone="{{ timezone }}";Headers are almost identical. The only difference is that they use the SQL comment style "-- " instead of "//". You can have multiple SQL statements separated by semicolons if needed. Only the result of the last query will be used in the report. This is useful for creating temp tables or setting variables.
The SQL queries are parsed with the Twig templating language before being executed, so "{{ timezone }}" will be replaced with the variable "timezone". You can also use conditionals, for loops, or any other Twig construct if you want.
Create the file reports/my-reports/timezones.js and add the following contents:
//Timezone List (MongoDB)
//This lists all timezone abbreviations in a given timezone
//VARIABLE: {name: "timezone", display: "Choose a Timezone"}
//MONGODATABASE: {database: "MyDatabase"}
printjson(db.Timezones.find({"timezone": timezone}));MongoDB reports are passed into the shell. You can add a MONGODATABASE header to pre-populate the "db" variable in your report.
All variables from the VARIABLE headers will be defined in the shell before the report is run.