Compatibility
Enable Export
Export a view
Settings
Export to PDF
Save file vs push file to browser
Export to image
Make PDF Open On Browser
Generate Base64 string
Page Break
Full example

Get started

Compatibility #

Export package uses Phantomjs headless browser to render PDF from web page served by your report's web server. It is known that Phantomjs only works well with full-fledged and production web servers such as Apache, Nginx, etc and not PHP built-in development web server (run as php -S localhost:8000 or php artisan serve).

Enable Export #

To enable Export feature in KoolReport, you do:

class MyReport extends \koolreport\KoolReport
{
    use \koolreport\export\Exportable;
    ...
}

Now your MyReport has ability to export, in the run file(index.php), you do:

...
$report->run()->export()->pdf(array(
    "format"=>"A4",
    "orientation"=>"portrait"
))->toBrowser("myfile.pdf");

Export a view #

Sometime, you have a view for browser's display and another view for exporting. The separation make things simpler. Assume that you create a view called AnotherViewForPDF.view.php, you can do:

$report->run();
$report->export('AnotherViewForPDF')->...

Settings #

There are some settings for exporting that you may need to aware of.

name	type	default	description
phantomjs	string		Set the path to your phantomjs install if it's not in koolreport/export/bin
useLocalTempFolder	boolean	false	Whether to use a local temporary directory or the system temporary one
autoDeleteLocalTempFile	boolean	false	When use a local temporary directory, whether to delete local temporary files after exporting
resourceWaiting	numeric	1000	Micro seconds to wait after the page loads to retrieve remote resources
serverLocalAddress	string		Use this and set it to "localhost" or "127.0.0.1" when your server can not access your report's resources with $_SERVER["HTTP_HOST"] name

$report->export()
->settings(array(
    "useLocalTempFolder"=>true,
    // "autoDeleteLocalTempFile"=>true,
    "autoDeleteTempFile" => true,
    "phantomjs"=>"/path/to/phantomjs",
    "resourceWaiting"=>2000,
    "serverLocalAddress" => "MyServer", // default = "localhost", if your network doesn't allow localhost address use this setting
))
->pdf(array(
    ...
))
->toBrowser("report.pdf");

In rare case you receive Exception: Could not save content to temporary folder, probably your server does not support writing files to temporary folder /tmp for example. In this case, you may set "useLocalTempFolder"=>true. This settings will tell Export package to create a local temp located at the current report directory.

Since version 5.2.0 "useLocalTempFolder" could be a path to any directory to be used as a temporary one.

In some case, your server required phantomjs to be installed rather than used directly from bin folder. After installing phantomjs, you may use the "phantomjs"=>"/path/to/phantomjs" to let Export package know how to call PhantomJS executed file.

The resourceWaiting is the milliseconds that export package will wait if there is any left resource to load before it decides to end loading and start exporting to PDF and others. By default, the resourceWating is 1000 milliseconds ( or 1 seconds) but you should set your own value to suit your server. Please choose the optimal value. If value is too low, it will cause page not fully loaded. If the value is too high, it will take longer time overall to generate PDF.

Export to PDF #

We have several options for PDF exporting which are

name	type	default	description
margin	string/array	"0px"	The margin of the page, accepting unit in `px`,`cm` and `in`. The margin can be an `array` contains separated settings for `top`,`left`,`right`,`bottom`
width	string		Width of the page
height	string		Height of the page
header	array		The header of PDF page, it is array containing `height` and `contents` parameters, for example `"header"=>array("height"=>"30px","contents"=>"this is header")`
footer	array		The footer of PDF page, it is array containing `height` and `contents` parameters, for example `"footer"=>array("height"=>"30px","contents"=>"this is footer")`
format	string	"A4"	The paper format, accepting "A3","A4","A5","Letter","Legal","Tabloid"
orientation	string	"portrait"	The orientation of the page, it always goes with the `format` property
dpi	number	72	Set the dpi for image or PDF
zoom	number	1	This is the page zoom factor, the default in linux is `0.5` and other OS is `1.0`

