Plugin Check lokalnie i w CI: błędy wykryte przed recenzją

Plugin Check wykrywa typowe problemy przed zgłoszeniem do WordPress.org: brak informacji o licencji, niebezpieczne wyjście lub błędnie przypisane tłumaczenia. Narzędzie jest też nazywane PCP. Zgłoszenie wskazuje miejsce do sprawdzenia. Brak zgłoszeń nie dowodzi bezpieczeństwa ani przyjęcia do katalogu.

Artykuł omawia panel WordPressa, wiersz poleceń i GitHub Actions. CI oznacza tutaj automatyczne uruchamianie testów przez GitHuba po zmianie kodu. Szczegóły techniczne dotyczą Plugin Check 2.1.0 i akcji v1.1.9. Celowo błędny przykład oraz poprawiona wersja pokazują różnicę.

Co sprawdza Plugin Check

Plugin Check 2.1.0 wymaga co najmniej WordPressa 6.3 i PHP 7.4. Wcześniejsze środowisko z WordPressem 7.1.2 jest historycznym zestawem testowym, a nie aktualnym zaleceniem aktualizacji. Nowe środowiska wymagają bieżącej wspieranej wersji WordPressa. „Tested up to” opisuje wersję sprawdzoną w testach, a nie pełną gwarancję zgodności.

Wersja 2.1.0 rejestruje 34 testy. Każdy ma krótką nazwę techniczną, na przykład late_escaping. Testy statyczne czytają pliki bez wykonywania badanego kodu wtyczki. Wiele korzysta z PHP_CodeSniffer, czyli PHPCS; pojedyncza reguła nazywa się sniff. Escapowanie oznacza zabezpieczenie wartości odpowiednio do miejsca wyświetlania, na przykład tekstu lub atrybutu HTML, aby znaki nie stały się obcym kodem.

Testy uruchomieniowe obserwują aktywną wtyczkę podczas działania. Plugin Check używa osobnych tabel testowych. Nie jest to pełna granica bezpieczeństwa: kod nadal może odczytywać pliki lub kontaktować się z usługami zewnętrznymi. Testy należą więc do jednorazowej lokalnej instalacji bez prawdziwych danych klientów i dostępów produkcyjnych. Pięć takich testów w 2.1.0 dotyczy rozmiaru, zakresu użycia i sposobu ładowania skryptów oraz arkuszy stylów.

Wszystkie testy Security w 2.1.0 należą także do plugin_repo. Ta kategoria obejmuje już wyjście i bezpośredni dostęp do plików. Według FAQ zgłoszenia do katalogu zazwyczaj muszą przejść wszystkie testy Plugin Repo. Pozostałe kategorie rozszerzają kontrolę. Decyzja zespołu przeglądającego nadal jest potrzebna.

ERROR oznacza błąd, a WARNING ostrzeżenie. Wynik ma też liczbową wagę, czyli severity. Ta klasyfikacja nie określa niezawodnie rzeczywistego ryzyka. Ostrzeżenie o braku kontroli formularza może wskazywać prawdziwą lukę. Parametr URL służący tylko do wyświetlania nie wymaga nonce wyłącznie z powodu pochodzenia z adresu. Znaczenie mają przetwarzanie, wyjście i możliwe zmiany danych. Nonce utrudnia żądania wywołane z obcej strony; kontrola uprawnień określa, które konto może wykonać działanie.

Uruchamianie lokalne: panel i WP-CLI

Po instalacji i aktywacji menu Narzędzia → Plugin Check udostępnia wybór wtyczki, kategorii i typów wyników. Dostęp wymaga uprawnienia do zarządzania wtyczkami. Wyniki podają plik, wiersz, kolumnę, typ, kod i wyjaśnienie. Od wersji 1.8.0 dostępny jest eksport CSV, JSON i Markdown. Wszystkie poniższe polecenia dotyczą lokalnej instalacji testowej.

