debug_array] */ private static array $debug_log = []; /** @var bool Whether a L3-token is active. */ private static bool $token_active = false; /** @var int[] IDs of placements where the output hook has been triggered. * This is used to track which placements have actually rendered content on the frontend. */ private static array $output_triggered_placements = []; /** * @var array Unique reasons */ private static array $js_forcing_reasons = []; /** * @var array> JS-forcing reasons per placement ID, keyed by source. */ private static array $placement_js_reasons = []; /** @var int|string|null Placement the pipeline is currently deciding SSR/JS for, see set_current_placement(). */ private static $current_placement_id = null; /** * Adds the necessary hooks to WordPress to enable debugging. * Enables the debug mode only for users with the correct capabilities. * * @return void */ public static function hooks(): void { if ( ! self::is_active( 1 ) || ! self::debug_mode_active_for_user() ) { return; } // Enable Admin Bar for Level 3 (Support Token) even if not logged in. if ( self::$level === 3 && ! is_user_logged_in() ) { add_filter( 'show_admin_bar', '__return_true' ); } add_action( 'wp', [ self::class, 'reset_logs' ], 4 ); add_action( 'admin_bar_menu', [ self::class, 'setup_admin_bar_debug_nodes' ], 99 ); add_filter( 'body_class', [ self::class, 'add_debug_body_class' ] ); add_action( 'wp_enqueue_scripts', [ self::class, 'enqueue_assets' ] ); // Add SEO/caching hooks if ( self::$level >= 1 ) { add_action( 'send_headers', [ self::class, 'add_cache_bypass_headers' ] ); } if ( self::$level === 3 && ! is_user_logged_in() ) { add_action( 'wp_head', [ self::class, 'add_noindex_tag' ] ); } } /** * Determines whether the debug mode is active for the current user. * * @return bool */ private static function debug_mode_active_for_user(): bool { if ( self::$level === 3 ) { return true; } $only_admin = Settings::get_setting( 'debug_mode_user', false ); if ( $only_admin && ! current_user_can( self::get_user_cap() ) ) { return false; } return true; } /** * Capability required to see debug output. The legacy filter stays for backwards compatibility. * * @return string */ private static function get_user_cap(): string { return apply_filters( 'adpresso_debug_mode_user_cap', adpresso_get_capability( 'view_debug' ) ); } /** * Determines the debug level based on the setting and request parameters. * * @return int */ private static function determine_debug_level(): int { $level = (int) Settings::get_setting( 'debug_mode', 1 ); // L3: Highest priority $token = Params::get()->getString( 'adpresso_token' ); if ( $level >= 3 && $token !== '' ) { if ( DebugTokenManager::validate_token( $token ) ) { self::$token_active = true; return 3; } } // L2 if ( $level >= 2 || ( defined( 'WP_DEBUG' ) && WP_DEBUG === true ) ) { if ( current_user_can( self::get_user_cap() ) ) { return 2; } } // L1 if ( $level >= 1 ) { if ( current_user_can( self::get_user_cap() ) ) { return 1; } } return 0; } /** * Resets the request-specific logs. * * @return void */ public static function reset_logs(): void { self::$debug_log = []; self::$output_triggered_placements = []; self::$js_forcing_reasons = []; self::$placement_js_reasons = []; self::$current_placement_id = null; } /** * Resets every piece of per-request state, including the resolved debug level. * * @return void */ public static function reset_request_state(): void { self::$level = self::LEVEL_UNRESOLVED; self::$token_active = false; self::reset_logs(); } /** * Returns whether the debugger is active for the current request. * * @param int $required_level The minimum required debug level. * * @return bool */ public static function is_active( int $required_level = 1 ): bool { if ( self::$level === self::LEVEL_UNRESOLVED ) { self::$level = self::determine_debug_level(); } return self::$level >= $required_level; } /** * Helper to build the standardized snapshot format for the frontend. * This creates the hierarchical structure: Placement -> Entity -> Decision Log. * * @param object $placement The placement entity (or virtual wrapper). * @param object|null $item The content entity (Ad or Group). * * @return array */ public static function build_snapshot( object $placement, object $item = null ): array { $placement_id = $placement->get_id(); // Generate the UID: real ID or virtual ID fallback $uid = $placement_id ?: $placement->get_uid(); // Placement Execution Layer with default values. $snapshot = [ 'uid' => (string) $uid, 'db_id' => $placement_id, // The real DB ID (0 for virtual) 'title' => $placement->get_title(), 'public_id' => $placement->get_public_id(), 'badge' => [ 'label' => $placement->get_type(), 'type' => $placement->get_type(), ], 'execution' => [ 'status' => 'success', 'trigger' => 'ssr', 'output_mode' => 'ssr', 'hook_fired' => true, 'skip_reason' => method_exists( $placement, 'get_skip_reason' ) ? $placement->get_skip_reason() : null, 'checks' => $placement->backend_checks ?? [], ], 'payload' => null, ]; // Content Payload Layer (Ad/Group) if ( $item ) { $tab = $item instanceof Group ? 'groups' : 'ads'; $item_id = $item->get_id(); $payload = [ 'type' => $item instanceof Group ? 'group' : 'ad', 'id' => $item_id, 'title' => $item->get_title(), 'status' => $item->is_backend_valid ? 'valid' : 'invalid', 'checks' => $item->backend_checks ?? [], 'skip_reason' => $item->skip_reason ?? '', 'ignore_privacy' => (bool) $item->get_meta( 'ignore_privacy_settings', 0 ), 'edit_url' => admin_url( sprintf( 'admin.php?page=adpresso-list-tables&tab=%s&action=edit&entity_type=%s&entity_id=%s', $tab, $tab, $item_id ) ), ]; if ( $item instanceof Group ) { $payload['info'] = [ 'visible_ads' => (int) $item->get_meta( 'visible_ads', 1 ), 'output' => $item->get_meta( 'output', 'default' ), 'random' => (bool) $item->get_meta( 'random', false ), 'static_refresh' => $item->has_static_refresh(), ]; } // Decision Logic Layer (via Trait) // We check if the method exists (through the trait) if ( method_exists( $item, 'get_debug_candidates_info' ) ) { /** @var Group $item */ $payload['group_logic'] = [ 'candidates' => $item->get_debug_candidates_info(), ]; } $snapshot['payload'] = $payload; } return $snapshot; } /** * Adds a new log entry for a placement. * * @param int|string $key The placement ID or UID. * @param array $data The data to add to the log entry. * * @return void */ public static function add_log_entry( int|string $key, array $data ): void { if ( ! self::is_active( 1 ) ) { return; } $key = (string) $key; if ( ! isset( self::$debug_log[ $key ] ) ) { self::$debug_log[ $key ] = [ 'uid' => $key, 'execution' => [], 'payload' => null, 'id' => $key, 'name' => '...', 'output_mode' => 'unknown', ]; } self::$debug_log[ $key ] = array_replace_recursive( self::$debug_log[ $key ], $data ); } /** * Updates an existing log entry for a placement. * * @param int|string $key The placement ID or UID. * @param array $data_to_merge The data to merge into the existing log entry. * * @return void */ public static function update_log_entry( int|string $key, array $data_to_merge ): void { if ( ! self::is_active( 1 ) ) { return; } self::add_log_entry( $key, $data_to_merge ); } /** * Add a server error log entry. * * @param $message * * @return void */ public static function add_server_error_log_entry( $message ): void { if ( ! self::is_active( 2 ) ) { return; } /* phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log Error logging is intended for debugging.*/ error_log( 'AdPresso DEBUG: ' . $message ); } /** * Records a reason why JS-mode rendering was forced. * The request-wide list keeps the first label per key; the reason is also attributed to a placement (explicit ID, else the current one). * * @param string $key Stable id for the source, e.g. 'privacy', 'traffic_guard', 'condition_user_role'. * @param string $label Human-readable reason, shown as-is in the admin bar. * @param int|string|null $placement_id Placement to attribute it to; defaults to the current placement. * * @return void */ public static function note_js_forcing_reason( string $key, string $label, $placement_id = null ): void { if ( ! self::is_active( 1 ) ) { return; } if ( ! isset( self::$js_forcing_reasons[ $key ] ) ) { self::$js_forcing_reasons[ $key ] = $label; } $placement_id ??= self::$current_placement_id; if ( $placement_id !== null ) { self::$placement_js_reasons[ $placement_id ][ $key ] = $label; } } /** * Sets the placement note_js_forcing_reason() attributes to when it gets no explicit ID. * * @param int|string|null $placement_id Null to clear. * * @return void */ public static function set_current_placement( $placement_id ): void { self::$current_placement_id = $placement_id; } /** * JS-forcing reasons attributed to one placement. * * @param int|string $placement_id * * @return string[] */ public static function get_placement_js_reasons( $placement_id ): array { return array_values( self::$placement_js_reasons[ $placement_id ] ?? [] ); } /** * Returns all reasons recorded so far in this request. * * @return array */ public static function get_js_forcing_reasons(): array { return self::$js_forcing_reasons; } /** * Add a _doing_it_wrong log entry. * * @param $message * * @return void */ public static function add_doing_it_wrong_entry( $message ): void { if ( ! self::is_active( 2 ) ) { return; } _doing_it_wrong( __METHOD__, 'AdPresso Debug: ' . esc_html( $message ), '0.5.0' ); } /** * Marks that a placement's output hook has been triggered. * * @param int|string $key The placement ID or UID. * * @return void */ public static function mark_output_triggered( int|string $key ): void { if ( ! self::is_active( 1 ) ) { return; } if ( ! in_array( $key, self::$output_triggered_placements, false ) ) { $keyStr = (string) $key; if ( ! in_array( $keyStr, self::$output_triggered_placements, true ) ) { self::$output_triggered_placements[] = $keyStr; } self::update_log_entry( $key, [ 'execution' => [ 'hook_fired' => true ], 'hook_fired' => true, ] ); } } /** * Adds headers to bypass caching. * * @return void */ public static function add_cache_bypass_headers(): void { if ( ! headers_sent() ) { header( 'Cache-Control: no-cache, must-revalidate, max-age=0' ); } } /** * Adds a noindex tag to the head section so that the debug output is not indexed. * * @return void */ public static function add_noindex_tag(): void { echo '' . "\n"; } /** * Gather all debug data for frontend JS. * * @return array */ public static function get_js_data(): array { if ( ! self::is_active( 1 ) ) { return []; } return [ 'adpressoDebugActive' => self::determine_debug_level(), 'adpressoDebugData' => self::$debug_log, 'adpressoFiredHookPlacements' => self::$output_triggered_placements, ]; } /** * Enqueue the necessary scripts and styles for debugging. * * @return void */ public static function enqueue_assets(): void { if ( ! self::is_active( 1 ) || is_admin() ) { return; } $debug_script_handle = 'adpresso-adminbar'; wp_enqueue_script( $debug_script_handle ); wp_enqueue_style( $debug_script_handle ); } /** * Adds the debug-specific body class. * * @param array $classes The existing body classes. * * @return array */ public static function add_debug_body_class( array $classes ): array { if ( self::is_active( 1 ) ) { $classes[] = 'adpresso-debug-active'; } return $classes; } /** * Creates the basic structure for the debug menu in the admin bar. * * @param WP_Admin_Bar $wp_admin_bar * * @return void */ public static function setup_admin_bar_debug_nodes( WP_Admin_Bar $wp_admin_bar ): void { // top level node $wp_admin_bar->add_node( [ 'id' => 'adpresso-debug', 'title' => ' AdPresso Status Bar', 'href' => '#', ] ); $wp_admin_bar->add_node( [ 'id' => 'adpresso-debug-highlight-toggle', 'parent' => 'adpresso-debug', 'title' => ' ' . __( 'Highlight Ads', 'adpresso' ), 'href' => '#', 'meta' => [ 'class' => 'adpresso-debug-highlight-button' ], ] ); $wp_admin_bar->add_node( [ 'id' => 'adpresso-debug-toggle-placements', 'parent' => 'adpresso-debug', 'title' => ' ' . __( 'Hide non-visible placements', 'adpresso' ), 'href' => '#', 'meta' => [ 'class' => 'adpresso-debug-toggle-placements-button' ], ] ); $wp_admin_bar->add_node( [ 'id' => 'adpresso-debug-separator', 'parent' => 'adpresso-debug', 'title' => '-', 'meta' => [ 'class' => 'adpresso-debug-separator' ] ] ); } }