Example #

Set landscape A4 with 1 inch margin for PDF file

$report->export()->pdf(array(
    "format"=>"A4",
    "orientation"=>"landscape",
    "margin"=>"1in",
))->toBrowser("myfile.pdf");

Set custom width and height for PDF

$report->export()->pdf(array(
    "width"=>"1024px",
    "height"=>"768px",
    "margin"=>"50px",
))->toBrowser("myfile.pdf");

Set custom margin components:

$report->export()->pdf(array(
    "format"=>"A4",
    "orientation"=>"landscape",
    "margin"=>array(
        "top"=>"0.5in",
        "bottom"=>"0.5in",
        "left"=>"1in"
        "right"=>"1in"
    ),
))->toBrowser("myfile.pdf");

Set paper margin on the view #

Alternatively to setting margin through the pdf() function, you can set the margin of page on the view by setting margin css style in the <body> tag:

Example: Set 1cm margin for page

<html>
    <body style="margin:1cm">
    ...
    </body>
</html>

Example: Set value for each margin component

<html>
    <body style="margin: 10px 20px 10px 20px">
    ...
    </body>
</html>

or you can do:

<html>
    <body style="margin-top:10px;margin-right:20px;margin-bottom:10px;margin-left:20px;">
    ...
    </body>
</html>

Header and footer of the page #

You may set the header and footer on top of each PDF page using the <div class='page-header'></div> and <div class='page-footer'></div> tag inside the <body> of view.

<html>
    <body style="margin: 1in">
        <div class='page-header' style='height:30px'>
            <span>Header</span>
        </div>

        ...
        ...

        <div class='page-footer' style='height:30px'>
            <span>Footer</span>
        </div>
    </body>
</html>

If you want to set show the page number and also the total number of pages, you do:

<html>
    <body style="margin: 1in">
        <div class='page-header' style='height:30px'>
            <span>Page {pageNum}/{numPages}</span>
        </div>

        ...
        ...

        <div class='page-footer' style='height:30px'>
            <span>Page {pageNum}/{numPages}</span>
        </div>
    </body>
</html>

If you want to make the header and footer show on the right of page, do this:

<html>
    <body style="margin: 1in">
        <div class='page-header'>
            <div style="text-align:right">Header</div>
        </div>

        <div class='page-footer'>
            <div style="text-align:right">Header</div>
        </div>
    </body>
</html>

To show the header and footer at the center, it is easy as:

<html>
    <body style="margin: 1in">
        <div class='page-header'>
            <div style="text-align:center">Header</div>
        </div>

        <div class='page-footer'>
            <div style="text-align:center">Header</div>
        </div>
    </body>
</html>

Easy, isn't it?

Header and footer callbacks (version >= 5.0.0) #

Since version 5.0.0 Export package allows for extensive customization of header and footer using javascript function:

$report->export()->pdf(array(
    //headerCallback and footerCallback could be js function that return header and footer content based on current page (pageNum), total number of page (numPages) and header/footer content set by pdf option or page-header, page-footer tags
    "headerCallback" => "function(headerContent, pageNum, numPages){
        if (pageNum == 1) return ''; //don't return any header for page number 1
        return 'This is a header' || headerContent;
    }",
    "footerCallback" => "function(footerContent, pageNum, numPages){
        if (pageNum == numPages) return ''; //don't return any footer for the last page
        return 'This is a footer' || footerContent;
    }",
))->toBrowser("myfile.pdf");

Save file vs push file to browser #

After exporting, you have two options to do with the file. First, you can save the file to local drive and can use it later for example attaching file to email. Second, you can push to file to browser for user to download.

To save file, you do:

$report->export()->pdf()->saveAs("../storage/myreport.pdf"); // State the path of file

To push file to browser, you do:

$report->export()->pdf()->toBrowser("myreport.pdf"); // Input the filename

Export to image #

$report->export()->jpg(array(
    "width"=>"1024px",
    "height"=>"768px",
))->saveAs("../storage/myreport.jpg");

