Enhancement/7602-parsing-custom-dimensions-report

includes/Core/Util/WP_Entity_Helpers.php

@@ -0,0 +1,75 @@
+<?php
+/**
+ * Class Google\Site_Kit\Core\Util\WP_Entity_Helpers
+ *
+ * @package   Google\Site_Kit\Core\Util
+ * @copyright 2023 Google LLC
+ * @license   https://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
+ * @link      https://sitekit.withgoogle.com
+ */
+
+namespace Google\Site_Kit\Core\Util;
+
+/**
+ * Utility class for fetching meta data for posts.
+ *
+ * @since n.e.x.t
+ * @access private
+ * @ignore
+ */
+class WP_Entity_Helpers {
+
+	/**
+	 * Gets the display name for a given user ID.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param int $user_id User ID of the user to get the display name of.
+	 * @return string Display name of the user for the given user ID.
+	 */
+	public static function get_user_display_name( $user_id ) {
+		$user = get_userdata( $user_id );
+		return $user->display_name;
+	}
+
+	/**
+	 * Gets the category names for a given array of category IDs.
+	 *
+	 * If no category is found for a given ID, the original ID is preserved in
+	 * the returned array.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param array $category_ids Array of IDs of categories to get names of.
+	 * @return array Array of category names (or their original IDs if no name is found).
+	 */
+	public static function get_category_names( $category_ids ) {
+		$category_names = array();
+		foreach ( $category_ids as $category_id ) {
+			$category_name    = get_cat_name( $category_id );
+			$category_names[] = empty( $category_name ) ? $category_id : $category_name;
+		}
+		return $category_names;
+	}
+
+	/**
+	 * Converts a string list of category IDs to a stringified array of their
+	 * category names.
+	 *
+	 * If no category is found for a given ID, the original ID is preserved in
+	 * the returned string.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param string $category_ids_string Comma separated string list of IDs of categories to get names of.
+	 * @return string JSON encoded string of comma separated category names (or their original IDs if no name is found).
+	 */
+	public static function parse_category_names( $category_ids_string ) {
+		$category_ids = json_decode( '[' . $category_ids_string . ']', true );
+
+		$category_names = self::get_category_names( $category_ids );
+
+		return wp_json_encode( $category_names );
+	}
+
+}

includes/Modules/Analytics_4.php

@@ -91,6 +91,13 @@ final class Analytics_4 extends Module
 	 */
 	const MODULE_SLUG = 'analytics-4';
 
