Files
2026-10-19 12:45:45 -06:00

227 lines
6.2 KiB
PHP
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<?php
/**
* Audit runner service for the rank-math/audit-site-seo ability.
*
* @since 1.0.271
* @package RankMath
* @subpackage RankMath\Abilities\SEO_Analysis
* @author Rank Math <support@rankmath.com>
*/
namespace RankMath\Abilities\SEO_Analysis;
use RankMath\KB;
use RankMath\Helpers\Url;
use RankMath\SEO_Analysis\SEO_Analyzer;
defined( 'ABSPATH' ) || exit;
/**
* Runs the Rank Math site SEO audit and shapes the result for ability/MCP consumers.
*/
class Audit_Runner {
/**
* SEO Analyzer instance.
*
* @var SEO_Analyzer
*/
private $analyzer;
/**
* Constructor.
*
* @param SEO_Analyzer|null $analyzer SEO Analyzer instance.
*/
public function __construct( ?SEO_Analyzer $analyzer = null ) {
$this->analyzer = $analyzer ?? new SEO_Analyzer();
}
/**
* Run the audit and return a structured result.
*
* External URL auditing requires Rank Math PRO. FREE installs receive
* an Audit_Result with error.code 'pro_required' instead of findings.
*
* @param bool $refresh Re-run tests instead of returning cached results.
* @param string|null $url Optional URL to audit. Defaults to this site's home URL.
* @return Audit_Result
*/
public function run( $refresh = true, $url = null ) {
if ( ! empty( $url ) ) {
$clean = wp_http_validate_url( $url );
if ( false === $clean ) {
return $this->error_result(
'invalid_url',
__( 'The provided URL is not valid.', 'seo-by-rank-math' )
);
}
if ( Url::is_external( $clean ) && ! apply_filters( 'rank_math/analysis/is_allowed_url', false, $clean ) ) {
return $this->error_result(
'pro_required',
sprintf(
/* translators: %s: URL to the Rank Math PRO upgrade page */
__( 'Competitor URL analysis requires Rank Math PRO. Upgrade at %s', 'seo-by-rank-math' ),
KB::get( 'pro', 'Audit Site SEO Ability' )
)
);
}
}
// The tests file is normally loaded only in the admin context. Include it here
// so local tests are available when the ability is invoked via REST/MCP.
$tests_file = RANK_MATH_PATH . 'includes/modules/seo-analysis/seo-analysis-tests.php';
if ( file_exists( $tests_file ) ) {
include_once $tests_file;
}
if ( ! empty( $url ) ) {
$this->analyzer->analyse_url = esc_url_raw( $url );
$this->analyzer->analyse_subpage = true;
}
$this->analyzer->set_url();
if ( $refresh || ! $this->has_cached_results() ) {
$this->analyzer->run_tests( $refresh );
} else {
$this->analyzer->get_results_from_storage();
}
return $this->shape( $this->analyzer );
}
/**
* Build a minimal Audit_Result carrying only an error (no findings).
*
* @param string $code Machine-readable error code.
* @param string $message Human-readable message for the AI/user.
* @return Audit_Result
*/
private function error_result( $code, $message ) {
return new Audit_Result(
[
'url' => '',
'score' => 0,
'grade' => 'bad',
'statuses' => [
'ok' => 0,
'fail' => 0,
'warning' => 0,
'info' => 0,
],
'total_tests' => 0,
'last_run_at' => 0,
'remote_api_status' => 'skipped',
'findings' => [],
'error' => [
'code' => $code,
'message' => $message,
],
]
);
}
/**
* Whether a cached audit result exists.
*
* @return bool
*/
private function has_cached_results() {
return (bool) get_option( 'rank_math_seo_analysis_results' );
}
/**
* Build an Audit_Result from a populated SEO_Analyzer.
*
* @param SEO_Analyzer $analyzer Populated analyzer instance.
* @return Audit_Result
*/
private function shape( SEO_Analyzer $analyzer ) {
$findings = [];
$statuses = [
'ok' => 0,
'fail' => 0,
'warning' => 0,
'info' => 0,
];
$total = 0;
$score_sum = 0;
$score_pass = 0;
if ( is_array( $analyzer->results ) ) {
foreach ( $analyzer->results as $id => $result ) {
if ( ! is_object( $result ) || $result->is_hidden() || $result->is_excluded() ) {
continue;
}
$data = $result->get_result();
$status = $result->get_status();
$score = (int) $result->get_score();
$statuses[ $status ] = isset( $statuses[ $status ] ) ? $statuses[ $status ] + 1 : 1;
++$total;
$score_sum += $score;
if ( 'ok' === $status ) {
$score_pass += $score;
}
// Prefer the per-run `message` (contains actual counts/links) over the
// static `description` (generic text defined in the test registration).
$description = isset( $data['message'] ) ? $data['message'] : ( isset( $data['description'] ) ? $data['description'] : '' );
$fix_html = isset( $data['fix'] ) ? $data['fix'] : '';
$findings[] = new Finding(
[
'test_id' => $id,
'category' => $result->get_category(),
'status' => $status,
'score' => $score,
'title' => isset( $data['title'] ) ? $data['title'] : '',
'description' => wp_strip_all_tags( $description ),
'fix_text' => html_entity_decode( wp_strip_all_tags( $fix_html ), ENT_QUOTES | ENT_HTML5, 'UTF-8' ),
'fix_html' => $fix_html,
'fix_hint' => Fix_Hint_Map::get( $id ),
'kb_link' => isset( $data['kb_link'] ) ? $data['kb_link'] : '',
'data' => isset( $data['data'] ) ? $data['data'] : null,
]
);
}
}
$percent = $score_sum > 0 ? (int) round( ( $score_pass / $score_sum ) * 100 ) : 0;
return new Audit_Result(
[
'url' => $analyzer->analyse_url,
'score' => $percent,
'grade' => $this->grade_for( $percent ),
'statuses' => $statuses,
'total_tests' => $total,
'last_run_at' => (int) get_option( 'rank_math_seo_analysis_date', 0 ),
'remote_api_status' => $analyzer->remote_api_succeeded() ? 'ok' : 'unavailable',
'findings' => $findings,
'error' => null,
]
);
}
/**
* Score → grade bucket.
*
* @param int $percent Score percentage 0–100.
* @return string good|average|bad
*/
private function grade_for( $percent ) {
if ( $percent < 50 ) {
return 'bad';
}
if ( $percent < 70 ) {
return 'average';
}
return 'good';
}
}