Architecture

The Commerce Reporting module generates reports of orders in a "snapshot" fashion. Instead of querying Drupal's completely normalized data, a denormalized record is created for each report type. This provides a more concise and easier to manage model that simplifies querying and report generation.

Denormalized vs Normalized data

Drupal stores data in a very normalized fashion. In short, when data is normalized it fits well into a relational database across multiple tables and various references. If you think of an order, it has references to the customer, the customer's billing information, the order items, the purchased products on the order item, any promotions and coupons attached, and any other custom references. Building a report on this data would require combining all of those tables and constructing a very complex query.

Denormalized data brings that all in as close as possible, so you do not have to join any additional tables. What you need should be right there, present for querying. This format is easier to aggregate and extract.

The order report entity

This was accomplished by creating an Order Report entity which acts as a report record. It contains data about the order and is created whenever the order has been placed or is manually refreshed (such as after a refund, or another adjustment.) By using the entity system, data modeling, CRUD, querying, and other features are handled for us, instead of manually working with the database layer.

There are different kinds of reports that will need to be generated, each with their own record. Order reports are content entities and have bundles provided by plugins. These plugins define what fields (schema) are available and generate their report. This grants flexibility for custom reporting needs and a way to create different data "buckets" for various reporting requirements. Each report references the order, so it is possible to query across the different report types as well.

This was implemented in #2848145: Create the order report entity and #2918882: Use bundle plugins for reports.

The report type plugin

The report type plugin, as previously mentioned, defines different reports to be created. Bundle plugins are an API feature provided by the Entity module. It allows a content entity to use plugins to define bundles and fields for each bundle. Other examples of their usage are payment method types in Commerce itself.

Each report type is responsible for returning the field definitions for the report, attaching the data for the report from its source, and building the query for its report. The report type plugin is also responsible for creating the needed report entries and saving them. The order is passed to the plugin and it can generate report records for the order, its adjustments, its order items, or any other requirements.