+	/**
+	 * Custom dimensions tracked by Site Kit
+	 */
+	const CUSTOM_EVENT_PREFIX              = 'customEvent:';
+	const CUSTOM_DIMENSION_POST_AUTHOR     = 'googlesitekit_post_author';
+	const CUSTOM_DIMENSION_POST_CATEGORIES = 'googlesitekit_post_categories';
+
 	/**
 	 * Registers functionality through WordPress hooks.
 	 *

includes/Modules/Analytics_4/Report/Response.php

@@ -11,6 +11,7 @@
 namespace Google\Site_Kit\Modules\Analytics_4\Report;
 
 use Google\Site_Kit\Core\REST_API\Data_Request;
+use Google\Site_Kit\Modules\Analytics_4;
 use Google\Site_Kit\Modules\Analytics_4\Report;
 use Google\Site_Kit_Dependencies\Google\Service\AnalyticsData\DateRange as Google_Service_AnalyticsData_DateRange;
 use Google\Site_Kit_Dependencies\Google\Service\AnalyticsData\Row as Google_Service_AnalyticsData_Row;
@@ -42,6 +43,8 @@ public function parse_response( Data_Request $data, $response ) {
 			return $response;
 		}
 
+		$response = $this->parse_custom_dimensions( $response );
+
 		// Get report dimensions and return early if there is either more than one dimension or
 		// the only dimension is not "date".
 		$dimensions = $this->parse_dimensions( $data );
@@ -117,6 +120,51 @@ function( $date ) use ( &$rows, $existing_rows, $ranges_count, $metric_headers,
 		return $response;
 	}
 
+	/**
+	 * Converts the IDs of any custom dimensions within the response into their respective display names.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param Google_Service_AnalyticsData_RunReportResponse $response Request response that may contain custom dimensions.
+	 * @return Google_Service_AnalyticsData_RunReportResponse Response with any IDs of custom dimensions converted to their display names.
+	 */
+	protected function parse_custom_dimensions( $response ) {
+		if ( empty( $response['rows'] ) ) {
+			return $response;
+		}
+
+		// Create a map of any custom dimension to its equivalent parsing function to avoid
+		// looping through report rows multiple times below.
+		$custom_dimension_map = array();
+		foreach ( $response['dimensionHeaders'] as $dimension_key => $dimension ) {
+			if ( Analytics_4::CUSTOM_EVENT_PREFIX . Analytics_4::CUSTOM_DIMENSION_POST_AUTHOR === $dimension['name'] ) {
+				$custom_dimension_map[ $dimension_key ] = array( 'Google\\Site_Kit\\Core\\Util\\WP_Entity_Helpers', 'get_user_display_name' );
+			}
+
+			if ( Analytics_4::CUSTOM_EVENT_PREFIX . Analytics_4::CUSTOM_DIMENSION_POST_CATEGORIES === $dimension['name'] ) {
+				$custom_dimension_map[ $dimension_key ] = array( 'Google\\Site_Kit\\Core\\Util\\WP_Entity_Helpers', 'parse_category_names' );
+			}
+		}
+
+		if ( empty( $custom_dimension_map ) ) {
+			return $response;
+		}
+
+		foreach ( $response['rows'] as &$row ) {
+			foreach ( $custom_dimension_map as $dimension_key => $callable ) {
+				$dimension_value = $row['dimensionValues'][ $dimension_key ]->getValue();
+				if ( '(not set)' === $dimension_value ) {
+					continue;
+				}
+
+				$new_dimension_value = call_user_func( $callable, $dimension_value );
+				$row['dimensionValues'][ $dimension_key ]->setValue( $new_dimension_value );
+			}
+		}
+
+		return $response;
+	}
+
 	/**
 	 * Gets the response row key composed from the date and the date range index values.
 	 *

tests/phpunit/integration/Core/Util/WP_Entity_HelpersTest.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * WP_Entity_HelpersTest
+ *
+ * @package   Google\Site_Kit\Tests\Core\Util
+ * @copyright 2023 Google LLC
+ * @license   https://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
+ * @link      https://sitekit.withgoogle.com
+ */
+
+namespace Google\Site_Kit\Tests\Core\Util;
+
+use Google\Site_Kit\Core\Util\WP_Entity_Helpers;
+use Google\Site_Kit\Tests\TestCase;
+
+/**
+ * @group Util
+ */
+class WP_Entity_HelpersTest extends TestCase {
+
+	public function test_get_user_display_name() {
+		$test_user_id = $this->factory()->user->create( array( 'display_name' => 'test display name' ) );
+		$this->assertEquals( 'test display name', WP_Entity_Helpers::get_user_display_name( $test_user_id ) );
+	}
+
+	public function test_parse_category_names__mixed_values() {
+		$category_with_number = $this->factory()->category->create( array( 'name' => '2' ) );
+		$category_with_commas = $this->factory()->category->create( array( 'name' => 'Category,with,commas' ) );
+		$normal_category      = $this->factory()->category->create( array( 'name' => 'Normal Category' ) );
+		$category_ids_string  = implode( ',', array( $category_with_number, $category_with_commas, 1955, $normal_category ) ); // 1955 would be a non-existent category
+
+		$this->assertEquals(
+			'["2","Category,with,commas",1955,"Normal Category"]',
+			WP_Entity_Helpers::parse_category_names( $category_ids_string )
+		);
+	}
+
+	public function test_parse_category_names__single_value() {
+		$this->assertEquals(
+			'["Uncategorized"]',
+			WP_Entity_Helpers::parse_category_names( '1' )
+		);
+	}
+
+}