A major update in Reports.PHP and Dashboards.PHP

Author: Alex Markus
In version 2024.4, we are announcing a major update for our Reports.PHP and Dashboards.PHP products. The code has been completely refactored, the operation of component events has been improved, the request handler work has been enhanced, export settings have been added, and most importantly, the ability to render and export reports on the server side has been implemented. The main improvements and examples of their use are described below.

Minimum requirements raised to PHP 7.0

In the new version, we have added several significant improvements and changes, which we will describe below. As a result, it was necessary to raise the minimum requirements to PHP 7.0 to implement the intended functionality effectively. PHP 5.6 is long outdated, with its support ending in December 2018. Consequently, upgrading to a more recent version provides more features, higher speed, and improved security.

Simplified configuration of component scripts

Previously, when you needed to add component scripts, it was necessary to create a special StiJavaScript object, configure it for a specific component, and display it separately on the HTML page in a certain place. Now, there is no need for this; the components can deploy their own scripts with just one line of code. If necessary, you can change the script settings in the component. 
<?php
$viewer = new StiViewer();
$viewer->javascript->usePacked = false;
?>

<!DOCTYPE html>
<html>
<head>
    <?php $viewer->javascript->renderHtml(); ?>
</head>
Adding component scripts using a separate object is fully preserved for compatibility with the older version.

New ways to display components

Previously, there was only one method available for displaying the HTML code of a component: calling the renderHtml() method, which would display all the code necessary for the component to work in its current location on the page. In the new version, the functionality of this method has been expanded, and a new printHtml() method has been added for all components. This method will display a fully prepared HTML page with all the necessary scripts and HTML code. It can be used if you do not need your page template and want the viewer or designer component to be displayed entirely on the page. 
<?php
$viewer = new StiViewer();
$viewer->process();

$viewer->printHtml();
?>
The renderHtml() method will now work differently. It generates HTML code together with the <script></script> block, so you no longer need to add this block to the HTML page. It is also no longer necessary to monitor the page loading; the component will determine the moment the HTML page and necessary scripts are fully loaded, after which it will start working.

The event handler is built into components

Previously, the event handler was created and configured as a separate StiHandler object, with its own settings and scripts, and was not connected to components (report, viewer, designer) in any way. Now you can work solely with components; they will create, configure, and deploy the event handler code themselves. All properties of the handler can be configured within the component. A special process() method has been added for event processing. It processes the request and, if necessary, returns the response to the client. No additional actions are required. 
<?php
$viewer = new StiViewer();
// $viewer->handler->encryptData = true;

$viewer->process();
?>
At the same time, as in previous versions, separate creation and configuration of the handler is fully supported.

Simplified access to component options

Previously, configuring the viewer and report designer components required creating a separate options object, configuring it, and passing it to the component constructor. Now, this is no longer necessary. The options object is built into the component, allowing you to simply change the necessary properties directly in the component. 
<?php
$viewer = new StiViewer();
$viewer->options->appearance->backgroundColor = 'black';
$viewer->options->appearance->theme = StiViewerTheme::Office2022BlackGreen;
$viewer->options->toolbar->displayMode = StiToolbarDisplayMode::Separated;
$viewer->options->toolbar->showFullScreenButton = false;
?>
The old way of setting options can also be used if necessary.

Improved event handling

Previously, processing all component events was done in a single file, handler.php. This solution was not always convenient and had limitations with events of the same name in different components. In the new version, each component has its own set of events. Now, events can be triggered both on the PHP server side and on the JavaScript client side. Additionally, it is now possible to assign multiple handlers of different types to a single event. You can assign or add to an event a PHP function, the name of a JavaScript function from the current page template, or a JavaScript function in the form of a code block. 
<?php
$viewer = new StiViewer();

$viewer->onBeginProcessData = function (StiDataEventArgs $args) {
    if ($args->connection == 'MyConnectionName')
        $args->connectionString = 'Server=localhost;Database=test;uid=root;password=******;';
};

