Life Cycle

Overview #

When we use the any tool in the real world, we feel more confident if we understand how that tool works. A report development is no different. When you understand how KoolReport Framework functions, you feel more comfortable and confident using it.

The goal of this document is to give you high-level of overview of how KoolReport framework works. By getting to know the overall framework better, everything feels less "magical", you feel more confident to write your data report. If you don't understand right away, no worries, don't lose heart! Just keen on getting the basic of what's going on, you knowledge will grow as you explore other sections of documentation.

KoolReport Life Cycle

Initiation #

A report is actually a PHP class representing the report. We initiate the report by creating object of report's class. When the report object is created, it receives parameters to initiate. For example a SaleReport may need startTime and endTime.

$report = new SaleReport(array(
    "startDate"=>"2017-01-01",
    "endDate"=>"2018-01-01"
));

During the initiation, your report will load report settings, initiate report's services and setup the data processing tree.

Load Settings #

First, your report will call settings() method to get necessary settings of report such as:

  1. List of data sources and their connection settings
  2. Asset path and url for your widget
  3. List of settings
  4. Others
protected function settings()
{
    return array(
        "dataSources"=>array(
            "sale"=>array(
                "connectionString"=>"mysql:host=localhost;dbname=saledatabase",
                "username"=>"root",
                "password"=>"",
                "charset"=>"utf8"
            ),
        )
    )
}

Now all of your settings will be available to be used.

Initiate Services #

Then, the report start looking for any registered services to initiate them. The service in the report will look like this:

class MyReport extends \koolreport\KoolReport
{
    use \koolreport\clients\Bootstrap; // Use Bootstrap service
    ...
}

In above example, we use Boostrap service to add Twitter Bootstrap Library to your report. So KoolReport will look for any services registed on your report and get them initiated.

Setup Data Processing #

Now your settings and services is up, KoolReport finally call setup() methods to set up your data processing tree. In the setup() methods, we defined how data will flow: which source data come from?, which processes data will pass through?

protected function setup()
{
    $this->src('sale')
    ->query("select customerName, dollar_sales from orders")
    ->pipe(new Group(
        "by"=>"customerName"
        "sum"=>"dollar_sales"
    ))
    ->pipe($this->dataStore("sales_by_customer"));
}

The setup() function helps us to build the data processing tree but no data is passing through yet. It is like we construct a water pipes but we have not pump water through them.

Run #

After your report initiated, everything is ready waiting for data coming to process. You start running your report like this:

$report = new SaleReport(array(
    "startDate"=>"2017-01-01",
    "endDate"=>"2018-01-01"
));

//Run report
$report->run();

After receiving your run command, KoolReport will initiate data pumping process. The datasource starts connecting to databases, reading csv or excel files and then sending row by row of data to the datapipe.

Data from the sources will run through all processes until it reaches the data store where final data will be hold.

Finish #

Render Report #

Now your report ran, data after piping through various process are stored in dataStores. You may render your report with following command:

$report = new SaleReport(array(
    "startDate"=>"2017-01-01",
    "endDate"=>"2018-01-01"
));
$report->run();

//Render report
$report->render();

The render() methods is called without any parameters, it will look for the default view file in form of {report_name}.view.php, in this case is SaleReport.view.php. If the view file is found, report will load and render the view.

If you have different view, you can render it like this:

// If you have Another.view.php, you can render it by
$report->render('Another');

Use Data Only #

In case that you would like to consume data generated by report for other purposes rather than rendering it out, you can do so.

$report = new SaleReport(array(
    "startDate"=>"2017-01-01",
    "endDate"=>"2018-01-01"
));
$report->run();


echo $report->dataStore('sales_by_customer')->toJson();

Above you can see that after the sale report run, "sales_by_customer" data store will be available for you to access. This feature is extremely useful in case you are building web services which will return report in form of JSON, XML or others.