Reports

为了在 Mautic 中添加和渲染自定义报告，您的插件需要监听以下事件：

• \Mautic\ReportBundle\ReportEvents::REPORT_ON_BUILD

• ReportEvents::REPORT_ON_GENERATE

• ReportEvents::REPORT_ON_GRAPH_GENERATE

<?php
// plugins\HelloWorldBundle\EventListener\ReportSubscriber

namespace MauticPlugin\HelloWorldBundle\EventListener;

use Mautic\CoreBundle\EventListener\CommonSubscriber;
use Mautic\CoreBundle\Helper\GraphHelper;
use Mautic\ReportBundle\Event\ReportBuilderEvent;
use Mautic\ReportBundle\Event\ReportGeneratorEvent;
use Mautic\ReportBundle\Event\ReportGraphEvent;
use Mautic\ReportBundle\ReportEvents;
use Mautic\CoreBundle\Helper\Chart\ChartQuery;
use Mautic\CoreBundle\Helper\Chart\LineChart;

final class ReportSubscriber extends CommonSubscriber
{
   public static function getSubscribedEvents(): array
   {
      return [
            ReportEvents::REPORT_ON_BUILD => ['onReportBuilder', 0],
            ReportEvents::REPORT_ON_GENERATE => ['onReportGenerate', 0],
            ReportEvents::REPORT_ON_GRAPH_GENERATE => ['onReportGraphGenerate', 0],
      ];
   }

   public function onReportBuilder(ReportBuilderEvent $event): void
   {
      if ($event->checkContext(['worlds'])) {
            $prefix = 'w.';
            $columns = [
               $prefix . 'visit_count' => [
                  'label' => 'mautic.hellobundle.report.visit_count',
                  'type' => 'int',
               ],
               $prefix . 'world' => [
                  'label' => 'mautic.hellobundle.report.world',
                  'type' => 'text',
               ],
            ];

            $columns = $filters = array_merge(
               $columns,
               $event->getStandardColumns($prefix),
               $event->getCategoryColumns()
            );

            $filters[$prefix . 'world']['type'] = 'select';
            $filters[$prefix . 'world']['list'] = [
               'earth' => 'Earth',
               'mars' => 'Mars',
            ];

            $event->addTable('worlds', [
               'display_name' => 'mautic.helloworld.worlds',
               'columns' => $columns,
               'filters' => $filters,
            ]);

            $event->addGraph('worlds', 'line', 'mautichellobundle.graph.line.visits');
      }
   }

   public function onReportGenerate(ReportGeneratorEvent $event): void
   {
      $context = $event->getContext();
      if ($context == 'worlds') {
            $qb = $event->getQueryBuilder();
            $qb->from(MAUTIC_TABLE_PREFIX . 'worlds', 'w');
            $event->addCategoryLeftJoin($qb, 'w');
            $event->setQueryBuilder($qb);
      }
   }

```markdown public function onReportGraphGenerate(ReportGraphEvent $event): void

{

if (!$event->checkContext(‘worlds’)) {

return;

}

$graphs = $event->getRequestedGraphs(); $qb = $event->getQueryBuilder();

foreach ($graphs as $graph) {

$queryBuilder = clone $qb; $options = $event->getOptions($graph); $chartQuery = clone $options[‘chartQuery’]; $chartQuery->applyDateFilters($queryBuilder, ‘date_added’, ‘v’);

switch ($graph) {

case ‘mautic.hellobundle.graph.line.visits’:

$chart = new LineChart(null, $options[‘dateFrom’], $options[‘dateTo’]); $chartQuery->modifyTimeDataQuery($queryBuilder, ‘date_added’, ‘v’); $visits = $chartQuery->loadAndBuildTimeData($queryBuilder); $chart->setDataset(

$options[‘translator’]->trans(‘mautic.hellobundle.graph.line.visits’), $visits

); $data = $chart->render(); $data[‘name’] = $graph; $data[‘iconClass’] = ‘fa-tachometer’; $event->setGraph($graph, $data); break;

}

}

}

}

定义报告

Mautic 会派发 ReportEvents::REPORT_ON_BUILD 事件来定义一个报告。 在此事件中，插件会定义：

• 报告上下文

• 表格数据的可用列

• 表格数据的可用过滤器（默认为列）

• 可用的图表

列的定义

每个列数组可以包含以下属性：

Key	Type	Description
label	string	必需。 列的语言字符串。
type	string	必需。 列类型。
alias	string	返回值的别名。 与 formula 结合使用时很有用。
formula	string	SQL 公式，而不是一列。 例如：SUBSTRING_INDEX(e.type, '.', 1)。
link	string	将值转换为超链接的路由名称。 通常与实体的 ID 一起使用。 路由必须接受 objectAction 和 objectId 参数。

过滤器的定义

过滤器是可选的。 如果未定义，系统将使用列定义。 但是，过滤器可以提供其他选项，例如下拉列表。

以下是额外的过滤器键：

```

• • Key

    • Type

    • Description

    • • list

      • array

      • 当 type 为 select 时使用。为选择输入提供下拉选项。格式应为 value => label.

    • • operators

      • array

      • 允许此过滤器使用的自定义运算符列表。

        请参阅 :xref: 的 MauticReportBuilder 类中的 OPERATORS 常量，以获取示例。

生成 QueryBuilder

当 Mautic 生成并显示报告时，会触发 ReportEvents::REPORT_ON_GENERATE 事件。使用此事件来定义生成表数据的 QueryBuilder 对象。

• 使用 $event->checkContext() 来确定请求的报告是否属于订阅者。

• 通过以下方式获取 Doctrine 的 DBAL 层的 QueryBuilder：$qb = $event->getQueryBuilder();.

ReportGeneratorEvent 类提供了几个辅助函数，用于追加常见的关联关系（例如类别、联系人和 IP 地址）的连接。有关更多详细信息，请参阅 :xref: 的 Mautic ReportGeneratorEvent 类。

生成图表

当 Mautic 生成报告的图表时，会触发 ReportEvents::REPORT_ON_GRAPH_GENERATE 事件。使用此事件来定义视觉数据表示形式。

• 使用 $event->checkContext() 验证报告上下文。

• 克隆基础 QueryBuilder 以安全地操作多个图表的查询。

• 使用 LineChart 和 ChartQuery 类来生成和渲染图表数据。

有关支持的图表类型和选项，请参阅 ChartQuery 和 LineChart 辅助类 - 这些类位于 :xref: 的 Mautic CoreBundle Chart Helpers 命名空间中。