README

JasperPHP

A pure PHP library to generate reports from JasperSoft Studio (.jrxml files), without the need for a Java bridge or a Jasper Server.

For more details, documentation, and blog posts, visit jasperphp.com.

Recent Changes & Modernization

This project has undergone a significant modernization effort to align with current PHP best practices. Key changes include:

• Laravel\Octane integration: Added methods to reset static classes and values to each request (tested OK)
• Composer Integration: The project now uses Composer for dependency management.
• PSR-4 Autoloading: Switched to PSR-4 for class autoloading, with a reorganized and namespaced directory structure (src/).
• Static Analysis: phpstan has been integrated to improve code quality and catch errors.
• Flexible Data Sources: Added support for multiple data sources, including Arrays, JSON/CSV files, and direct database queries.
• Versatile Output Methods: Introduced new methods to stream reports to the browser, force downloads, save to a file, or get the content as a base64 string.

Requirements

• PHP 7.4 or higher
• Composer for dependency management.

The following PHP extensions are also required:

• gd
• mbstring
• xml

Installation

Install the library using Composer:

composer require quilhasoft/jasperphp:dev-master

Quick Start

Here is a basic example of how to generate a report. For a more detailed and runnable example, see public/index.php.

<?php

require_once __DIR__ . '/vendor/autoload.php';

use JasperPHP\core\TJasper;

// Path to your .jrxml file
$reportFile = __DIR__ . '/path/to/your/report.jrxml';

// Report parameters (if any)
$params = ['title' => 'My Report'];

// Data source configuration
$dataSource = [
    'type' => 'array',
    'data' => [
        ['id' => 1, 'name' => 'Product A', 'price' => 10.50],
        ['id' => 2, 'name' => 'Product B', 'price' => 22.00],
    ]
];

try {
    // Instantiate the report
    $jasper = new TJasper($reportFile, $params, $dataSource);

    // Generate and output the report to the browser
    // The output() method handles the entire process
    $jasper->output(); // Default output is PDF inline

} catch (\Exception $e) {
    echo 'Error generating report: ' . $e->getMessage();
}

Data Sources

You can use different types of data sources to populate your reports.

Array

Pass an array of objects or associative arrays directly.

$dataSource = [
    'type' => 'array',
    'data' => [
        (object)['id' => 1, 'name' => 'Item A'],
        (object)['id' => 2, 'name' => 'Item B']
    ]
];

Database (DB)

Execute a SQL query to fetch data.

$dataSource = [
    'type' => 'db',
    'sql' => 'SELECT * FROM customers',
    'db_driver' => 'mysql',
    'db_host' => 'localhost',
    'db_port' => '3306',
    'db_name' => 'mydatabase',
    'db_user' => 'user',
    'db_pass' => 'password',
];

JSON or CSV File

Load data from a local .json or .csv file.

// From a JSON file
$dataSource = [
    'type' => 'json_file',
    'path' => '/path/to/your/data.json'
];

// From a CSV file
$dataSource = [
    'type' => 'csv_file',
    'path' => '/path/to/your/data.csv'
];

Using Embedded SQL Query (from JRXML)

The library also retains the classic JasperReports functionality of executing a SQL query embedded directly within the .jrxml file. When no dataSource is provided in the PHP code, JasperPHP will look for a <queryString> tag inside the report file and execute it using the provided database connection.

This method is especially useful for creating master-detail reports, where a subreport can fetch its own data based on parameters passed from the main report.

Example JRXML (subreport.jrxml):

...
<parameter name="CUSTOMER_ID" class="java.lang.Integer"/>
<queryString>
    <![CDATA[SELECT * FROM orders WHERE customer_id = $P{CUSTOMER_ID}]]>
</queryString>
<field name="order_date" class="java.util.Date"/>
<field name="order_total" class="java.math.BigDecimal"/>
...

Example PHP: To run a report with an embedded query, provide the database connection details but omit the 'sql' key from the dataSource.

$dbConfig = [
    'type' => 'db',
    // No 'sql' key is needed here
    'db_driver' => 'mysql',
    'db_host' => 'localhost',
    'db_name' => 'mydatabase',
    'db_user' => 'user',
    'db_pass' => 'password',
];

// Parameters needed by the query in the JRXML
$reportParams = [
    'CUSTOMER_ID' => 123
];

$jasper = new TJasper('report_with_query.jrxml', $reportParams, $dbConfig);
$jasper->output();

Output Methods

The output() method provides several ways to deliver the generated report.

public function output(string $mode = 'I', string $filename = 'report.pdf', ?string $filePath = null): ?string

• $mode:
  • I (Inline): Streams the report directly to the browser. (Default)
  • D (Download): Forces the browser to download the report file.
  • F (File): Saves the report to a local file specified by $filePath.
  • S (String): Returns the raw report content as a string (or base64 encoded for binary formats).
• $filename: The name of the file for I and D modes.
• $filePath: The absolute path to save the file in F mode.

Examples:

// Stream to browser
$jasper->output('I', 'my_report.pdf');

// Force download
$jasper->output('D', 'invoice.pdf');

// Save to a file
$jasper->output('F', 'report.pdf', '/path/to/save/report.pdf');

// Get as a string
$reportContent = $jasper->output('S');

Supported Formats

• PDF
• XLS
• XLSX

Supported JRXML Elements

The library supports a wide range of JRXML tags and components.

* Subreports are supported recursively and without limits.

Other Features

• Aggregation functions for variables (sum, average, min, max).
• Reading and calculating variables from subreports.
• Conditional styling.
• Support for Laravel DB Facade by setting the net.sf.jasperreports.data.adapter property in your JRXML.

License

This library is licensed under the MIT License.