Feature Description

Email_Reporting_Data.php

• Restructure data to pass in a structured way to the email template code

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

New Email_Report_Section_Builder class and Email_Report_Data_Section_Part datatype class are added within Email_Reporting namespace

• Reshapes report payloads into a compact, template-ready data model using a datatype class Email_Report_Data_Section with consistent keys across sections:
  • eg. section_key, title, labels, values, trends, date_range, dashboard_link.
  • Provides typed accessors/mutators and lightweight validation of required fields and value types.
• Localizes numbers, dates, and labels to the subscriber’s locale; does not return raw API responses.
• Excludes empty sections gracefully; if all sections are empty, returns an empty result so the generation can be skipped within the Worker class (which means no module-specific conditionals will be required in templates).

Implementation Brief

• Add Core\Email_Reporting\Email_Report_Data_Section_Part class

  • Constructor receives final, already-normalised values: section_key, title, labels, values, trends, date_range, dashboard_link and $user_locale
  • Validate that:
    • section_key and title are non-empty strings.
    • labels, values, and trends are arrays; coerce each element to strings after formatting.
    • date_range is either null or an array with startDate/endDate strings.
    • dashboard_link is a string or null.
  • Store the data as read-only properties and expose getters for them
  • Add an is_empty() method that returns true if values are all empty. The worker can use this before rendering.

• Add Core\Email_Reporting\Email_Report_Section_Builder

  • Accept instance of Context (for dashboard URLs) in constructor and set it as a class properties
  • Add normalization helpers - use number_format_i18n to localize numbers, and use wp_date() with Y-m-d format, and wp_timezone() as last parameter to localize dates. Helpers will be invoked in build_sections method which will invoke the calls after capturing the locale with switch_to_locale.
  • Add an array of label translations to map the $label string to the localized version. Like [ 'direct' => __( 'Direct', 'google-site-kit' ) ]. Anything without a mapping should fall back to the raw value.
  • Add format_metric_value method - re-use the implementation of the same method from the referenced PoC to format the metrics type correctly
  • Provide a helper format_dashboard_link( $module_slug ) that reuses existing module slug admin page mapping (e.g. sprintf( '%sgooglesitekit-dashboard#/module/%s', $context->get_admin_url( 'admin.php' ), $module_slug )
  • Add build_sections( $module_slug, $raw_payloads, $frequency, $user_locale ) method
    • Capture $switched_locale = switch_to_locale( $user_locale ) and wrap the entire build in try/finally { if ( $switched_locale ) restore_previous_locale(); }
    • Process the raw reports response $raw_payloads with helper methods and iterate the module payload:
      • Build a Email_Report_Data_Section_Part instance with normalized labels, values, trends, etc. and append to an array.
        • For each section, skip adding it to the array if required values are missing or all datapoints are empty (Email_Report_Data_Section_Part::is_empty).
        • Group sections by module slugs eq [analytics_4 => [Email_Report_Data_Section_Part, Email_Report_Data_Section_Part, ...]]
      • Map extracted/processed values to the Email_Report_Data_Section_Part parameters
        • title should match the Figma section title in the email template
        • section_key should be in the format {section_name}
        • labels should be extracted dimension headers
        • values should be metric values
        • trends should be computed difference based on comparison dates
        • Extract the start and end date (as well as comparison dates) from report_reference_dates meta field of email log CPT added in Create and register email reports post type and meta fields #11544, add a helper method in Google\Site_Kit\Core\Email_Reporting\Email_Log to retrieve this if not already present, and a method here that will handle computation and create date_range array
      • Return the final array containing Email_Report_Data_Section_Part objects
  • Add helper methods to process the raw payload - extract metricValues from totals, dimensions headers and metric values. Check includes/Modules/Analytics_4/Batch_Report_Processor.php class in the referenced PoC

Test Coverage

• Add basic test coverage for Email_Report_Data_Section_Part verifying that getters return received values and is_empty is returning true when values are empty
• Add tests for Email_Report_Section_Builder
  • For example - given a raw Analytics payload, build_sections() returns the expected array of Email_Report_Data_Section_Part objects (verify titles, keys, formatted values, links).
    • Sections with no metrics are filtered out

QA Brief

• No QA required as there are no user-facing changes in this issue.

Changelog entry

• Create email reporting data and section classes.