namespace, '/' . $this->rest_base . '/overview', [ [ 'methods' => WP_REST_Server::READABLE, 'callback' => [ $this, 'get_overview_data' ], 'permission_callback' => [ $this, 'permissions_check' ], 'args' => $this->get_collection_params(), ], ] ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/fallbacks', [ [ 'methods' => WP_REST_Server::READABLE, 'callback' => [ $this, 'get_fallback_data' ], 'permission_callback' => [ $this, 'permissions_check' ], 'args' => $this->get_collection_params(), ], ] ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/filter-options', [ [ 'methods' => WP_REST_Server::READABLE, 'callback' => [ $this, 'get_filter_options' ], 'permission_callback' => [ $this, 'permissions_check' ], ], ] ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/save-default-view', [ [ 'methods' => WP_REST_Server::CREATABLE, // POST 'callback' => [ $this, 'save_default_view' ], 'permission_callback' => [ $this, 'permissions_check' ], 'args' => [ 'view_params' => [ 'required' => true, 'type' => 'object', ], ], ], ] ); } /** * Saves the default view parameters for the current user. * * @param WP_REST_Request $request * @return WP_REST_Response|WP_Error */ public function save_default_view( WP_REST_Request $request ): WP_REST_Response|WP_Error { $user_id = get_current_user_id(); $params = $request->get_param( 'view_params' ); if ( empty( $params ) ) { if ( delete_user_meta( $user_id, 'adpresso_stats_default_view' ) ) { return new WP_REST_Response( [ 'success' => true, 'action' => 'deleted' ], 200 ); } return new WP_Error( 'rest_cannot_delete', __( 'Could not delete default view.', 'adpresso' ), [ 'status' => 500 ] ); } $sanitized_params = []; foreach ( $params as $key => $value ) { $sanitized_params[ sanitize_key( $key ) ] = sanitize_text_field( $value ); } update_user_meta( $user_id, 'adpresso_stats_default_view', $sanitized_params ); return new WP_REST_Response( [ 'success' => true, 'action' => 'saved', 'saved_view' => $sanitized_params ], 200 ); } /** * Pro: how often a fallback stood in, by reason and placement (DeliveryCounters, written by TrackingStorage). * * @param WP_REST_Request $request Request. * * @return WP_REST_Response|WP_Error */ public function get_fallback_data( WP_REST_Request $request ): WP_REST_Response|WP_Error { if ( ! Util::is_pro_active() ) { return new WP_Error( 'rest_forbidden', 'Fallback statistics need AdPresso Pro.', [ 'status' => 403 ] ); } $range_key = sanitize_key( (string) $request->get_param( 'range' ) ); $start_date = sanitize_text_field( (string) $request->get_param( 'start_date' ) ); $end_date = sanitize_text_field( (string) $request->get_param( 'end_date' ) ); if ( empty( $start_date ) || empty( $end_date ) ) { list( $start_date, $end_date ) = $this->calculate_dates_from_range( '' !== $range_key ? $range_key : 'last_30_days' ); } $start_date = $this->clamp_start_date( $start_date, $end_date ); $metrics = array_map( static fn( string $reason ): string => 'fallback_' . $reason, TrackingStorage::FALLBACK_REASONS ); $reasons = array_fill_keys( TrackingStorage::FALLBACK_REASONS, 0 ); $placements = []; foreach ( DeliveryCounters::totals_per_placement( $start_date, $end_date, $metrics ) as $placement_id => $hits ) { $title = (string) get_the_title( $placement_id ); $row = [ 'id' => (int) $placement_id, /* translators: %d: placement ID */ 'name' => '' !== $title ? $title : sprintf( __( 'Placement #%d', 'adpresso' ), $placement_id ), 'total' => 0, ]; foreach ( TrackingStorage::FALLBACK_REASONS as $reason ) { $count = (int) ( $hits[ 'fallback_' . $reason ] ?? 0 ); $row[ $reason ] = $count; $row['total'] += $count; $reasons[ $reason ] += $count; } $placements[] = $row; } usort( $placements, static fn( array $a, array $b ): int => $b['total'] <=> $a['total'] ); return new WP_REST_Response( [ 'start_date' => $start_date, 'end_date' => $end_date, 'total' => array_sum( $reasons ), 'reasons' => $reasons, 'placements' => $placements, ], 200 ); } /** * Delivers a list of all entities for the filter dropdown. * * @param WP_REST_Request $request * * @return WP_REST_Response */ public function get_filter_options( WP_REST_Request $request ): WP_REST_Response { $query_args = [ 'post_type' => [ Constants::POST_TYPE_AD, Constants::POST_TYPE_GROUP, Constants::POST_TYPE_PLACEMENT ], 'post_status' => 'any', 'posts_per_page' => -1, 'fields' => 'ids', ]; $query = new WP_Query( $query_args ); $options = [ 'ads' => [], 'groups' => [], 'placements' => [], ]; if ( $query->have_posts() ) { foreach ( $query->posts as $post_id ) { $post_type = get_post_type( $post_id ); $item = [ 'value' => $post_id, 'label' => get_the_title( $post_id ), ]; if ( $post_type === Constants::POST_TYPE_AD ) { $options['ads'][] = $item; } elseif ( $post_type === Constants::POST_TYPE_GROUP ) { $options['groups'][] = $item; } elseif ( $post_type === Constants::POST_TYPE_PLACEMENT ) { $options['placements'][] = $item; } } } return new WP_REST_Response( $options, 200 ); } /** * Permission check for the analytics endpoint. * * @param WP_REST_Request $request * * @return bool|WP_Error */ public function permissions_check( WP_REST_Request $request ): bool|WP_Error { if ( ! current_user_can( adpresso_get_capability( 'view_analytics' ) ) ) { return new WP_Error( 'rest_forbidden', 'You do not have permissions to view this data.', [ 'status' => 403 ] ); } return true; } /** * Gathers aggregated data for the dashboard. * * @param WP_REST_Request $request * @return WP_REST_Response */ public function get_overview_data( WP_REST_Request $request ): WP_REST_Response { global $wpdb; $stats_table = $wpdb->prefix . 'adpresso_stats'; $posts_table = $wpdb->prefix . 'posts'; $range_key = sanitize_key( $request->get_param( 'range' ) ?: 'last_30_days' ); $view_mode = sanitize_key( $request->get_param( 'view_mode' ) ?: 'date' ); $start_date = sanitize_text_field( $request->get_param( 'start_date' ) ); $end_date = sanitize_text_field( $request->get_param( 'end_date' ) ); if ( empty( $start_date ) || empty( $end_date ) ) { list( $start_date, $end_date ) = $this->calculate_dates_from_range( $range_key ?: 'last_30_days' ); } $start_date = $this->clamp_start_date( $start_date, $end_date ); $group_by = sanitize_key( $request->get_param( 'group_by' ) ?: 'day' ); $orderby = sanitize_key( $request->get_param( 'orderby' ) ?: 'impressions' ); $order = ( strtoupper( $request->get_param( 'order' ) ) === 'ASC' ) ? 'ASC' : 'DESC'; $filters = [ 'ads' => $request->get_param( 'filter_ads' ), 'groups' => $request->get_param( 'filter_groups' ), 'placements' => $request->get_param( 'filter_placements' ), ]; $where_clauses = []; $params = []; $where_clauses[] = 'stats.stat_date BETWEEN %s AND %s'; $params[] = $start_date; $params[] = $end_date; $filter_map = [ 'ads' => 'stats.ad_id', 'groups' => 'stats.group_id', 'placements' => 'stats.placement_id', ]; $simple_sort_columns = [ 'date' => 'date', 'name' => 'name', 'impressions' => 'impressions', 'clicks' => 'clicks', 'impressions_av' => 'impressions_av', ]; if ( isset( $simple_sort_columns[ $orderby ] ) ) { $orderby_sql = $simple_sort_columns[ $orderby ]; } elseif ( $orderby === 'ctr' ) { $orderby_sql = 'CASE WHEN SUM(stats.impressions) > 0 THEN (SUM(stats.clicks) / SUM(stats.impressions)) ELSE 0 END'; } elseif ( $orderby === 'viewability' && Util::is_pro_active() ) { $orderby_sql = 'CASE WHEN SUM(stats.impressions) > 0 THEN (SUM(stats.impressions_av) / SUM(stats.impressions)) ELSE 0 END'; } else { // Fallback $orderby_sql = 'impressions'; } // Prevent some orders when in the wrong view mode. if ( $view_mode !== 'date' && $orderby_sql === 'date' ) { $orderby_sql = 'impressions'; } if ( $view_mode === 'date' && $orderby_sql === 'name' ) { $orderby_sql = 'date'; } foreach ( $filters as $key => $value_string ) { // '0' is a real filter value (e.g. compare mode asking for "no group" rows), so no empty() here. if ( is_scalar( $value_string ) && '' !== (string) $value_string && isset( $filter_map[ $key ] ) ) { $ids = array_map( 'absint', explode( ',', (string) $value_string ) ); if ( empty( $ids ) ) { continue; } $placeholders = implode( ',', array_fill( 0, count( $ids ), '%d' ) ); $where_clauses[] = "{$filter_map[$key]} IN ($placeholders)"; $params = array_merge( $params, $ids ); } } $select_clause = 'SUM(stats.impressions) as impressions, SUM(stats.clicks) as clicks, SUM(stats.impressions_av) as impressions_av'; $join_clause = ''; $group_by_format = ''; $order_by_clause = sprintf( 'ORDER BY %s %s', $orderby_sql, $order ); switch ( $view_mode ) { case 'ads': $select_clause .= ', stats.ad_id, posts.post_title as name'; $join_clause = " LEFT JOIN {$posts_table} as posts ON stats.ad_id = posts.ID"; $group_by_clause = 'GROUP BY stats.ad_id, posts.post_title'; break; case 'groups': $select_clause .= ', stats.group_id, posts.post_title as name'; $join_clause = " LEFT JOIN {$posts_table} as posts ON stats.group_id = posts.ID"; $group_by_clause = 'GROUP BY stats.group_id, posts.post_title'; break; case 'placements': $select_clause .= ', stats.placement_id, posts.post_title as name'; $join_clause = " LEFT JOIN {$posts_table} as posts ON stats.placement_id = posts.ID"; $group_by_clause = 'GROUP BY stats.placement_id, posts.post_title'; break; case 'date': default: $group_by_format = match ( $group_by ) { 'week' => '%x-%v', 'month' => '%Y-%m', 'year' => '%Y', default => '%Y-%m-%d', }; $select_clause .= ', DATE_FORMAT(stats.stat_date, %s) AS date'; $group_by_clause = 'GROUP BY date'; break; } $where_string = 'WHERE ' . implode( ' AND ', $where_clauses ); $sql = "SELECT {$select_clause} FROM {$stats_table} as stats {$join_clause} {$where_string} {$group_by_clause} {$order_by_clause}"; if ( $view_mode !== 'date' ) { $sql .= ' LIMIT ' . self::ENTITY_ROW_LIMIT; } if ( $view_mode === 'date' ) { array_unshift( $params, $group_by_format ); } // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- Query prepared above. $prepared_sql = $wpdb->prepare( $sql, ...$params ); if ( $view_mode !== 'date' ) { $prepared_sql = str_replace( "'%s' as date,", '', $prepared_sql ); } // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- Query prepared above. $results = $wpdb->get_results( $prepared_sql, ARRAY_A ); if ( $view_mode === 'date' && ! empty( $start_date ) && ! empty( $end_date ) ) { // Rebuild results for faster access. $results_by_date = []; foreach ( $results as $row ) { $results_by_date[ $row['date'] ] = $row; } $results = []; // Create a new clean timeline by the group_by parameter $start = new \DateTime( $start_date ); $end = new \DateTime( $end_date ); $end->modify( '+1 day' ); // DatePeriod excludes the last day by default // Step from the bucket start, or a mid-bucket start skips the last (or a short) bucket. switch ( $group_by ) { case 'week': $start->setISODate( (int) $start->format( 'o' ), (int) $start->format( 'W' ) ); break; case 'month': $start->setDate( (int) $start->format( 'Y' ), (int) $start->format( 'm' ), 1 ); break; case 'year': $start->setDate( (int) $start->format( 'Y' ), 1, 1 ); break; } $interval_string = match ( $group_by ) { 'week' => 'P1W', 'month' => 'P1M', 'year' => 'P1Y', default => 'P1D', }; $interval = new \DateInterval( $interval_string ); $period = new \DatePeriod( $start, $interval, $end ); // Fill spaces with nulls foreach ( $period as $dt ) { $date_key = match ( $group_by ) { 'week' => $dt->format( 'o-W' ), // ISO year, like MySQL's %x-%v. 'month' => $dt->format( 'Y-m' ), 'year' => $dt->format( 'Y' ), default => $dt->format( 'Y-m-d' ), }; if ( isset( $results_by_date[ $date_key ] ) ) { $results[] = $results_by_date[ $date_key ]; } else { // Add a dummy entry for empty days. $results[] = [ 'date' => $date_key, 'impressions' => 0, 'clicks' => 0, 'impressions_av' => 0, ]; } } } // Data enrichment (e.g., CTR calculation) $data = array_map( function( $row ) { $impressions = (int) $row['impressions']; $clicks = (int) $row['clicks']; $impressions_av = (int) $row['impressions_av']; $row['impressions'] = $impressions; $row['clicks'] = $clicks; $row['ctr'] = ( $impressions > 0 ) ? ( $clicks / $impressions ) * 100 : 0; if ( Util::is_pro_active() ) { $row['impressions_av'] = $impressions_av; $row['viewability'] = ( $impressions > 0 && $impressions_av > 0 ) ? ( $impressions_av / $impressions ) * 100 : 0; } return $row; }, $results ); // The date timeline is rebuilt in date order above, so the requested sort is applied here. if ( 'date' === $view_mode ) { $data = $this->sort_date_rows( $data, (string) $orderby, $order ); } return new WP_REST_Response( $data, 200 ); } /** * Sorts date-view rows by a metric or the date; equal values stay in date order. * * @param array $rows Rows with 'date' and the metric columns. * @param string $orderby Requested column. * @param string $order 'ASC' or 'DESC'. * * @return array */ private function sort_date_rows( array $rows, string $orderby, string $order ): array { $metrics = [ 'impressions', 'clicks', 'ctr' ]; if ( Util::is_pro_active() ) { $metrics[] = 'impressions_av'; $metrics[] = 'viewability'; } $key = in_array( $orderby, $metrics, true ) ? $orderby : 'date'; usort( $rows, static function ( array $a, array $b ) use ( $key, $order ): int { $by_date = strcmp( (string) $a['date'], (string) $b['date'] ); $cmp = 'date' === $key ? $by_date : ( $a[ $key ] ?? 0 ) <=> ( $b[ $key ] ?? 0 ); if ( 'DESC' === $order ) { $cmp = -$cmp; } return 0 !== $cmp ? $cmp : $by_date; } ); return $rows; } /** * Caps the start date to MAX_RANGE_YEARS before the end date. * * @param string $start_date Y-m-d * @param string $end_date Y-m-d * * @return string */ private function clamp_start_date( string $start_date, string $end_date ): string { try { $earliest = ( new \DateTimeImmutable( $end_date ) )->modify( '-' . self::MAX_RANGE_YEARS . ' years' )->format( 'Y-m-d' ); } catch ( \Exception ) { return $start_date; } return $start_date < $earliest ? $earliest : $start_date; } /** * Helper function to calculate date ranges. * * @param string $range_key * @return array */ private function calculate_dates_from_range( string $range_key ): array { // The site's calendar day (stats are stored per site day), as a plain UTC date so day math has no DST. $today = new \DateTimeImmutable( current_datetime()->format( 'Y-m-d' ), new \DateTimeZone( 'UTC' ) ); $end_date = $today->format( 'Y-m-d' ); switch ( $range_key ) { case 'today': $start_date = $end_date; break; case 'yesterday': $start_date = $today->modify( '-1 day' )->format( 'Y-m-d' ); $end_date = $start_date; break; case 'last_7_days': $start_date = $today->modify( '-6 days' )->format( 'Y-m-d' ); break; case 'this_month': $start_date = $today->format( 'Y-m-01' ); break; case 'last_month': $start_date = $today->modify( 'first day of last month' )->format( 'Y-m-01' ); $end_date = $today->modify( 'last day of last month' )->format( 'Y-m-t' ); break; case 'this_quarter': $current_month = (int) $today->format( 'm' ); $current_quarter = (int) ceil( $current_month / 3 ); $start_month = ( ( $current_quarter - 1 ) * 3 ) + 1; $start_date = $today->setDate( (int) $today->format( 'Y' ), $start_month, 1 )->format( 'Y-m-d' ); break; case 'this_year': $start_date = $today->format( 'Y-01-01' ); break; case 'last_12_months': $start_date = $today->modify( '-12 months' )->format( 'Y-m-d' ); break; case 'ytd': // Year to Date $start_date = $today->format( 'Y-01-01' ); break; case 'last_30_days': default: $start_date = $today->modify( '-29 days' )->format( 'Y-m-d' ); break; } return [ $start_date, $end_date ]; } /** * Defines the expected parameters for the endpoint. */ public function get_collection_params(): array { $params = [ 'range' => [ 'description' => 'Date range preset key.', 'type' => 'string', 'enum' => [ 'custom', 'today', 'yesterday', 'last_7_days', 'this_month', 'last_month', 'this_quarter', 'this_year', 'last_12_months', 'last_30_days', 'ytd' ], 'default' => 'last_30_days', ], 'view_mode' => [ 'description' => 'Group data by entity type.', 'type' => 'string', 'enum' => [ 'date', 'ads', 'groups', 'placements' ], 'default' => 'date', ], 'orderby' => [ 'description' => 'Column to sort by.', 'type' => 'string', 'enum' => [ 'date', 'name', 'impressions', 'clicks', 'ctr', 'impressions_av', 'viewability' ], 'default' => 'impressions', ], 'order' => [ 'description' => 'Sort direction.', 'type' => 'string', 'enum' => [ 'asc', 'desc' ], 'default' => 'desc', ], 'start_date' => [ 'description' => 'Start date for the report (YYYY-MM-DD)', 'type' => 'string', 'format' => 'date', ], 'end_date' => [ 'description' => 'End date for the report (YYYY-MM-DD)', 'type' => 'string', 'format' => 'date', ], 'group_by' => [ 'description' => 'How to group the data.', 'type' => 'string', 'enum' => [ 'day', 'week', 'month', 'year' ], 'default' => 'day', ], ]; return apply_filters( 'adpresso_entities_collection_params', $params ); } }