You can set the width and height in cm and in. Above example demonstrate exporting to .jpg file, other file types work in the same way. Here is the full list of supported image files:

method	description
jpg($params)	Export to `.jpg` file
gif($params)	Export to `.gif` file
bmp($params)	Export to `.bmp` file
ppm($params)	Export to `.ppm` file
png($params)	Export to `.png` file

Make PDF Open On Browser #

Instead of pushing file to browser for you to download, you may make PDF or or exported images to open on browser

$report->export()->pdf()->toBrowser("myreport.pdf",true);

By adding true to the second parameter of toBrowser() function, you will force browser to open the file.

Generate Base64 string #

You may generate base64 string:

$report->export()->pdf()->toBase64();

Page Break #

If you want to make a table or anything start at new page, you may use the page break like following:

<div class="page-break"></div>
<?php 
Table::create(array(..));
?>

Above code will make the table starts at a new page.

Full example #

In this example, we would like to summarize sale of Sakila Rental by month and display resulted in column chart and in a detail table.

index.php

<?php
require "SakilaRental.php";
$report = new SakilaRental;
$report->run();
$report->export()->pdf()->toBrowser("sakila.pdf");

SakilaRental.php

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

use \koolreport\KoolReport;
use \koolreport\processes\TimeBucket;
use \koolreport\processes\Group;

class SakilaRental extends KoolReport
{
    use \koolreport\export\Exportable;
    
    public function settings()
    {
        return array(
            "dataSources"=>array(
                "sakila_rental"=>array(
                    "class"=>'\koolreport\datasources\CSVDataSource',
                    'filePath'=>dirname(__FILE__)."\sakila_rental.csv",
                )
            )
        );
    }   
    protected function setup()
    {
        $this->src('sakila_rental')
        ->pipe(new TimeBucket(array(
            "payment_date"=>"month"
        )))
        ->pipe(new Group(array(
            "by"=>"payment_date",
            "sum"=>"amount"
        )))
        ->pipe($this->dataStore('sale_by_month'));
    } 
}

SakilaRental.view.php

<?php 
use \koolreport\widgets\koolphp\Table;
use \koolreport\widgets\google\ColumnChart;
?>
<!DOCTYPE html>
<html>
    <body style="margin:1in">
        <div class='page-header'>
            <span style="float:right">{pageNum}/{numPages}</span>
        </div>
        <div class='page-footer'>
            <span style="float:right">{pageNum}/{numPages}</span>
        </div>

            <div class="text-center">
                <h1>Cash In Report</h1>
                <h4>This report show the cash-in report per month</h4>
            </div>
            <hr/>

            <?php
            ColumnChart::create(array(
                "dataStore"=>$this->dataStore('sale_by_month'),  
                "columns"=>array(
                    "payment_date"=>array(
                        "label"=>"Month",
                        "type"=>"datetime",
                        "format"=>"Y-n",
                        "displayFormat"=>"F, Y",
                    ),
                    "amount"=>array(
                        "label"=>"Amount",
                        "type"=>"number",
                        "prefix"=>"$",
                    )
                ),
                "width"=>"100%",
                "height"=>"400px",
            ));
            ?>
            <div class="page-break"></div>
            <?php
            Table::create(array(
                "dataStore"=>$this->dataStore('sale_by_month'),
                "columns"=>array(
                    "payment_date"=>array(
                        "label"=>"Month",
                        "type"=>"datetime",
                        "format"=>"Y-n",
                        "displayFormat"=>"F, Y",
                    ),
                    "amount"=>array(
                        "label"=>"Amount",
                        "type"=>"number",
                        "prefix"=>"$",
                                )
                ),
                "cssClass"=>array(
                    "table"=>"table table-hover table-bordered"
                )
            ));
            ?>
            
    </body>
</html>

You may view the exported result here

Get started with KoolReport

KoolReport will help you to construct good php data report by gathering your data from multiple sources, transforming them into valuable insights, and finally visualizing them in stunning charts and graphs.