docs: migrated the Reports component from the old docs to the new docs by OfficialJhimmy · Pull Request #238 · mautic/developer-documentation-new

OfficialJhimmy · 2025-04-14T15:45:41Z

No description provided.

…e new documentation

OfficialJhimmy · 2025-04-15T09:34:28Z

This pull request migrates over the documentation for the Reports Component in the reStructuredText (RST) format. It addresses #199.

RCheesley

Thanks for making a start at this @OfficialJhimmy - there's a lot of Vale fixes to address and probably more lurking beneath your use of vale off.

Please remove all of those, and we'll tell you where to use it if it's absolutely necessary.

Shout if you need some help running Vale in your editor, it should have picked all of these up while you were typing!

docs/components/reports.rst

adiati98 · 2026-01-16T20:55:25Z

docs/components/reports.rst

+Example: HelloWorld Report Subscriber
+=====================================
+
+.. vale on
+
+Below is an example Plugin file located at ``plugins\HelloWorldBundle\EventListener\ReportSubscriber.php``.
+
+This file subscribes to Report events and provides custom logic for adding new tables, columns, filters, and graphs.


This part is not available in the original version. Content-wise, is this correct?

I don't know, one for @mautic/core-team to review.

@mautic/core-team please refer to this live preview page for easy view:
https://mautic-developer--238.org.readthedocs.build/en/238/components/reports.html

And here's the original version:
https://github.com/mautic/developer-documentation/blob/main/source/includes/_plugin_extending_reports.md

adiati98 · 2026-01-16T20:56:28Z

docs/components/reports.rst

+.. code-block:: php
+
+    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;
+
+    class ReportSubscriber extends CommonSubscriber
+    {
+        public static function getSubscribedEvents()
+        {
+            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)
+        {
+            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', 'mautic.hellobundle.graph.line.visits');
+            }
+        }
+
+        public function onReportGenerate(ReportGeneratorEvent $event)
+        {
+            $context = $event->getContext();
+            if ($context == 'worlds') {
+                $qb = $event->getQueryBuilder();
+                $qb->from(MAUTIC_TABLE_PREFIX . 'worlds', 'w');
+                $event->addCategoryLeftJoin($qb, 'w');
+                $event->setQueryBuilder($qb);
+            }
+        }
+
+        public function onReportGraphGenerate(ReportGraphEvent $event)
+        {
+            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;
+                }
+            }
+        }
+    }


The code-block here is different with the original one. This one doesn't have comments. Do we want to follow the original or use this one?

Please refer to the original version here: https://github.com/mautic/developer-documentation/blob/main/source/includes/_plugin_extending_reports.md#extending-reports

One for @mautic/core-team to discuss/review.

adiati98 · 2026-01-16T21:11:08Z

docs/components/reports.rst

+To add and render custom Reports in Mautic, your Plugin needs to listen to three events:

+* ``\Mautic\ReportBundle\ReportEvents::REPORT_ON_BUILD``
+* ``ReportEvents::REPORT_ON_GENERATE``
+* ``ReportEvents::REPORT_ON_GRAPH_GENERATE``
+
+This guide walks you through defining a custom Report, generating Report data, and rendering graphs.
+
+.. vale off
+
+Defining the Report
+*******************
+
+.. vale on
+
+Use the ``ReportEvents::REPORT_ON_BUILD`` event to define:
+
+* The Report context
+* Available columns
+* Available filters - defaults to columns
+* Available graphs


In the original version, there's no introduction.

Also, the Defining the Report section is different. Which one should we use? Please refer to original one here: https://github.com/mautic/developer-documentation/blob/main/source/includes/_plugin_extending_reports.md#defining-the-report

For @mautic/core-team to review/consider.

I don't understand the question. I also think this is getting too deep into the weeds of code. A developer (my personal view) rather study the actual code. Looks at the event class and knows exactly what it can do. I think it's OK to mention the event, but I wouldn't go too deep. The internal implementation changes in time and then it's hard to keep the docs up to date.

I think the original poster elaborate the section more by adding an introduction. Would getting back to the original work better?

Here's the original version of this section:
https://github.com/mautic/developer-documentation/blob/main/source/includes/_plugin_extending_reports.md#defining-the-report

Yep, I don't see an issue in the original

erinlefeyijimi added 2 commits April 14, 2025 16:44

docs: migrated the Reports component from the old docs to the new docs

6eaa9a3

docs: migrated the Reports component from the old documentation to th…

676a03f

…e new documentation

RCheesley self-requested a review April 22, 2025 08:45

favour-chibueze added the writetechhub Pull requests from writetechhub's team label Apr 22, 2025

RCheesley requested changes Apr 24, 2025

View reviewed changes

chore: addresed comments

e6ef5b6

favour-chibueze assigned OfficialJhimmy May 19, 2025

erinlefeyijimi and others added 4 commits May 27, 2025 08:41

docs: migrated the Stages component from the old docs to the new docs

19662e0

docs:migrated the Stages Component from the old docs to the new docs

daa5b73

Merge branch '5.x' into feyijimi-new-wth

fe1e57c

Merge branch '5.x' into feyijimi-new-wth

f50e61b

adiati98 requested a review from a team as a code owner January 9, 2026 22:14

adiati98 requested review from adiati98 and favour-chibueze and removed request for a team January 9, 2026 22:14

adiati98 added 3 commits January 16, 2026 21:41

fix: rst format

dff36f2

address vale warnings

12495d3

address vale warnings

3228881

adiati98 reviewed Jan 19, 2026

View reviewed changes

Merge branch '5.x' into feyijimi-new-wth

0e5fbd3

adiati98 added this to Mautic's No/Low/Code Tasks Feb 5, 2026

adiati98 moved this to 🕰️ In progress in Mautic's No/Low/Code Tasks Feb 5, 2026

Conversation

OfficialJhimmy commented Apr 14, 2025

Uh oh!

OfficialJhimmy commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RCheesley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

OfficialJhimmy commented Apr 15, 2025 •

edited

Loading

adiati98 Jan 20, 2026 •

edited

Loading