$args Optional. Display overrides ('count', 'heading', 'fallback'). * @return string Escaped HTML markup. */ function mlpicks_get_related_html( int $post_id, array $args = array() ): string { return MLPicks_Display::get_related_html( $post_id, $args ); } /** * Public template alias function to get related articles HTML. * * @param int $post_id Source post ID. * @param array $args Optional. Display overrides ('count', 'heading', 'fallback'). * @return string Escaped HTML markup. */ function mlpicks_get_related_articles_html( int $post_id, array $args = array() ): string { return MLPicks_Display::get_related_html( $post_id, $args ); } /** * Public template function to get recent articles HTML. * * @param array $args Display arguments. * @return string Escaped HTML markup or empty string. */ function mlpicks_get_recent_articles_html( array $args = array() ): string { return MLPicks_Display::render_recent_articles( $args ); } /** * Public template function to get most-read articles HTML. * * @param array $args Display arguments. * @return string Escaped HTML markup or empty string. */ function mlpicks_get_most_read_html( array $args = array() ): string { return MLPicks_Display::render_most_read( $args ); } /** * Public template function to get personalized recommendations HTML. * * @param array $args Display arguments. * @return string Escaped HTML markup. */ function mlpicks_get_recommendations_html( array $args = array() ): string { return MLPicks_Display::render_recommendations( $args ); } /** * Load a post's content vector from the database. * * @param int $post_id Post ID. * @param bool $force_refresh Optional. Whether to bypass runtime cache. Default false. * @return array{terms: array, norm: float}|null Vector array or null if not found. */ function mlpicks_get_post_vector( int $post_id, bool $force_refresh = false ): ?array { if ( $post_id <= 0 ) { return null; } static $runtime_cache = array(); if ( $force_refresh && array_key_exists( $post_id, $runtime_cache ) ) { unset( $runtime_cache[ $post_id ] ); } if ( ! $force_refresh && array_key_exists( $post_id, $runtime_cache ) ) { return $runtime_cache[ $post_id ]; } global $wpdb; $table = $wpdb->prefix . 'mlpicks_vectors'; // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter $row = $wpdb->get_row( $wpdb->prepare( 'SELECT terms_json, norm FROM %i WHERE post_id = %d', $table, $post_id ) ); if ( ! $row ) { $runtime_cache[ $post_id ] = null; return null; } $terms = json_decode( (string) $row->terms_json, true ); if ( ! is_array( $terms ) ) { $terms = array(); } $vector = array( 'terms' => $terms, 'norm' => (float) $row->norm, ); $runtime_cache[ $post_id ] = $vector; return $vector; } /** * Calculate cosine similarity between two content vectors. * * @param array $vec_a First vector with keys 'terms' (array) and 'norm' (float). * @param array $vec_b Second vector with keys 'terms' (array) and 'norm' (float). * @return float Cosine similarity score in [0.0, 1.0], rounded to 4 decimals. */ function mlpicks_vector_cosine_similarity( array $vec_a, array $vec_b ): float { $norm_a = (float) ( $vec_a['norm'] ?? 0.0 ); $norm_b = (float) ( $vec_b['norm'] ?? 0.0 ); $terms_a = isset( $vec_a['terms'] ) && is_array( $vec_a['terms'] ) ? $vec_a['terms'] : array(); $terms_b = isset( $vec_b['terms'] ) && is_array( $vec_b['terms'] ) ? $vec_b['terms'] : array(); if ( $norm_a <= 0.0 || $norm_b <= 0.0 || empty( $terms_a ) || empty( $terms_b ) ) { return 0.0; } // Iterate over the smaller array for speed. $dot = 0.0; if ( count( $terms_a ) > count( $terms_b ) ) { foreach ( $terms_b as $token => $wb ) { if ( isset( $terms_a[ $token ] ) ) { $dot += (float) $wb * (float) $terms_a[ $token ]; } } } else { foreach ( $terms_a as $token => $wa ) { if ( isset( $terms_b[ $token ] ) ) { $dot += (float) $wa * (float) $terms_b[ $token ]; } } } if ( $dot <= 0.0 ) { return 0.0; } $sim = $dot / ( $norm_a * $norm_b ); return round( min( 1.0, max( 0.0, (float) $sim ) ), 4 ); } /** * Add settings action link on Plugins screen. * * @param array $links Existing action links. * @return array Modified action links. */ function mlpicks_add_plugin_action_links( array $links ): array { $settings_url = admin_url( 'admin.php?page=mlpicks' ); $settings_link = sprintf( '%s', esc_url( $settings_url ), esc_html__( 'Settings', 'mlpicks' ) ); array_unshift( $links, $settings_link ); return $links; } add_filter( 'plugin_action_links_' . plugin_basename( __FILE__ ), 'mlpicks_add_plugin_action_links' ); /** * Creates or updates the plugin database tables on activation. * * @return void */ function mlpicks_activate() { mlpicks_install_tables(); update_option( 'mlpicks_db_version', MLPICKS_DB_VERSION ); // Queue one-time backfill of existing published posts. mlpicks_start_backfill(); if ( function_exists( 'mlpicks_start_vector_backfill' ) ) { mlpicks_start_vector_backfill(); } } register_activation_hook( __FILE__, 'mlpicks_activate' ); /** * Backwards-compatible template function aliases. */ if ( ! function_exists( 'dearc_get_related_html' ) ) { /** * Legacy template function alias. * * @param int $post_id Source post ID. * @param array $args Optional. Display overrides. * @return string Escaped HTML markup. */ // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- Backward compatibility alias for legacy theme integration. function dearc_get_related_html( int $post_id, array $args = array() ): string { return mlpicks_get_related_html( $post_id, $args ); } } if ( ! function_exists( 'dearc_get_related_articles_html' ) ) { /** * Legacy template function alias. * * @param int $post_id Source post ID. * @param array $args Optional. Display overrides. * @return string Escaped HTML markup. */ // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- Backward compatibility alias for legacy theme integration. function dearc_get_related_articles_html( int $post_id, array $args = array() ): string { return mlpicks_get_related_html( $post_id, $args ); } } if ( ! function_exists( 'dearc_get_recent_articles_html' ) ) { /** * Legacy template function alias. * * @param array $args Display arguments. * @return string Escaped HTML markup or empty string. */ // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- Backward compatibility alias for legacy theme integration. function dearc_get_recent_articles_html( array $args = array() ): string { return mlpicks_get_recent_articles_html( $args ); } } if ( ! function_exists( 'dearc_get_most_read_html' ) ) { /** * Legacy template function alias. * * @param array $args Display arguments. * @return string Escaped HTML markup or empty string. */ // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- Backward compatibility alias for legacy theme integration. function dearc_get_most_read_html( array $args = array() ): string { return mlpicks_get_most_read_html( $args ); } } if ( ! function_exists( 'dearc_get_recommendations_html' ) ) { /** * Legacy template function alias. * * @param array $args Display arguments. * @return string Escaped HTML markup. */ // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- Backward compatibility alias for legacy theme integration. function dearc_get_recommendations_html( array $args = array() ): string { return mlpicks_get_recommendations_html( $args ); } }