KoolReport PHP Reporting Framework

A standard KoolReport implementation consists of three main parts: a bootstrap file (index.php), a report definition class (SalesByCustomer.php), and a view file (SalesByCustomer.view.php).

1. The Bootstrap File (index.php)

This file initializes the report class, runs the data processing, and renders the view.

<?php
require_once "SalesByCustomer.php";

$salesByCustomer = new SalesByCustomer;
$salesByCustomer->run()->render();

2. The Report Class (SalesByCustomer.php)

Extend \koolreport\KoolReport to define your data sources and processing pipeline.

• settings(): Define your dataSources. Each source requires a class (e.g., \koolreport\datasources\CSVDataSource) and configuration parameters (e.g., filePath).
• setup(): Define the data pipeline. Use $this->src('source_name') to select a source, then use ->pipe() to pass data through various processes (like Group, Sort, or Limit) before saving it to a dataStore using ->pipe($this->dataStore('store_name')).

3. The View File (SalesByCustomer.view.php)

Use widget classes to render the processed data. Widgets typically use ::create() and require a dataStore name that matches the one defined in the setup() method.

<?php 
    use \koolreport\widgets\koolphp\Table;
    use \koolreport\widgets\google\BarChart;
?>

<?php
BarChart::create(array(
    "dataStore" => $this->dataStore('sales_by_customer'),
    "columns" => array(
        "customerName" => array("label" => "Customer"),
        "dollar_sales" => array("type" => "number", "label" => "Amount")
    )
));
?>

<?php
require_once "../koolreport/autoload.php";

use \koolreport\processes\Group;
use \koolreport\processes\Sort;
use \koolreport\processes\Limit;

class SalesByCustomer extends \koolreport\KoolReport
{
    protected function settings()
    {
        return array(
            "dataSources"=>array(
                "sales"=>array(
                    "class"=>'\koolreport\datasources\CSVDataSource',
                    "filePath"=>"orders.csv",
                ),
            )
        );
    }

    protected function setup()
    {
        $this->src('sales')
        ->pipe(new Group(array(
            "by"=>"customerName",
            "sum"=>"dollar_sales"
        )))
        ->pipe(new Sort(array(
            "dollar_sales"=>"desc"
        )))
        ->pipe(new Limit(array(10)))
        ->pipe($this->dataStore('sales_by_customer'));
    }
}

KoolReport uses a 'legos-like' structure where the reporting pipeline is composed of Node objects. Data flows from source nodes through various processing nodes to destination nodes.

Key concepts of the Node model:

• Piping: You connect nodes using the pipe() method. This establishes a relationship where the current node sends data to the next node in the chain.
• Streaming: Data is processed as a stream of rows (associative arrays). Nodes receive data via input(), process it, and pass it forward using next().
• Lifecycle: A node's lifecycle involves receiving a startInput() signal, processing data via onInput(), and eventually receiving an endInput() signal once all upstream sources have finished.
• Metadata: Nodes can pass metaData through the pipeline using receiveMeta() and sendMeta(), allowing non-row information to travel alongside the data stream.

// Example of connecting nodes in a pipeline
$source->pipe($processor)->pipe($destination);

To implement a custom visual style for KoolReport, you must create a class that extends koolreport\core\Theme. You will need to override several protected methods to define your theme's identity, supported widgets, and color schemes.

Key methods to implement:

• themeInfo(): Returns an associative array containing name, version, base (e.g., 'bs4'), and cssClass (the class to be attached to widgets).
• themeWidgets(): Returns an associative array of supported widgets and their associated resource paths (JS/CSS).
• allColorSchemes(): Returns an associative array of color schemes, where each scheme is an array of hex color strings.
• onInit(): An optional lifecycle method called during construction.

namespace myapp\theme;

use koolreport\core\Theme;

class MyCustomTheme extends Theme
{
    protected function onInit()
    {
        // Initialization logic
    }

    public function themeInfo()
    {
        return [
            "name" => "My Custom Theme",
            "version" => "1.0.0",
            "base" => "bs4",
            "cssClass" => "my-custom-theme-class",
        ];
    }

    protected function allColorSchemes()
    {
        return [
            "default" => ["#000", "#333", "#666", "#999", "#bbb", "#ddd", "#fff"],
            "ocean" => ["#0077be", "#00a3e0", "#5f9ea0", "#add8e6"],
        ];
    }

    protected function themeWidgets()
    {
        return [
            'koolreport\widgets\chart\Chart' => [
                'folder' => 'assets/chart',
                'js' => ['chart.js'],
                'css' => ['chart.css'],
            ],
        ];
    }
}

To use OracleDataSource on a Windows environment with Apache, follow these steps:

1. Install Oracle Database (32-bit): Since PHP on Windows is typically 32-bit, you must install the 32-bit version of the Oracle database.
2. Configure Oracle Instant Client:
   • Download and extract the Oracle Instant Client 32-bit.
   • Add the extracted folder to your Windows Path environment variable.
3. Install Visual Studio Redistributable: Install the version required by your Instant Client (e.g., VC 2013 for Instant Client 12.2.0.1.0).
4. Configure Apache:
   • Copy all .dll files from the Oracle Instant Client 32-bit folder into Apache's bin folder.
   • Enable the extension in php.ini (e.g., extension=php_oci8_12c.dll).
   • Restart Apache.

For PDO with Oracle on Windows:

• Follow the same steps as above, but instead of the OCI8 extension, enable extension=php_pdo_oci.dll in php.ini and restart Apache.