WP-CLI steruje WordPressem z wiersza poleceń. wp plugin check przyjmuje nazwę wtyczki, ścieżkę albo adres ZIP-a. Domyślnie działają tylko testy statyczne. Testy uruchomieniowe wymagają wczytania cli.php przez --require przed startem WordPressa oraz aktywnej badanej wtyczki. Bez tych warunków brakuje części testów. Brak zgłoszenia nie potwierdza wtedy poprawnego działania.

# Local disposable test installation; version used for this article.
wp plugin install plugin-check --version=2.1.0 --activate

# All static checks for wp-content/plugins/lw-hello-banner.
wp plugin check lw-hello-banner

# Include runtime checks (plugin must be active): load cli.php before WordPress boots.
wp plugin check lw-hello-banner --require=./wp-content/plugins/plugin-check/cli.php

# Limit the run to categories or to single checks.
wp plugin check lw-hello-banner --categories=plugin_repo,security
wp plugin check lw-hello-banner --checks=late_escaping,i18n_usage

# Findings as one JSON array; no findings produces a success line.
wp plugin check lw-hello-banner --ignore-warnings --format=strict-json --fields=file,line,column,type,code,message

# Show result codes, then ignore one specific code.
wp plugin check lw-hello-banner --format=csv --fields=code,message
wp plugin check lw-hello-banner --ignore-codes=textdomain_mismatch

# Checks for an update of an existing directory plugin.
wp plugin check lw-hello-banner --mode=update

# What is available in the installed version.
wp plugin list-checks --format=csv
wp plugin list-check-categories

Najważniejsze opcje wp plugin check w wersji 2.1.0:

Nazwa testu wybiera kontrolę, a kod wyniku oznacza zgłoszenie. --checks=i18n_usage wybiera testy tłumaczeń. Natomiast --ignore-codes=WordPress.WP.I18n.TextDomainMismatch ukrywa pasujące zgłoszenia. --format=csv --fields=code,message wypisuje kody i wyjaśnienia.

Kod CLI w 2.1.0 nie kończy automatycznie przebiegu błędnym statusem po znalezieniu problemów. Kod wyjścia 0 nie oznacza zatem „brak zgłoszeń”. Automatyczny krok zatwierdzania musi przeanalizować wyniki i nie może traktować brakującego lub nieczytelnego wyjścia jako sukcesu. Akcja GitHub ma własne przetwarzanie wyników.

Przy --format=json każdy plik otrzymuje wiersz FILE: …, a następnie tablicę JSON. Całość nie jest jednym dokumentem JSON. Przy zgłoszeniach --format=strict-json tworzy wspólną tablicę. Domyślne kolumny nie zawierają nazw plików; --fields=file,line,column,type,code,message dodaje tę kolumnę. Bez zgłoszeń nadal pojawia się tekst o powodzeniu zamiast pustej tablicy. Skrypt musi jawnie rozróżnić oba przypadki.

Przykładowa wtyczka z wbudowanymi błędami

Celowo błędna wtyczka znajduje się w wp-content/plugins/lw-hello-banner/. Nazwa katalogu jest tutaj slugiem. Domena tekstowa przypisuje tłumaczenia do wtyczki i również powinna brzmieć lw-hello-banner. Przykład wyświetla powitanie, odczytuje imię z URL i udostępnia pole notatki. Błędy obejmują surowe wyjście, brak licencji i zewnętrzny skrypt. CDN oznacza zewnętrzną usługę dostarczania plików. Błędna wersja służy wyłącznie do czytania i sprawdzania w jednorazowym środowisku.

<?php
/**
 * Plugin Name: LW Hello Banner
 * Description: Shows a greeting banner at the top of the front page.
 * Version:     0.1.0
 * Author:      Lukas Wojcik
 * Text Domain: hello-banner
 */

// Intentionally faulty example for Plugin Check. Do not use on a live site.

error_reporting( E_ALL );

function lw_hello_banner_register_setting() {
	register_setting( 'general', 'lw_hello_banner_note' );

	add_settings_field(
		'lw_hello_banner_note',
		__( 'Banner note', 'hello-banner' ),
		'lw_hello_banner_field',
		'general'
	);
}
add_action( 'admin_init', 'lw_hello_banner_register_setting' );

