В новой версии 2024.4 мы анонсируем крупное обновление для наших Reports.PHP и Dashboards.PHP продуктов. Был проведён полный рефакторинг кода, улучшена работа событий компонентов, доработан обработчик запросов, добавлены настройки экспортирования, и, самое главное, добавлена возможность построения и экспортирования отчета на стороне сервера. Ниже описаны основные улучшения, и примеры их использования.

Минимальные требования повышены до PHP 7.0

В новой версии мы добавили ряд значительных улучшений и изменений, о которых расскажем ниже. В связи с этим возникла необходимость повысить минимальные требования до PHP 7.0, чтобы реализовать задуманный функционал наилучшим образом. PHP 5.6 является давно устаревшей версией, её поддержка завершена в декабре 2018 года, соответственно, переход на более свежую версию предлагает больше возможностей, более высокую скорость работы и улучшенную безопасность.

Упрощенная настройка скриптов компонентов

Ранее для добавления скриптов компонентов нужно было создавать специальный StiJavaScript объект, настраивать его для конкретного компонента, и отдельно выводить на HTML странице в определенном месте. Теперь в этом нет необходимости, компоненты сами могут развернуть свои скрипты - для этого достаточно одной строки кода. При необходимости, можно изменить настройки скриптов в самом компоненте.
<?php
$viewer = new StiViewer();
$viewer->javascript->usePacked = false;
?>

<!DOCTYPE html>
<html>
<head>
    <?php $viewer->javascript->renderHtml(); ?>
</head>
Добавление скриптов компонентов при помощи отдельного объекта полностью сохранена для совместимости со старой версией.

Новые способы отображения компонентов

Ранее для отображения HTML кода компонента был доступен только один способ - вызов метода renderHtml(), который выведет весь необходимый для работы компонента код в текущем месте страницы. В новой версии работа указанного метода расширена, а также добавлен новый метод printHtml() для всех компонентов. Данный метод выведет полностью подготовленную HTML страницу со всеми необходимыми скриптами и HTML кодом. Этот способ очень удобен, если нет необходимости в своем шаблоне страницы, и компонент вьювера либо дизайнера отображается целиком на всю страницу.
<?php
$viewer = new StiViewer();
$viewer->process();

$viewer->printHtml();
?>
Работа метода renderHtml() была изменена, теперь он генерирует HTML код вместе с блоком <script></script>, поэтому больше нет необходимости добавлять указанный блок на HTML странице. Также больше нет необходимости следить за загрузкой страницы, компонент сам определит момент полной загрузки HTML страницы и необходимых скриптов, после чего начнет работу.

Обработчик событий встроен в компоненты

Ранее обработчик событий создавался и настраивался как отдельный объект StiHandler, со своими настойками и скриптами, и никак не был связан с компонентами (отчетом, вьювером, дизайнером). Теперь можно работать только с компонентами, они сами создадут, настроят и развернут код обработчика событий. Все свойства обработчика можно настроить в самом компоненте. Для обработки событий добавлен специальный метод process(), который обработает запрос, и при необходимости вернет ответ на сторону клиента. Никаких дополнительных действий для этого не требуется.
<?php
$viewer = new StiViewer();
// $viewer->handler->encryptData = true;

$viewer->process();
?>
В тоже время, как и в предыдущих версиях, полностью поддерживается раздельное создание и настройка обработчика.

Упрощенный доступ к опциям компонентов

Ранее для настройки компонентов вьювера и дизайнера отчетов, необходимо было создать отдельный объект опций, настроить его, и передать в конструктор компонента. Теперь такой необходимости нет, объект опций уже встроен в компонент, достаточно просто изменить нужные свойства прямо в самом компоненте.
<?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;
?>
Старый способ установки опций также можно использовать, если это необходимо.

Улучшенная работа событий

Ранее обработка всех событий компонентов производилась в одном файле handler.php, это решение было не всегда удобно и имело ограничения с одноименными событиями разных компонентов. В новой версии каждый компонент имеет свой набор событий. Теперь события могут быть вызваны как на стороне PHP сервера, так и на стороне JavaScript клиента. Более того, добавлена возможность назначить одному событию несколько обработчиков разных типов. Допускается присвоение либо добавление к событию PHP функции, названия JavaScript функции из текущего шаблона страницы, а также JavaScript функции в виде блока кода.
<?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();
?>
Работа событий через отдельный файл полностью сохранена - достаточно установить в настройках обработчика событий путь к файлу, содержащему функции обработки событий, после чего все запросы будут перенаправлены на него.
<?php
$viewer = new StiViewer();
$viewer->handler->url = 'handler.php';
?>

Настройки экспортирования

В новой версии были добавлены настройки экспортирования для всех поддерживаемых форматов. Настройки можно передавать в функцию экспорта, также настройки будут переданы в события экспорта отчета.
<?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);
?>

Построение и экспортирование отчета на стороне сервера

В новой версии мы добавили возможность построения и экспортирования отчета на стороне PHP сервера. Для этой цели используется универсальная платформа Node.js, работающая на различных операционных системах. Для работы с отчетом на стороне сервера необходимо иметь уже установленную платформу 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;
?>
Указанные действия по установке Node.js нужно выполнить один раз, действия по обновлению пакетов - каждый раз после апгрейда версии на более новую. Далее при работе с отчетом, будет использоваться уже установленная версия платформы и пакетов.

