readme.txt, nagłówek wtyczki i SVN: jak WordPress.org odczytuje wtyczkę

WordPress.org odczytuje informacje o wtyczce z kilku plików. Nagłówek głównego pliku PHP zawiera między innymi numer wersji i wymaganą wersję PHP. Plik readme.txt dostarcza opis do katalogu wtyczek. Jedno pole w tym pliku wybiera również folder publikowanego wydania. Sprzeczne wartości mogą sprawić, że przycisk pobierania nadal pokaże stary numer wersji.

Poniższy przykład przedstawia drogę od plików do strony w katalogu. „LW Reading Time” jest przykładową wtyczką, a nie potwierdzonym publicznym wydaniem. Nazwa konta, adresy, przetestowane wersje, zrzuty ekranu i tłumaczenia muszą odpowiadać rzeczywistej wtyczce przed zgłoszeniem.

Nagłówek wtyczki: informacje na początku pliku PHP

Nagłówek oznacza tutaj blok komentarza na początku głównego pliku PHP. WordPress rozpoznaje wtyczkę już po polu Plugin Name, ale przyjęcie do katalogu wymaga więcej niż tego pola. Importer katalogu szuka głównego pliku bezpośrednio w folderze wydania. Dlatego główny plik i readme trafiają bezpośrednio do trunk/, bez dodatkowego folderu trunk/lw-reading-time/.

<?php
/**
 * Plugin Name:       LW Reading Time
 * Plugin URI:        https://lukaswojcik.com/plugins/lw-reading-time/
 * Description:       Shows the estimated reading time above single posts.
 * Version:           1.2.0
 * Requires at least: 6.5
 * Requires PHP:      7.4
 * Author:            Lukas Wojcik
 * Author URI:        https://lukaswojcik.com/
 * License:           GPLv2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       lw-reading-time
 *
 * @package LW_Reading_Time
 */

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

/**
 * Prepends the estimated reading time to the content of single posts.
 *
 * @param string $content Post content.
 * @return string Filtered content.
 */
function lw_reading_time_prepend( $content ) {
	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		return $content;
	}

	$words = preg_split( '/\s+/u', trim( wp_strip_all_tags( $content ) ), -1, PREG_SPLIT_NO_EMPTY );
	if ( false === $words ) {
		return $content;
	}
	$minutes = max( 1, (int) ceil( count( $words ) / 200 ) );

	$label = sprintf(
		/* translators: %d: number of minutes. */
		_n( '%d minute read', '%d minutes read', $minutes, 'lw-reading-time' ),
		$minutes
	);

	return '<p class="lw-reading-time">' . esc_html( $label ) . '</p>' . $content;
}
add_filter( 'the_content', 'lw_reading_time_prepend' );

Przykład szacuje czas czytania na podstawie fragmentów tekstu rozdzielonych białymi znakami i tempa 200 słów na minutę. Spacje nierozdzielające również oddzielają fragmenty. To przybliżenie, a nie językoznawcze liczenie słów; języki bez spacji między słowami wymagają innej metody. Wynik wynosi co najmniej minutę. Nieprawidłowe UTF-8 pozostawia treść bez zmian.

• Version określa wersję wtyczki. PHP porównuje wersje funkcją version_compare(): 1.02 jest uznawane za nowsze niż 1.1. Spójna numeracja, na przykład 1.2.0, zapobiega takim niespodziankom.
• Requires at least i Requires PHP określają minimalne wersje. WordPress odczytuje te wymagania z pliku PHP. Identyczne wartości w readme zapobiegają sprzecznym informacjom na ekranie.
• Requires Plugins zawiera w razie potrzeby nazwy z katalogu, na przykład woocommerce, a nie ścieżki plików PHP. Zależności zadeklarowane w tym polu przez wtyczkę z katalogu również muszą być opublikowane w katalogu. Pole nie zastępuje sprawdzenia wymaganych funkcji ani konkretnych wersji.
• Update URI pozostaje pominięte w typowej wtyczce z katalogu. Importer nie przyjmuje dowolnego zewnętrznego adresu aktualizacji; rozpoznany adres katalogu musi należeć do tej samej wtyczki.
• Text Domain przypisuje tłumaczone teksty do wtyczki i odpowiada slugowi, czyli krótkiej nazwie w katalogu.