function lw_hello_banner_field() {
	echo '<input type="text" name="lw_hello_banner_note" value="' . get_option( 'lw_hello_banner_note' ) . '">';
}

function lw_hello_banner_assets() {
	wp_enqueue_script( 'lw-hello-banner', 'https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js' );
}
add_action( 'wp_enqueue_scripts', 'lw_hello_banner_assets' );

function lw_hello_banner_render() {
	$name = isset( $_GET['lw_name'] ) ? $_GET['lw_name'] : 'Guest';
	$note = get_option( 'lw_hello_banner_note', '' );

	echo '<div class="lw-hello-banner"><p>' . sprintf( __( 'Hello, %s!', 'hello-banner' ), $name ) . ' ' . $note . '</p></div>';
}
add_action( 'wp_body_open', 'lw_hello_banner_render' );

Co zgłasza Plugin Check

Tabela łączy typowe zgłoszenia z reguł Plugin Check 2.1.0 z błędami przykładu. Liczba i dokładna postać wyników zależą od środowiska, wersji oraz wybranych testów. Tabela nie jest gwarantowanym aktualnym pomiarem.

Kilka testów może zgłosić tę samą przyczynę. Test nagłówka porównuje domenę tekstową w pliku ze slugiem; test i18n sprawdza wywołania tłumaczeń. error_reporting() również może uruchomić kilka reguł. Reguły nonce i danych wejściowych pochodzą z plugin_review_phpcs. Wybór samej kategorii security nie obejmuje więc wszystkich uwag dotyczących bezpieczeństwa.

Testy statyczne i uruchomieniowe badają różne właściwości. Zewnętrzny skrypt może zostać zgłoszony już z powodu obcego adresu. Przy lokalnym skrypcie znaczenie ma także zestaw stron, które go ładują. Baner tylko na stronie głównej nie potrzebuje skryptu na każdej podstronie. Brak zgłoszenia nie zastępuje sprawdzenia tego zachowania.

Poprawiona wersja

Poprawiona wersja zawiera główny plik, readme.txt i lokalny JavaScript w assets/. Nagłówek podaje licencję i wersje minimalne. Warunek ABSPATH blokuje bezpośrednie wykonanie poza WordPressem. Ustawienie notatki otrzymuje funkcję oczyszczania; wyjście HTML jest zabezpieczane tuż przed wypisaniem. Skrypt ładuje się tylko na stronie głównej. defer odkłada wykonanie do zakończenia odczytu dokumentu HTML. Taka postać opcji ładowania istnieje od WordPressa 6.3.

<?php
/**
 * Plugin Name:       LW Hello Banner
 * Description:       Shows a greeting banner at the top of the front page.
 * Version:           0.2.0
 * Requires at least: 6.3
 * Requires PHP:      7.4
 * Author:            Lukas Wojcik
 * License:           GPLv2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       lw-hello-banner
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

define( 'LW_HELLO_BANNER_VERSION', '0.2.0' );

/**
 * Registers the banner note setting and its field on Settings > General.
 */
function lw_hello_banner_register_setting() {
	register_setting(
		'general',
		'lw_hello_banner_note',
		array(
			'type'              => 'string',
			'sanitize_callback' => 'sanitize_text_field',
			'default'           => '',
		)
	);

	add_settings_field(
		'lw_hello_banner_note',
		__( 'Banner note', 'lw-hello-banner' ),
		'lw_hello_banner_field',
		'general',
		'default',
		array( 'label_for' => 'lw_hello_banner_note' )
	);
}
add_action( 'admin_init', 'lw_hello_banner_register_setting' );

/**
 * Prints the input field for the banner note.
 */
function lw_hello_banner_field() {
	printf(
		'<input type="text" class="regular-text" id="lw_hello_banner_note" name="lw_hello_banner_note" value="%s">',
		esc_attr( get_option( 'lw_hello_banner_note', '' ) )
	);
}

/**
 * Loads the bundled script on the front page only.
 */
