chromed

Back Back Up Advanced Editor

<?php

namespace WPForms\Admin\Forms;

use WP_Post;
use WPForms\Admin\Forms\Table\Facades\Columns;
use WPForms\Analytics\Analytics as AnalyticsFeature;
use WPForms\Pro\Analytics\Analytics as ProAnalytics;

/**
 * Analytics columns on the Forms Overview page.
 *
 * Registers three new columns (Views, Interactions, Conversion), pre-fetches
 * their data via a bulk query, and renders cells.
 *
 * @since 2.0.0
 */
class Analytics {

/**
	 * Pre-fetched stats keyed by form ID.
	 *
	 * @since 2.0.0
	 *
	 * @var array
	 */
	private $stats = [];

/**
	 * Start the engine.
	 *
	 * @since 2.0.0
	 */
	public function init(): void {

$this->hooks();
	}

/**
	 * Register WordPress hooks.
	 *
	 * @since 2.0.0
	 */
	private function hooks(): void {

add_filter( 'wpforms_admin_forms_table_facades_columns_data', [ $this, 'register_columns' ] );
		add_filter( 'wpforms_overview_table_column_value', [ $this, 'render_column' ], 10, 3 );
		add_action( 'wpforms_admin_forms_list_table_prepare_items_after', [ $this, 'prefetch_stats' ] );
		add_filter( 'default_hidden_columns', [ $this, 'set_column_defaults' ], 11, 2 );
		add_action( 'wpforms_admin_header_after', [ $this, 'render_feature_tooltip' ] );

// Priority 10 runs after the core row actions (priority 9), so "Entries" is
		// already present to insert "Analytics" after.
		add_filter( 'wpforms_overview_row_actions', [ $this, 'add_analytics_row_action' ], 10, 2 );
	}

/**
	 * Add an "Analytics" row action after "Entries" in the Forms Overview table.
	 *
	 * Pro/Elite only — Lite users see the upgrade badge in the analytics columns
	 * instead. Gated by the same per-form capability as the analytics page.
	 *
	 * @since 2.0.0
	 *
	 * @param array|mixed $row_actions Row action links keyed by slug.
	 * @param WP_Post     $form        Form object.
	 *
	 * @return array
	 */
	public function add_analytics_row_action( $row_actions, $form ): array {

$row_actions = (array) $row_actions;

if ( ! wpforms()->is_pro() || ! ProAnalytics::is_allowed() || ! wpforms_current_user_can( 'view_entries_form_single', $form->ID ) ) {
			return $row_actions;
		}

$analytics = [
			'analytics' => sprintf(
				'<a href="%s" title="%s">%s</a>',
				esc_url(
					add_query_arg(
						[
							'page'    => 'wpforms-analytics',
							'form_id' => $form->ID,
						],
						admin_url( 'admin.php' )
					)
				),
				esc_attr__( 'View analytics', 'wpforms-lite' ),
				esc_html__( 'Analytics', 'wpforms-lite' )
			),
		];

// Insert after Entries (or append when absent), mirroring register_columns().
		$position = array_search( 'entries', array_keys( $row_actions ), true );
		$position = $position !== false ? $position + 1 : count( $row_actions );

return array_slice( $row_actions, 0, $position, true )
			+ $analytics
			+ array_slice( $row_actions, $position, null, true );
	}

/**
	 * Register analytics columns (Views, Interactions, Conversion).
	 *
	 * Inserts three analytics columns immediately after the Entries column when
	 * it exists, or appends them at the end of the columns list otherwise.
	 *
	 * Hooks: wpforms_admin_forms_table_facades_columns_data (filter).
	 *
	 * @since 2.0.0
	 *
	 * @param array|mixed $columns Existing columns data.
	 *
	 * @return array
	 */
	public function register_columns( $columns ): array {

$columns = (array) $columns;

$analytics_columns = [
			'analytics_views'        => [
				'label' => esc_html__( 'Views', 'wpforms-lite' ),
			],
			'analytics_interactions' => [
				'label' => esc_html__( 'Interactions', 'wpforms-lite' ),
			],
			'analytics_conversion'   => [
				'label' => esc_html__( 'Conversion', 'wpforms-lite' ),
			],
		];

$position = array_search( 'entries', array_keys( $columns ), true );
		$position = $position !== false ? $position + 1 : count( $columns );

return array_slice( $columns, 0, $position, true )
			+ $analytics_columns
			+ array_slice( $columns, $position, null, true );
	}

/**
	 * Render an analytics column cell.
	 *
	 * Dispatches to the appropriate private renderer based on $column_name.
	 * Returns the original $value unchanged when $form is not a WP_Post instance
	 * or when $column_name does not match an analytics column.
	 *
	 * Hooks: wpforms_overview_table_column_value (filter).
	 * Matches the signature used by Forms\Locator::column_value — no strict type
	 * hints on filter callback params.
	 *
	 * @since 2.0.0
	 *
	 * @param mixed  $value       Current cell value (pass-through for unknown columns).
	 * @param mixed  $form        Form post object; must be WP_Post to render.
	 * @param string $column_name Column identifier.
	 *
	 * @return mixed
	 */
	public function render_column( $value, $form, string $column_name ) {

if ( ! $form instanceof WP_Post ) {
			return $value;
		}

$form_id = (int) $form->ID;

switch ( $column_name ) {
			case 'analytics_views':
				$value = $this->render_views( $form_id );
				break;

case 'analytics_interactions':
				$value = $this->render_interactions( $form_id );
				break;

case 'analytics_conversion':
				$value = $this->render_conversion( $form_id );
				break;
		}

return $value;
	}

/**
	 * Bulk-fetch stats for all forms on the current overview page.
	 *
	 * Retrieves views and submissions for every form in a single DB call and
	 * stores the result in $stats keyed by form ID. No-ops when $form_ids is
	 * empty or non-array, or when the analytics DB object is unavailable.
	 *
	 * Hooks: wpforms_admin_forms_list_table_prepare_items_after (action). The
	 * parameter is untyped because the action's payload depends on the dispatcher
	 * (`ListTable::prepare_items()`), which may pass a non-array if the items
	 * lookup degraded - keeping this method tolerant prevents a fatal in that path.
	 *
	 * @since 2.0.0
	 *
	 * @param mixed $form_ids Form IDs (expected: int[]).
	 */
	public function prefetch_stats( $form_ids ): void {

if ( ! is_array( $form_ids ) || empty( $form_ids ) ) {
			$this->stats = [];

return;
		}

$db = wpforms()->obj( 'analytics_db' );

if ( ! $db ) {
			$this->stats = [];

return;
		}

$this->stats = $db->get_overview_stats( $form_ids );
	}

/**
	 * Hide the Shortcode column by default on the Forms Overview screen.
	 *
	 * Hooks: default_hidden_columns (filter, priority 11). Runs after
	 * ListTable::default_hidden_columns() (priority 10), receives its output,
	 * gates on the same screen ID + Columns::has_selected_columns() conditions,
	 * and appends 'shortcode' to keep the analytics columns visually grouped
	 * after Entries on first visit.
	 *
	 * @since 2.0.0
	 *
	 * @param mixed $hidden Hidden columns array (filter input may be non-array).
	 * @param mixed $screen WP_Screen-like object for the current admin screen.
	 *
	 * @return array
	 */
	public function set_column_defaults( $hidden, $screen ): array {

$hidden = (array) $hidden;

if ( ! is_object( $screen ) || ! isset( $screen->id ) || $screen->id !== 'toplevel_page_wpforms-overview' ) {
			return $hidden;
		}

if ( Columns::has_selected_columns() ) {
			return $hidden;
		}

$hidden[] = 'shortcode';

return $hidden;
	}

/**
	 * Render the Views column cell.
	 *
	 * @since 2.0.0
	 *
	 * @param int $form_id Form ID.
	 *
	 * @return string
	 */
	private function render_views( int $form_id ): string {

$views = $this->stats[ $form_id ]['views'] ?? null;

if ( $views === null ) {
			return '—';
		}

$value = number_format_i18n( (int) $views );

if ( ! wpforms()->is_pro() ) {
			return $value;
		}

if ( ! ProAnalytics::is_allowed() ) {
			return $value;
		}

return $this->build_analytics_link( $form_id, 'views', $value );
	}

/**
	 * Render the Interactions column cell.
	 *
	 * On Lite, returns the Pro upgrade badge. On Pro with stats present,
	 * returns a link to the Analytics page for the given form.
	 * Returns a dash on Pro when the form has no stats.
	 *
	 * @since 2.0.0
	 *
	 * @param int $form_id Form ID.
	 *
	 * @return string
	 */
	private function render_interactions( int $form_id ): string {

if ( ! wpforms()->is_pro() || ! ProAnalytics::is_allowed() ) {
			return $this->render_pro_badge( __( 'Upgrade to Pro to unlock Interactions', 'wpforms-lite' ) );
		}

$interactions = $this->stats[ $form_id ]['interactions'] ?? null;

if ( $interactions === null ) {
			return '—';
		}

return $this->build_analytics_link( $form_id, 'interactions', number_format_i18n( (int) $interactions ) );
	}

/**
	 * Render the Pro upgrade teaser for locked columns (Lite only).
	 *
	 * Outputs a blurred-value image wrapped in the education-modal link, so the
	 * locked metric reads as "there is data here, upgrade to see it". Both gated
	 * columns (Interactions, Conversion) share a single `analytics-upgrade`
	 * utm_content value. The `data-utm-medium` attribute is read by the Lite
	 * education modal JS to override the upgrade URL's utm_medium with
	 * `forms-overview`.
	 *
	 * @since 2.0.0
	 *
	 * @param string $tooltip Hover title naming the locked metric (e.g. "Upgrade to Pro to unlock Interactions").
	 *
	 * @return string
	 */
	private function render_pro_badge( string $tooltip ): string {

return sprintf(
			'<a href="#" class="education-modal" title="%5$s" data-action="upgrade" data-name="%1$s" data-license="pro" data-banner-src="%2$s" data-utm-medium="forms-overview" data-utm-content="analytics-upgrade"><img src="%3$s" alt="%4$s" width="48" height="27"></a>',
			esc_attr__( 'Form Analytics', 'wpforms-lite' ),
			esc_url( WPFORMS_PLUGIN_URL . 'assets/images/education/analytics-preview.png' ),
			esc_url( WPFORMS_PLUGIN_URL . 'assets/images/education/blurred-value.svg' ),
			esc_attr__( 'Upgrade to Pro', 'wpforms-lite' ),
			esc_attr( $tooltip )
		);
	}

/**
	 * Render the Conversion column cell.
	 *
	 * @since 2.0.0
	 *
	 * @param int $form_id Form ID.
	 *
	 * @return string
	 */
	private function render_conversion( int $form_id ): string {

if ( ! wpforms()->is_pro() || ! ProAnalytics::is_allowed() ) {
			return $this->render_pro_badge( __( 'Upgrade to Pro to unlock Conversion Rate', 'wpforms-lite' ) );
		}

$value = $this->calculate_conversion_value( $this->stats[ $form_id ] ?? null );

if ( $value === null ) {
			return '—';
		}

return $this->build_analytics_link( $form_id, 'conversion', $value );
	}

/**
	 * Compute the formatted conversion-rate string for a form's stats.
	 *
	 * @since 2.0.0
	 *
	 * @param array|null $stats Pre-fetched stats for the form, or null when absent.
	 *
	 * @return string|null Formatted "NN.N%" value, or null when stats are missing or views are zero.
	 */
	private function calculate_conversion_value( ?array $stats ): ?string {

if ( ! $stats ) {
			return null;
		}

$views       = (int) ( $stats['views'] ?? 0 );
		$submissions = (int) ( $stats['submissions'] ?? 0 );

if ( $views <= 0 ) {
			return null;
		}

$rate = round( ( $submissions / $views ) * 100, 1 );

return number_format_i18n( $rate, 1 ) . '%';
	}

/**
	 * Build the Analytics-page link markup for a populated column cell (Pro).
	 *
	 * @since 2.0.0
	 *
	 * @param int    $form_id      Form ID the link targets.
	 * @param string $css_modifier Column suffix for the link CSS class.
	 * @param string $value        Display value (escaped on output).
	 *
	 * @return string Anchor markup pointing at the form's Analytics page.
	 */
	private function build_analytics_link( int $form_id, string $css_modifier, string $value ): string {

return sprintf(
			'<a href="%1$s" class="wpforms-analytics-%2$s-link">%3$s</a>',
			esc_url( admin_url( 'admin.php?page=wpforms-analytics&form_id=' . $form_id ) ),
			esc_attr( $css_modifier ),
			esc_html( $value )
		);
	}

/**
	 * Render the Form Analytics feature-discovery tooltip on Forms Overview.
	 *
	 * @since 2.0.0
	 */
	public function render_feature_tooltip(): void {

if ( ! $this->should_render_feature_tooltip() ) {
			return;
		}

$tooltip = wpforms()->obj( 'education_feature_tooltip' );

if ( ! $tooltip ) {
			return;
		}

/**
		 * Filter the Learn More URL for the Form Analytics feature-discovery tooltip.
		 *
		 * @since 2.0.0
		 *
		 * @param string $url Default UTM-wrapped wpforms.com URL.
		 */
		$learn_more_url = apply_filters(
			'wpforms_admin_forms_analytics_render_feature_tooltip_learn_more_url',
			wpforms_utm_link(
				AnalyticsFeature::DOC_URL,
				'forms-overview',
				'Analytics Feature Tooltip'
			)
		);

$button = wpforms()->is_pro() && ProAnalytics::is_allowed()
			? [
				'text'    => esc_html__( 'View Analytics', 'wpforms-lite' ),
				'url'     => add_query_arg( 'page', 'wpforms-analytics', admin_url( 'admin.php' ) ),
				'classes' => 'wpforms-btn wpforms-btn-sm wpforms-btn-orange wpforms-education-feature-tooltip-view',
			]
			: [
				'text'    => esc_html__( 'Upgrade to Pro', 'wpforms-lite' ),
				'url'     => '#',
				'classes' => 'wpforms-btn wpforms-btn-sm wpforms-btn-orange education-modal',
				'data'    => [
					'name'        => esc_attr__( 'Form Analytics', 'wpforms-lite' ),
					'license'     => 'pro',
					'action'      => 'upgrade',
					'banner-src'  => WPFORMS_PLUGIN_URL . 'assets/images/education/analytics-preview.png',
					'utm-medium'  => 'forms-overview',
					'utm-content' => 'analytics-feature-tooltip',
				],
			];

$tooltip->render(
			[
				'title'          => esc_html__( 'Form Analytics', 'wpforms-lite' ),
				'badge'          => esc_html__( 'NEW', 'wpforms-lite' ),
				'text'           => esc_html__( 'Monitor views, conversions, and field-level activity to optimize performance.', 'wpforms-lite' ),
				'section'        => 'analytics-feature-discovery',
				'learn_more_url' => $learn_more_url,
				'button'         => $button,
			]
		);
	}

/**
	 * Whether the Form Analytics feature-discovery tooltip should render.
	 *
	 * Gates on the current admin screen and the per-user dismissal flag stored
	 * in the `wpforms_dismissed` user meta map.
	 *
	 * @since 2.0.0
	 *
	 * @return bool True when the tooltip should render on this request.
	 */
	private function should_render_feature_tooltip(): bool {

$screen    = get_current_screen();
		$screen_id = $screen->id ?? '';

if ( ! $screen || $screen_id !== 'toplevel_page_wpforms-overview' ) {
			return false;
		}

$dismissed = (array) get_user_meta( get_current_user_id(), 'wpforms_dismissed', true );

return empty( $dismissed['edu-analytics-feature-discovery'] );
	}
}