$viewer->onBeginExportReport->append(function (StiExportEventArgs $args) {
    $args->fileName = "MyExportedFileName.$args->fileExtension";
    if ($args->format == StiExportFormat::Pdf) {
        /** @var StiPdfExportSettings $settings */
        $settings = $args->settings;
        $settings->creatorString = 'My Company Name';
    }
});

$viewer->onBeginExportReport->append('beginExportReport');

$viewer->onBeginExportReport->append('
    if (args.format == Stimulsoft.Report.StiExportFormat.Pdf)
        args.settings.imageResolution = 200;
');

$viewer->process();
?>
Event processing through a separate file remains unchanged. You simply need to set the path to the file containing the event processing function in the event handler settings, after which all requests will be redirected to it. 
<?php
$viewer = new StiViewer();
$viewer->handler->url = 'handler.php';
?>

Export settings

In the new version, we have added export settings for all supported formats. These settings can be passed to the export function and will be applied to the report export event. 
<?php
$report = new StiReport();

$settings = new StiPdfExportSettings();
$settings->creatorString = 'My Company Name';
$settings->keywordsString = 'SimpleList PHP Report Export';
$settings->embeddedFonts = false;

$report->exportDocument(StiExportFormat::Pdf, $settings);
?>

Building and exporting a report on the server side

In the new version, we have introduced the capability to create and export reports on the PHP server side. This is facilitated by utilizing the versatile Node.js platform, which operates across different operating systems. To utilize report functionalities on the server side, ensure that Node.js is installed on your system. Alternatively, you can use specialized classes for installing and configuring Node.js. 
<?php
$nodejs = new StiNodeJs();

// Setting the path to the executable files of the already installed Node.js
//$nodejs->binDirectory = "C:\\Program Files\\nodejs";
//$nodejs->binDirectory = "/usr/bin/nodejs";

// Setting the path to the working directory where Node.js packages will be deployed
// By default, the current Python script execution directory is used
//$nodejs->workingDirectory = '';

// Installing the Node.js package from the official website, may take some time
// If the installation fails, the function will return false
$result = $nodejs->installNodeJS();

// Installing or updating product packages to the current version, may take some time
if ($result)
    $result = $nodejs->updatePackages();

// Installation status or error text from Node.js engine
$message = $result ? 'The installation was successful.' : $nodejs->error;
?>
The steps for installing Node.js need to be performed only once, while the steps for updating packages should be carried out each time after upgrading to a newer version. Additionally, when working with the report, the already installed version of the platform and packages will be utilized.

Building and exporting a report on the server side is designed to be as straightforward as possible. To achieve this, simply switch the report engine property to server mode and utilize the existing render() and exportDocument() methods. These functions will automatically operate in server-side mode, ensuring that all report events function identically to when the reporting tool runs on the server side.

Here is an example of how to build a report and obtain a document file (or save it to a file): 
<?php
$report = new StiReport();
$report->engine = StiEngineType::ServerNodeJS;

$result = $report->render();
if ($result) {
    $document = $report->saveDocument();
    // $result = $report->saveDocument('reports/SimpleList.mdc');
}
?>
An example of exporting a report on the server and obtaining the result in the form of a line (or saving the exported data to a file): 
<?php
$report = new StiReport();
$report->engine = StiEngineType::ServerNodeJS;

$result = $report->render();
if ($result) {
    $result = $report->exportDocument(StiExportFormat::Text);
    // $result = $report->exportDocument(StiExportFormat::Pdf, null, false, 'reports/SimpleList.pdf');
}
?>

Backward compatibility mode

We have implemented all the innovations to ensure that existing projects remain as efficient as possible, making the transition to the new version smooth. After the update, you may experience the following issues:
  • properties or methods marked as deprecated;
  • some classes and enums not found;
  • handler requests not sent to the handler.php file;
  • the HTML code of the component displayed incorrectly.

All these problems can be easily solved by turning on compatibility mode with the old version. We recommend using this option temporarily, as some innovations may not work correctly in this mode. To enable compatibility mode, you need to add one line of code to the beginning of the file. 
<?php
require_once 'vendor/autoload.php';

\Stimulsoft\StiHandler::enableLegacyMode();
?>
For a complete transition to the new version, you will need to make small changes to the code of your projects. Options for solving all of the aforementioned problems are discussed below.

Obsolete properties and methods

In the new version, some properties have changed their location, and some methods have been renamed for better clarity and organization of the code. The old names are preserved and marked as @deprecated. To solve the problem, simply replace them with the new ones specified in the description of the deprecated property or method.

Namespace

In the new version, a significant number of new classes and enumerations have been added, necessitating a revision of the namespaces to avoid conflicts. Below is a table of namespace correspondences.

Old name spacesNew name spaces
Stimulsoft\StiComponentType Stimulsoft\Enums\StiComponentType
Stimulsoft\StiEventType Stimulsoft\Enums\StiEventType
Stimulsoft\StiExportFormat Stimulsoft\Export\Enums\StiExportFormat
Stimulsoft\StiExportAction Stimulsoft\Viewer\Enums\StiExportAction
Stimulsoft\StiPrintAction Stimulsoft\Viewer\Enums\StiPrintAction
   
Stimulsoft\Report\(enum classes) Stimulsoft\Report\Enums\(enum classes)
Stimulsoft\Viewer\(enum classes) Stimulsoft\Viewer\Enums\(enum classes)
Stimulsoft\Designer\(enum classes) Stimulsoft\Designer\Enums\(enum classes)
   
Stimulsoft\(event classes) Stimulsoft\Events\(event classes)

To solve the problem with namespaces, simply replace the old namespaces with the new ones. No other changes to the code are required.

Event handler requests

In the new version, all events and the event handler itself have been moved to components. As a result, all requests now, by default, come to the current page with the component instead of a separate event handler.php file. There are several options for solving this problem.

The first option is to redirect requests to a separate file. In this case, the events will work as before. To do this, simply specify the path to the event processing file.

Using a separate handler 
<?php
$handler = StiHandler("handler.php");
?>
Using built-in handler 
<?php
$viewer = new StiViewer();
$viewer->handler->url = "handler.php";
?>
The second option is used to transfer component events to the main file and use the component's special process() method to handle events. This option is preferred and is used in new examples and documentation. 
<?php
$viewer = new StiViewer();

$viewer->onBeginProcessData = function (StiDataEventArgs $args) {
    if ($args->connection == 'MyConnectionName')
        $args->connectionString = 'Server=localhost;Database=test;uid=root;password=******;';
};

$viewer->process();
?>

HTML output of components

In the new version, new options for outputting the HTML code of the components have been added, so the default behavior of existing methods has been adjusted. The main change is that the renderHtml() method now outputs HTML <script></script> tags in addition to the main code of the component. This may disrupt the functionality of existing projects. There are several options for solving this problem.

The first option is to simply remove the <script></script> tags from the HTML page template. No additional actions are required.

Old way 
<script>
<?php
$viewer = new StiViewer();
$viewer->renderHtml();
?>
</script>
New way 
<?php
$viewer = new StiViewer();
$viewer->renderHtml();
?>
The second option is to use the getHtml() method with the StiHtmlMode::Scripts parameter. In this case, the component will return the same HTML code as in previous versions. This method is applicable when the component is displayed inside any JavaScript function.

Old way 
<?php
$viewer = new StiViewer();
?>
	
<script>
function showViewer() {
    <?php $viewer->renderHtml(); ?>
}
</script>
New way 
<?php
$viewer = new StiViewer();
?>
<script>
function showViewer() {
    <?php echo $viewer->getHtml(StiHtmlMode::Scripts); ?>
}
</script>

This is already available

All specified innovations are already available for use starting with version 2024.3.2 and are currently in the testing and final improvement stage. You can upload scripts from a separate branch of the repository, which will soon be merged into the main repository. New usage examples have been prepared, and the documentation will be updated soon. We welcome any comments and suggestions for product improvement.

Examples of usage with the latest versions of the scripts can be found at this link.
By using this website, you agree to the use of cookies for analytics and personalized content. Cookies store useful information on your computer to help us improve efficiency and usability. For more information, please read the privacy policy and cookie policy.
I agree