function lw_hello_banner_assets() {
	if ( ! is_front_page() ) {
		return;
	}

	wp_enqueue_script(
		'lw-hello-banner',
		plugins_url( 'assets/lw-hello-banner.js', __FILE__ ),
		array(),
		LW_HELLO_BANNER_VERSION,
		array(
			'in_footer' => true,
			'strategy'  => 'defer',
		)
	);
}
add_action( 'wp_enqueue_scripts', 'lw_hello_banner_assets' );

/**
 * Prints the banner on the front page.
 */
function lw_hello_banner_render() {
	if ( ! is_front_page() ) {
		return;
	}

	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Read-only display value, nothing is stored.
	$name = isset( $_GET['lw_name'] ) ? sanitize_text_field( wp_unslash( $_GET['lw_name'] ) ) : '';
	if ( '' === $name ) {
		$name = __( 'Guest', 'lw-hello-banner' );
	}

	$greeting = sprintf(
		/* translators: %s: visitor name */
		__( 'Hello, %s!', 'lw-hello-banner' ),
		$name
	);

	$note = get_option( 'lw_hello_banner_note', '' );

	echo '<div class="lw-hello-banner"><p>' . esc_html( $greeting );
	if ( '' !== $note ) {
		echo ' ' . esc_html( $note );
	}
	echo '</p><button type="button">' . esc_html__( 'Dismiss', 'lw-hello-banner' ) . '</button></div>';
}
add_action( 'wp_body_open', 'lw_hello_banner_render' );

Własny parametr URL nazywa się lw_name. WordPress używa ogólnego name do wyboru wpisu, więc taki parametr może zmienić żądaną stronę albo wywołać odpowiedź 404. Wartość przykładowa jest oczyszczana i wyświetlana tylko jako zabezpieczony tekst. Wąski komentarz phpcs:ignore wycisza więc ostrzeżenie nonce dla tego wiersza. Przy zapisie danych takie uzasadnienie byłoby błędne: potrzebne są także kontrole formularza i uprawnień. Różnicę wyjaśnia artykuł o funkcjach bezpieczeństwa WordPressa.

=== LW Hello Banner ===
Contributors: lukaswojcik
Tags: banner, greeting
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Shows a short, dismissible greeting banner at the top of the front page.

== Description ==

LW Hello Banner prints a greeting on the front page. An optional note can be set under Settings > General.

== Changelog ==

= 0.2.0 =
* Add output escaping, setting sanitization and a local script.

= 0.1.0 =
* Initial version.

Tested up to podaje faktycznie sprawdzoną główną wersję WordPressa, na przykład 7.1. Sama zmiana liczby dla usunięcia komunikatu nie jest testem. Reguły mogą zgłosić starą wartość jako błąd dla nowych wtyczek i ostrzeżenie w trybie aktualizacji. Wartość z poprawką, na przykład 7.1.2, także może zostać zgłoszona. Licencja w readme musi być zgodna z głównym plikiem. Szczegóły zawiera artykuł o readme i nagłówku wtyczki.

// assets/lw-hello-banner.js
( function () {
	const banner = document.querySelector( '.lw-hello-banner' );
	if ( ! banner ) {
		return;
	}

	const button = banner.querySelector( 'button' );
	if ( button ) {
		button.addEventListener( 'click', function () {
			banner.hidden = true;
		} );
	}
} )();

Plugin Check w GitHub Actions

Oficjalna akcja pochodzi z WordPress/plugin-check-action. Opisany przebieg został prześledzony w źródłach v1.1.9. Akcja przygotowuje Node 24 i lokalne środowisko WordPressa wp-env, instaluje Plugin Check oraz zależności, a następnie aktywuje badaną wtyczkę. Polecenie używa --require dla testów uruchomieniowych. Typowa konfiguracja wp-env wymaga Dockera; workflow korzysta z komputera testowego Ubuntu udostępnianego przez GitHuba.

Akcja czyta plik wyników i dodaje uwagi przy odpowiednich plikach. Przetworzony ERROR ustawia kod wyjścia 1; samo ostrzeżenie tego nie robi. Z strict: true również przetworzone ostrzeżenia kończą zadanie błędem. Dotyczy to tylko wpisów faktycznie rozpoznanych przez parser. Niepełne wyjście lub wyłączone testy nie dowodzą ogólnego bezpieczeństwa. Pull request może otrzymać komentarz podsumowujący, a surowe wyniki są zapisywane do pobrania.

