Skip to content

Use dotorg readme parser if available #947

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 24, 2025
Merged

Use dotorg readme parser if available #947

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 43 additions & 42 deletions includes/Checker/Checks/Plugin_Repo/Plugin_Readme_Check.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,13 @@
use WordPress\Plugin_Check\Checker\Check_Categories;
use WordPress\Plugin_Check\Checker\Check_Result;
use WordPress\Plugin_Check\Checker\Checks\Abstract_File_Check;
use WordPress\Plugin_Check\Lib\Readme\Parser;
use WordPress\Plugin_Check\Lib\Readme\Parser as PCPParser;
use WordPress\Plugin_Check\Traits\Amend_Check_Result;
use WordPress\Plugin_Check\Traits\Find_Readme;
use WordPress\Plugin_Check\Traits\License_Utils;
use WordPress\Plugin_Check\Traits\Stable_Check;
use WordPress\Plugin_Check\Traits\Version_Utils;
use WordPressdotorg\Plugin_Directory\Readme\Parser as DotorgParser;

/**
* Check the plugins readme file and contents.
Expand Down Expand Up @@ -83,7 +84,7 @@ protected function check_files( Check_Result $result, array $files ) {

$readme_file = reset( $readme );

$parser = new Parser( $readme_file );
$parser = class_exists( DotorgParser::class ) ? new DotorgParser( $readme_file ) : new PCPParser( $readme_file );

// Check the readme file for plugin name.
$this->check_name( $result, $readme_file, $parser );
Expand Down Expand Up @@ -121,11 +122,11 @@ protected function check_files( Check_Result $result, array $files ) {
*
* @since 1.0.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_name( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_name( Check_Result $result, string $readme_file, $parser ) {
if ( isset( $parser->warnings['invalid_plugin_name_header'] ) && false === $parser->name ) {
$this->add_result_error_for_file(
$result,
Expand Down Expand Up @@ -188,13 +189,13 @@ private function check_name( Check_Result $result, string $readme_file, Parser $
*
* @since 1.0.2
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*
* @SuppressWarnings(PHPMD.ExcessiveMethodLength)
*/
private function check_headers( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_headers( Check_Result $result, string $readme_file, $parser ) {
$ignored_warnings = $this->get_ignored_warnings( $parser );

$fields = array(
Expand Down Expand Up @@ -302,11 +303,11 @@ private function check_headers( Check_Result $result, string $readme_file, Parse
*
* @since 1.0.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_default_text( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_default_text( Check_Result $result, string $readme_file, $parser ) {
$short_description = $parser->short_description;
$tags = $parser->tags;
$donate_link = $parser->donate_link;
Expand Down Expand Up @@ -334,11 +335,11 @@ private function check_default_text( Check_Result $result, string $readme_file,
*
* @since 1.0.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_license( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_license( Check_Result $result, string $readme_file, $parser ) {
$license = $parser->license;
$matches_license = array();
$plugin_main_file = $result->plugin()->main_file();
Expand Down Expand Up @@ -408,11 +409,11 @@ private function check_license( Check_Result $result, string $readme_file, Parse
*
* @since 1.0.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_stable_tag( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_stable_tag( Check_Result $result, string $readme_file, $parser ) {
$stable_tag = $parser->stable_tag;

if ( empty( $stable_tag ) ) {
Expand Down Expand Up @@ -487,11 +488,11 @@ private function check_stable_tag( Check_Result $result, string $readme_file, Pa
*
* @since 1.0.2
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_upgrade_notice( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_upgrade_notice( Check_Result $result, string $readme_file, $parser ) {
$notices = $parser->upgrade_notice;

$maximum_characters = 300;
Expand Down Expand Up @@ -521,13 +522,13 @@ private function check_upgrade_notice( Check_Result $result, string $readme_file
*
* @since 1.0.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*
* @SuppressWarnings(PHPMD.ExcessiveMethodLength)
*/
private function check_for_warnings( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_for_warnings( Check_Result $result, string $readme_file, $parser ) {
$warnings = $parser->warnings ? $parser->warnings : array();

// This should be ERROR rather than WARNING. So ignoring here to handle separately.
Expand Down Expand Up @@ -665,11 +666,11 @@ private function check_for_warnings( Check_Result $result, string $readme_file,
*
* @since 1.3.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_for_donate_link( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_for_donate_link( Check_Result $result, string $readme_file, $parser ) {
$donate_link = $parser->donate_link;

// Bail if empty donate link.
Expand Down Expand Up @@ -819,11 +820,11 @@ function ( $value ) {
*
* @since 1.5.0
*
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param Parser $parser The Parser object.
* @param Check_Result $result The Check Result to amend.
* @param string $readme_file Readme file.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
private function check_requires_headers( Check_Result $result, string $readme_file, Parser $parser ) {
private function check_requires_headers( Check_Result $result, string $readme_file, $parser ) {
$ignored_warnings = $this->get_ignored_warnings( $parser );

$found_warnings = $parser->warnings ? $parser->warnings : array();
Expand Down Expand Up @@ -881,10 +882,10 @@ private function check_requires_headers( Check_Result $result, string $readme_fi
*
* @since 1.0.2
*
* @param Parser $parser The Parser object.
* @param DotorgParser|PCPParser $parser The Parser object.
* @return array Ignored warnings.
*/
private function get_ignored_warnings( Parser $parser ) {
private function get_ignored_warnings( $parser ) {
$ignored_warnings = array(
'contributor_ignored',
);
Expand All @@ -894,8 +895,8 @@ private function get_ignored_warnings( Parser $parser ) {
*
* @since 1.0.2
*
* @param array $ignored_warnings Array of ignored warning keys.
* @param Parser $parser The Parser object.
* @param array $ignored_warnings Array of ignored warning keys.
* @param DotorgParser|PCPParser $parser The Parser object.
*/
$ignored_warnings = (array) apply_filters( 'wp_plugin_check_ignored_readme_warnings', $ignored_warnings, $parser );

Expand Down
5 changes: 3 additions & 2 deletions includes/Checker/Checks/Plugin_Repo/Trademarks_Check.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@
use WordPress\Plugin_Check\Checker\Check_Categories;
use WordPress\Plugin_Check\Checker\Check_Result;
use WordPress\Plugin_Check\Checker\Checks\Abstract_File_Check;
use WordPress\Plugin_Check\Lib\Readme\Parser;
use WordPress\Plugin_Check\Lib\Readme\Parser as PCPParser;
use WordPress\Plugin_Check\Traits\Amend_Check_Result;
use WordPress\Plugin_Check\Traits\Find_Readme;
use WordPress\Plugin_Check\Traits\Stable_Check;
use WordPressdotorg\Plugin_Directory\Readme\Parser as DotorgParser;

/**
* Check for trademarks.
Expand Down Expand Up @@ -265,7 +266,7 @@ private function check_for_name_in_readme( Check_Result $result, array $files )

$readme_file = reset( $readme );

$parser = new Parser( $readme_file );
$parser = class_exists( DotorgParser::class ) ? new DotorgParser( $readme_file ) : new PCPParser( $readme_file );

try {
$this->validate_name_has_no_trademarks( $parser->name );
Expand Down
5 changes: 3 additions & 2 deletions includes/Plugin_Context.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@
namespace WordPress\Plugin_Check;

use Exception;
use WordPress\Plugin_Check\Lib\Readme\Parser;
use WordPress\Plugin_Check\Lib\Readme\Parser as PCPParser;
use WordPress\Plugin_Check\Traits\Find_Readme;
use WordPressdotorg\Plugin_Directory\Readme\Parser as DotorgParser;
use function WP_CLI\Utils\normalize_path;

/**
Expand Down Expand Up @@ -200,7 +201,7 @@ public function minimum_supported_wp() {
$readme_files = $this->filter_files_for_readme( $readme_files, $this->path() );
$readme_file = reset( $readme_files );
if ( $readme_file ) {
$parser = new Parser( $readme_file );
$parser = class_exists( DotorgParser::class ) ? new DotorgParser( $readme_file ) : new PCPParser( $readme_file );

if ( ! empty( $parser->requires ) ) {
$this->minimum_supported_wp = $parser->requires;
Expand Down
1 change: 1 addition & 0 deletions phpstan.neon.dist
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ parameters:
- tests/phpstan/stubs/wp-cli.php
- tests/phpstan/stubs/exitexception.php
- tests/phpstan/stubs/formatter.php
- tests/phpstan/stubs/readme-parser.php
dynamicConstantNames:
- WP_PLUGIN_CHECK_PLUGIN_DIR_URL
treatPhpDocTypesAsCertain: false
Expand Down
110 changes: 110 additions & 0 deletions tests/phpstan/stubs/readme-parser.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
<?php

namespace WordPressdotorg\Plugin_Directory\Readme;

class Parser {
/**
* @var string
*/
public $name = '';
/**
* @var array
*/
public $tags = array();
/**
* @var string
*/
public $requires = '';
/**
* @var string
*/
public $tested = '';
/**
* @var string
*/
public $requires_php = '';
/**
* @var array
*/
public $contributors = array();
/**
* @var string
*/
public $stable_tag = '';
/**
* @var string
*/
public $donate_link = '';
/**
* @var string
*/
public $short_description = '';
/**
* @var string
*/
public $license = '';
/**
* @var string
*/
public $license_uri = '';
/**
* @var array
*/
public $sections = array();
/**
* @var array
*/
public $upgrade_notice = array();
/**
* @var array
*/
public $screenshots = array();
/**
* @var array
*/
public $faq = array();
/**
* Warning flags which indicate specific parsing failures have occurred.
*
* @var array
*/
public $warnings = array();
/**
* These are the readme sections that we expect.
*
* @var array
*/
public $expected_sections = array('description', 'installation', 'faq', 'screenshots', 'changelog', 'upgrade_notice', 'other_notes');
/**
* We alias these sections, from => to
*
* @var array
*/
public $alias_sections = array('frequently_asked_questions' => 'faq', 'change_log' => 'changelog', 'screenshot' => 'screenshots');
/**
* These are the valid header mappings for the header.
*
* @var array
*/
public $valid_headers = array('tested' => 'tested', 'tested up to' => 'tested', 'requires' => 'requires', 'requires at least' => 'requires', 'requires php' => 'requires_php', 'tags' => 'tags', 'contributors' => 'contributors', 'donate link' => 'donate_link', 'stable tag' => 'stable_tag', 'license' => 'license', 'license uri' => 'license_uri');
/**
* These plugin tags are ignored.
*
* @var array
*/
public $ignore_tags = array('plugin', 'wordpress');
/**
* The maximum field lengths for the readme.
*
* @var array
*/
public $maximum_field_lengths = array('short_description' => 150, 'section' => 2500, 'section-changelog' => 5000, 'section-faq' => 5000);
/**
* The raw contents of the readme file.
*
* @var string
*/
public $raw_contents = '';

public function __construct($string = '') {}
}
Loading