Readme: opis i wybrane wydanie

Readme korzysta z uproszczonej składni Markdown. Podwójne znaki równości oznaczają sekcje. Krótki tekst po polach nagłówka pojawia się pod nazwą wtyczki. Zwięzły opis o długości najwyżej 150 znaków zapobiega ucinaniu zdań.

=== LW Reading Time ===
Contributors: lukaswojcik
Tags: reading time, posts, content
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Shows the estimated reading time above single posts, based on the word count of the post content.

== Description ==

LW Reading Time counts the words of a post and shows the estimated reading time above the content of single posts.

* No settings page, no database tables.
* The output is a single paragraph with the class `lw-reading-time`.
* Translations are managed on translate.wordpress.org.

== Installation ==

1. Install the plugin via Plugins > Add New, or upload the folder `lw-reading-time` to `/wp-content/plugins/`.
2. Activate the plugin.
3. Open any single post; the reading time appears above the content.

== Frequently Asked Questions ==

= How is the reading time calculated? =

The word count of the post content is divided by 200 and rounded up to full minutes.

= Does the plugin change pages? =

No. Only single posts of the post type `post` are changed.

== Screenshots ==

1. Reading time above a single post.
2. The same post with the Polish translation active.

== Changelog ==

= 1.2.0 =
* Plural forms for the reading time label.
* WordPress 6.5 or later is required.

= 1.1.0 =
* Output limited to the main query.

== Upgrade Notice ==

= 1.2.0 =
Adds plural forms. WordPress 6.5 or later is now required.

Wartości we wzorze są przykładowe. Tłumaczenie na translate.wordpress.org, wymienione obrazy i test z konkretną wersją WordPressa muszą rzeczywiście istnieć przed publikacją takich informacji. Contributors zawiera nazwy użytkowników WordPress.org; Tags najwyżej pięć trafnych haseł. Tested up to wskazuje rzeczywiście przetestowaną linię wydań WordPressa, a nie oczekiwaną zgodność z przyszłą wersją.

Typowe sekcje opisują funkcje, instalację, częste pytania, zrzuty ekranu i zmiany. Numerowane opisy zrzutów odpowiadają plikom screenshot-1, screenshot-2 i kolejnym. Starsze wpisy historii zmian mogą trafić do osobnego pliku. Ostrzeżenie podręcznika o możliwych problemach powyżej 10 kB nie jest ogólnym sztywnym limitem importu.

Które pole pojawia się na stronie?

Tabela opisuje sprawdzony kod importera. Kontrola wersji w nagłówku akceptuje w tym miejscu określone ciągi cyfr i kropek; zaakceptowany ciąg nie dowodzi przeprowadzenia testu zgodności. Readme ma osobne reguły, między innymi dla wartości zbyt daleko wybiegających w przyszłość. Te reguły nie obowiązują automatycznie identycznie w nagłówku. Katalog może też przyporządkować wpisanej wersji odpowiednie opublikowane wydanie.

SVN: trzy foldery o różnych zadaniach

SVN jest systemem kontroli wersji katalogu wtyczek. trunk/ zawiera przygotowany stan, tags/1.2.0/ pliki konkretnego wydania, a główny folder assets/ obrazy strony w katalogu. Te obrazy nie należą do pobieranego archiwum ZIP wtyczki.

W typowym przebiegu plik trunk/readme.txt zawiera wpis Stable tag: 1.2.0. WordPress.org szuka wtedy tags/1.2.0/. Gdy ten folder istnieje i zawiera odpowiednie pliki, kod i opis pochodzą z tego folderu wydania. Opis zmieniony tylko w trunk nie pojawi się wtedy na stronie wtyczki. Numer wersji w PHP, nazwa folderu i wartości Stable tag muszą być zgodne.