Parametry wejściowe w v1.1.9: build-dir (domyślnie ./), checks, exclude-checks, categories, exclude-files, exclude-directories, ignore-codes, ignore-warnings, ignore-errors, include-experimental, wp-version (latest lub trunk), severity, error-severity, warning-severity, include-low-severity-errors, include-low-severity-warnings, slug, strict i repo-token. Parametry listowe przyjmują jeden wpis w wierszu.

build-dir wybiera sprawdzany katalog. Ostatni człon ścieżki zwykle staje się slugiem; wejście slug może zastąpić tę wartość. Inna nazwa może powodować niepoprawne zgłoszenia tłumaczeń. Materiały robocze takie jak .github również nie należą do gotowej wtyczki. Workflow tworzy więc osobny katalog przez git archive. Wpisy z export-ignore w .gitattributes pozostają poza archiwum. Trafiają do niego tylko pliki obecne już w commicie Git.

# .github/workflows/plugin-check.yml
name: Plugin Check

on:
  pull_request:
  push:
    branches:
      - main

permissions:
  contents: read
  pull-requests: write # only for the summary comment on pull requests

jobs:
  plugin-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      # Build the folder that would be shipped, without .github and other
      # development files (see export-ignore in .gitattributes).
      - name: Build distributable plugin folder
        run: |
          mkdir -p build
          git archive --format=tar --prefix=lw-hello-banner/ HEAD | tar -x -C build

      - name: Run Plugin Check
        uses: wordpress/plugin-check-action@v1.1.9
        with:
          # The folder name becomes the slug (text domain check, readme check).
          build-dir: ./build/lw-hello-banner
          wp-version: latest
          # Optional filters, one entry per line:
          # categories: |
          #   plugin_repo
          #   security
          # exclude-checks: |
          #   enqueued_scripts_scope
          # ignore-codes: |
          #   textdomain_mismatch
          # Fail on warnings as well:
          # strict: true

# .gitattributes: files that git archive leaves out of the build
/.gitattributes export-ignore
/.github        export-ignore
/.gitignore     export-ignore
/build          export-ignore

pull-requests: write umożliwia opcjonalny komentarz podsumowujący. Pull requesty z obcych forków mogą mieć ograniczone uprawnienia. Kod akcji zapisuje nieudane komentowanie jako komunikat błędu, ale w tym miejscu nie ustawia dodatkowo kodu wyjścia. Workflow wskazuje v1.1.9 zamiast ruchomego tagu v1. Pełny sprawdzony hash commitu mocniej ustala tożsamość kodu; tag wersji również może zostać przesunięty.

Ograniczenia i otwarte kwestie

• Plugin Check nie zastępuje ręcznej oceny. Brak zgłoszeń nie gwarantuje zatwierdzenia.
• Przykłady PHP przeszły kontrolę składni. Testy w izolacji sprawdziły układ archiwum, przycisk banera i oficjalny parser wyników. Nie wykonano tutaj pełnego przebiegu WordPressa ani workflow na GitHubie dla tych przykładów.
• Część testów wyprowadza prawdopodobne wzorce nazw z kodu. Wspólny początek funkcji, na przykład lw_hello_banner_, ogranicza kolizje nazw. Wywnioskowana reguła nadal wymaga oceny konkretnego przypadku.
• Akcja v1.1.9 nie ma wejścia ustalającego wersję Plugin Check. W świeżym środowisku instaluje wersję z katalogu. Ustalenie tagu akcji nie ustala więc wszystkich zależności.
• Brakuje wejścia dla wersji PHP. W v1.1.9 tylko trunk wybiera inne źródło WordPressa; pozostałe wartości wp-version prowadzą do bieżącego wydania. Testy starszych wersji wymagają osobnego środowiska opisanego w osobnym artykule z tej serii.
• Zgłoszenia dotyczące skryptów zależą od badanych stron i warunków ładowania. Artykuł o wybiórczym wyłączaniu skryptów opisuje wybiórcze usuwanie skryptów wtyczek.