Построение и экспорт отчета на стороне сервера реализован максимально просто для использования. Для этого достаточно переключить свойство отчета engine в режим работы на сервере, и использовать уже существующие методы render() и exportDocument(). Теперь эти функции будут автоматически переключены в режим работы на сервере, все события отчета будут работать так же, как и в случае работы генератора отчетов на стороне сервера.

Пример построения отчета и получения файла документа (либо его сохранения в файл):
<?php
$report = new StiReport();
$report->engine = StiEngineType::ServerNodeJS;

$result = $report->render();
if ($result) {
    $document = $report->saveDocument();
    // $result = $report->saveDocument('reports/SimpleList.mdc');
}
?>
Пример экспортирования отчета на сервере и получения результата в виде строки (либо сохранения экспортированных данных в файл):
<?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');
}
?>

Режим обратной совместимости

Мы постарались реализовать все нововведения таким образом, чтобы уже существующие проекты были максимально работоспособны, а переход на новую версию был плавным. После обновления могут возникнуть следующие проблемы:
  • свойство или метод помечен как устаревший;
  • не найдены некоторые классы и перечисления;
  • запросы обработчика не направляются в файл handler.php;
  • неверно выводится HTML код компонента.

Все указанные проблемы можно легко решить, включив режим совместимости со старой версией. Мы рекомендуем данный вариант как временный, т.к. в этом случае могут неверно работать некоторые нововведения. Для включения режима совместимости необходимо добавить одну строку кода в начало файла.
<?php
require_once 'vendor/autoload.php';

\Stimulsoft\StiHandler::enableLegacyMode();
?>
Для полного перехода на новую версию, потребуется сделать небольшие изменения в коде ваших проектов. Ниже рассмотрены варианты решения всех указанных выше проблем.

Устаревшие свойства и методы

В новой версии некоторые свойства изменили свое расположение, а некоторые методы были переименованы для более четкого понимания и организации кода. Старые имена сохранены и помечены как @deprecated, для решения проблемы просто замените их на новые, указанные в описании устаревшего свойства либо метода.

Пространства имен

В новой версии было добавлено значительное количество новых классов и перечислений, поэтому нам необходимо было пересмотреть пространства имен для исключения пересечений. Ниже представлена таблица соответствий пространств имен.

Старые пространства именНовые пространства имен
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)

Для решения проблемы с пространствами имен достаточно заменить старые пространства на новые, каких-либо других изменений в коде не требуется.

Запросы обработчика событий

В новой версии все события и сам обработчик событий были перенесены в компоненты, поэтому по умолчанию все запросы теперь приходят на текущую страницу с компонентом, вместо отдельного файла handler.php обработки событий. Есть несколько вариантов решения данной проблемы.

Первый вариант - перенаправить запросы на отдельный файл, в этом случае события будут работать так же, как и раньше. Для этого просто укажите путь к файлу обработки событий.

При использовании отдельного обработчика
<?php
$handler = StiHandler("handler.php");
?>
При использовании встроенного обработчика
<?php
$viewer = new StiViewer();
$viewer->handler->url = "handler.php";
?>
Второй вариант - перенести события компонента в основной файл, и использовать специальный метод process() компонента для обработки событий. Этот вариант является предпочтительным, и используется в новых примерах и документации.
<?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 кода компонентов

В новой версии добавлены новые варианты вывода HTML кода компонентов, поэтому поведение по умолчанию уже существующих методов было скорректировано. Главным изменением является то, что метод renderHtml() теперь помимо основного кода компонента, выводит HTML тэги <script></script>, это может нарушить работу уже существующих проектов. Есть несколько вариантов решения данной проблемы.

Первый вариант - просто убрать в HTML шаблоне страницы тэги <script></script>, никаких дополнительных действий не требуется.

Старый вариант
<script>
<?php
$viewer = new StiViewer();
$viewer->renderHtml();
?>
</script>
Новый вариант
<?php
$viewer = new StiViewer();
$viewer->renderHtml();
?>
Второй вариант - использовать метод getHtml() с параметром StiHtmlMode::Scripts, в этом случае компонент вернёт такой же HTML код, как и в предыдущих версиях. Данный способ применим в случае, когда компонент выводится внутри какой-либо JavaScript функции.

Старый вариант
<?php
$viewer = new StiViewer();
?>
	
<script>
function showViewer() {
    <?php $viewer->renderHtml(); ?>
}
</script>
Новый вариант
<?php
$viewer = new StiViewer();
?>
<script>
function showViewer() {
    <?php echo $viewer->getHtml(StiHtmlMode::Scripts); ?>
}
</script>

Уже доступно для использования

Все указанные нововведения уже доступны для использования, начиная с версии 2024.3.2, и в данный момент находятся на стадии тестирования и финальных доработок. Вы можете загрузить скрипты из отдельной ветки репозитория, которая вскоре будет выгружена в основную. Подготовлены новые примеры использования, а документация в ближайшее время будет обновлена. Мы рады любым комментариям и пожеланиям по доработке продукта.

Примеры использования с последними версиями скриптов находятся по данной ссылке.
Используя этот сайт, вы соглашаетесь на использование файлов Cookie для аналитики и персонализированного контента. Файлы Cookie хранят полезную информацию на вашем компьютере, чтобы помочь нам повысить эффективность и удобство использования. Для получения дополнительной информации, пожалуйста, прочтите Конфиденциальность и Использование Cookie.