Brak folderu wydania nie jest nieszkodliwym stanem normalnym. Import może użyć trunk jako źródła zastępczego; włączone potwierdzanie wydań może zamiast tego zatrzymać import. Stable tag: trunk jest zabronione dla nowych wtyczek. Katalog przebudowuje archiwa ZIP objęte zmianą, a nie automatycznie wszystkie stare wersje po każdym commicie. Commit oznacza wspólne zapisanie zestawu zmian; przetwarzanie i odświeżenie zapisanej kopii strony następują później.

Obrazy i podgląd

Główny folder assets korzysta z udokumentowanych nazw: na przykład banner-772x250.png, dodatkowo banner-1544x500.png dla ekranów o dużej rozdzielczości, icon-128x128.png, icon-256x256.png i numerowanych zrzutów ekranu. Wymiary obrazu muszą odpowiadać formatowi. Udokumentowane nazwy pisane małymi literami unikają niejasności; sprawdzony importer nie ignoruje bezwarunkowo wielkich liter.

Dla podglądu Playground podręcznik opisuje plik assets/blueprints/blueprint.json. Ten plik JSON zawiera kroki przygotowania środowiska testowego w przeglądarce. Poprawny plik nie wystarcza do publicznego udostępnienia podglądu: potrzebne jest również włączenie publicznego podglądu w zaawansowanym widoku wtyczki. Pamięć podręczna może opóźnić widoczne zmiany obrazów.

Pierwsze wydanie w jednym commicie

Polecenia zakładają zatwierdzone repozytorium, przygotowane pliki i wymagane obrazy. WPORG_USERNAME jest symbolem zastępczym rzeczywistej nazwy konta WordPress.org. Logowanie wymaga odpowiednich danych dostępu do SVN. Główny plik i readme zawierają już wersję 1.2.0.

# Run in a shell that stops on errors. Replace the approved slug and account.
set -eu

# First release: check out the repository created after approval.
svn co https://plugins.svn.wordpress.org/lw-reading-time lw-reading-time-svn
cd lw-reading-time-svn

# Main plugin file and readme.txt go directly into trunk/, not into a subfolder.
cp ../lw-reading-time/lw-reading-time.php ../lw-reading-time/readme.txt trunk/
svn add trunk/*

# Banner, icon, screenshots and blueprint go into the top-level assets/ folder.
cp ../lw-reading-time-assets/banner-772x250.png ../lw-reading-time-assets/banner-1544x500.png assets/
cp ../lw-reading-time-assets/icon-128x128.png ../lw-reading-time-assets/icon-256x256.png assets/
cp ../lw-reading-time-assets/screenshot-1.png ../lw-reading-time-assets/screenshot-2.png assets/
mkdir assets/blueprints
cp ../lw-reading-time-assets/blueprint.json assets/blueprints/
svn add assets/*

# Serve the images as images instead of application/octet-stream.
svn propset svn:mime-type image/png assets/*.png

# Prepare the tag before publishing anything. The source files already say 1.2.0.
svn cp trunk tags/1.2.0
svn status
svn diff

# One commit publishes trunk, tag and assets together. The username is case sensitive.
svn ci -m "Release LW Reading Time 1.2.0 with assets" --username WPORG_USERNAME

Folder wydania powstaje przed commitem. Dzięki temu trunk, wydanie i obrazy zostają zapisane razem. svn status pokazuje zmienione ścieżki, a svn diff zmiany tekstu. Właściwość MIME oznacza pliki PNG jako obrazy. Dla JPEG właściwy typ to image/jpeg.

Publikacja kolejnego wydania

Drugi przykład zaczyna się w folderze nadrzędnym istniejącej kopii roboczej. Przygotowane pliki zawierają teraz wersję 1.3.0. Kopiowanie zastępuje tutaj tylko dwa pliki. Stare, zbędne pliki nie znikają automatycznie: takie ścieżki wymagają świadomego usunięcia poleceniem svn delete po sprawdzeniu.

# Run from the parent directory of the existing working copy.
set -eu

# Next release: bring the working copy up to date.
cd lw-reading-time-svn
svn up

# Version header and Stable tag both say 1.3.0 in the copied files.
cp ../lw-reading-time/lw-reading-time.php ../lw-reading-time/readme.txt trunk/
# This example copies two files only. Inspect obsolete tracked files separately.
# Use svn delete on each deliberately removed path before tagging.
svn add --force trunk
svn stat
svn diff

# Copy trunk to the new tag and commit trunk and tag together.
svn cp trunk tags/1.3.0
svn ci -m "Release 1.3.0"

svn cp zachowuje historię wersji. Foldery wcześniejszych opublikowanych wydań pozostają bez zmian. Pliki deweloperskie, prywatna konfiguracja i archiwa ZIP nie należą do plików dostarczanej wtyczki. Plik .gitignore nie zapobiega przypadkowemu commitowi SVN. Osobny główny folder assets nie jest natomiast instalowany razem z wtyczką.

Kontrola przed publikacją

Walidator readme sprawdza nazwy, pola i strukturę tekstu. Narzędzie nie sprawdza istnienia folderu wydania, zgodności wersji w nagłówku PHP ani dostępności zależności. Te kwestie dotyczą innych plików lub importu do katalogu. Wynik readme bez błędów nie jest więc zatwierdzeniem wtyczki.

Po podaniu adresu URL sprawdzony walidator akceptuje określone hosty, w tym plugins.svn.wordpress.org i raw.githubusercontent.com, oraz odpowiednie nazwy plików readme. Pobrana treść musi być mniejsza niż 512 KiB; dokładnie 512 KiB jest już odrzucane. Ten limit pobierania różni się od zalecenia pisania krótkiego readme.

Oba przebiegi SVN sprawdzono w oddzielnym lokalnym repozytorium: wspólne pierwsze wydanie, poprawne kopie wersji, typ obrazu, niezmienione stare wydanie i czystą kopię roboczą. Osiem dodatkowych izolowanych testów PHP obejmuje liczenie tekstu i przypadki błędów. Te testy nie zastępują rzeczywistego uruchomienia WordPressa, Plugin Check ani zatwierdzenia przez WordPress.org. Opis importu opiera się na odczytanym kodzie źródłowym; usługa importu nie została odtworzona lokalnie.

Pytania i odpowiedzi

Dlaczego opis pozostaje bez zmian po commicie?

Przy poprawnym Stable tag katalog odczytuje opis z odpowiedniego folderu wydania. Zmiana tylko w trunk wtedy nie wystarcza. Przetwarzanie importu i pamięć podręczna mogą dodatkowo opóźnić widoczną zmianę.

Dlaczego wyświetlana wersja różni się od nazwy folderu?

Wyświetlany numer wersji pochodzi z nagłówka PHP. Nowa nazwa folderu nie zmienia wartości tego pola. Nagłówek, readme i folder wersji muszą wskazywać to samo wydanie.

Dlaczego Tested up to może różnić się między readme a stroną?

Zaakceptowana wartość nagłówka może zastąpić readme. Katalog może też przypisać wpisanej linii wydań odpowiednią opublikowaną wersję. Wyświetlana wartość nie dowodzi dodatkowego testu wtyczki.

Dalsze artykuły i źródła

• Przegląd i zasady katalogu
• Plugin Check
• Tłumaczenia
• Playground i blueprinty
• Plugin Handbook: readme.txt format
• Plugin Handbook: Header Requirements
• Plugin Handbook: Using Subversion
• Plugin Handbook: plugin assets
• Plugin Handbook: Previews and Blueprints
• WordPress.org: Readme Validator
• WordPress.org: przykładowy plik readme.txt
• GitHub WordPress/wordpress.org: parser readme (class-parser.php)
• GitHub WordPress/wordpress.org: walidator readme (class-validator.php)
• GitHub WordPress/wordpress.org: importer wtyczek (class-import.php)
• GitHub WordPress/wordpress-develop: validate_plugin_requirements() w plugin.php
• GitHub WordPress/wordpress-develop: Upgrade Notice w update-core.php
• Make WordPress Core: Introducing Plugin Dependencies in WordPress 6.5
• WordPress.org: Plugin Check (PCP), strona wtyczki i changelog
• WordPress.org API: core version check