Download the PHP package szepeviktor/consistent-versions without Composer

Consistent Versions

Consistent Versions checks that version-related values stored in different project files agree.

It is designed for projects where the same information appears in several places, for example:

• a WordPress plugin header;
• a WordPress.org readme.txt;
• composer.json;
• package.json;
• a GitHub Actions workflow;
• a PHPStan NEON configuration;
• a PHPCS ruleset;
• an INI or simple .env file;
• a Gettext PO or POT header;
• a PHP class constant;
• Markdown documentation;
• a plain VERSION file.

The tool only reads and compares configured sources. It never rewrites files or changes environment variables.

Table of contents

• Why use it?
• How it works
• Requirements
• Installation
• Quick start for a WordPress plugin
• Running the checker
• Configuration reference
• JSONPath selectors
• Readers
• Normalizers
• Complete WordPress example
• GitHub Actions integration
• Using the library API
• Extending the package
• Errors and exit codes
• Security and limitations
• Development
• License

Why use it?

A WordPress plugin release may contain the same plugin version in all of these files:

The minimum supported PHP version may also appear in:

It is easy to update four places and forget the fifth. Consistent Versions makes that mistake fail locally or in CI before a release is published.

Typical mistakes it detects include:

• VERSION contains 1.4.0, but the plugin header still contains 1.3.0;
• the WordPress readme has the wrong Stable tag;
• Composer requires PHP 8.1, but CI starts its test matrix at PHP 8.2;
• the plugin header and WordPress readme declare different minimum PHP versions;
• a PHP class constant was not updated for a release.

How it works

Each supported source is read by a format-aware reader. The reader converts the source into a virtual JSON-like document.

For example, this WordPress plugin header:

is exposed as data similar to:

A JSONPath selector such as $.Version selects the required scalar value.

The checking process is:

1. Read the expected value.
2. Read every configured value under values.
3. Apply source-specific normalizers.
4. Apply check-level normalizers.
5. Compare the normalized values using strict equality.
6. Report every value that differs.

Selectors must return exactly one scalar value: a string, number, boolean, or null. Selecting nothing, several values, an array, or an object is an error.

Requirements

• PHP 8.1 or newer
• Composer

The runtime package has no ext-* Composer dependency.

XML, HTML, PHP constants, and WordPress headers are parsed without loading or executing the inspected files. The package can run without optional PHP extensions.

PHPStan is a development-only dependency and uses the Phar support included in normal PHP CLI installations.

Installation

Install the package as a development dependency:

The executable becomes available at:

Quick start for a WordPress plugin

Assume the project contains the following files.

VERSION

plugin.php

readme.txt

src/Plugin.php

Create consistent-versions.yaml in the project root:

Run:

Successful output:

If readme.txt still contains 1.2.2, the output is:

Running the checker

The default command reads consistent-versions.yaml from the current working directory:

Use a different YAML configuration:

JSON configuration is also supported when the filename ends in .json:

Display help:

All source file paths are resolved relative to the configuration file, not relative to the current working directory. Absolute paths are accepted too.

Configuration reference

The configuration root must contain a non-empty checks map:

Check definition

Each check supports these fields:

The names under checks and values are report labels. They do not affect selection or comparison.

Expected value

expected may be a source:

or a literal scalar:

Quoting version-like YAML values is recommended. Without quotes, YAML may interpret values such as 8.1 as numbers.

Source definition

A source supports:

Example:

Normalizers may be written as one string:

or as an ordered list:

Source-specific normalizers run first. Check-level normalizers run afterwards.

Comparison

After normalization, values are compared using strict equality.

This means the string "8.1" and the number 8.1 are different unless a normalizer converts them to the same representation.

Use string or version when values may be represented with different scalar types or version formats.

JSONPath selectors

Consistent Versions implements a dependency-free, read-only subset of RFC 9535 JSONPath.

Supported syntax

Supported filter operators:

Example XML selector:

Example filter with two conditions:

String ordering comparisons only compare strings with strings. Numeric ordering comparisons only compare numbers with numbers. The tool does not perform loose PHP comparison inside filters.

Property names containing spaces or punctuation

Use bracket notation:

Backslashes in class names

Inside a YAML single-quoted scalar, use two backslashes in the JSONPath string:

This selects the PHP class Vendor\Plugin.

Unsupported JSONPath features

The following features are intentionally not implemented:

• unions;
• array slices;
• functions;
• regular-expression filters;
• update or mutation expressions.

Stable project configuration should normally use direct, deterministic paths.

Readers

Every reader returns a virtual JSON-like document. Use JSONPath to select a value from that document.

env

Reads one explicitly named environment variable. It does not expose the rest of the process environment.

The virtual document is the variable's string value. The default $ path is therefore normally sufficient. An unset variable is a parsing error; a set but empty variable is a valid empty string.

For a release tag such as v1.2.3, normalizers can remove the prefix and validate the version:

ini

Parses PHP INI syntax using raw value scanning. It works with .ini files and simple .env files that contain KEY=value assignments.

Input:

Selectors:

A complete source definition for .env is:

INI_SCANNER_RAW keeps every value as a string, so 8.1 remains "8.1". The reader does not copy parsed values into the process environment.

This is an INI reader, not a complete Dotenv implementation. Dotenv-specific features such as export KEY=value, shell expansion, and complex multiline values are not supported.

gettext

Reads metadata from the empty msgid header entry of a Gettext .po or .pot file. Escaped continuation strings are decoded without requiring the PHP Gettext extension.

Input:

Virtual document:

The conventional Project-Id-Version: PACKAGE VERSION value is split at its last whitespace boundary. This provides a version scalar that can be selected without a regular expression:

Any raw header remains available by name:

The reader intentionally parses catalog metadata, not individual translation entries.

text

Reads the entire file and applies trim().

Input:

Virtual document:

Selector:

This reader is suitable for VERSION and similar one-value files.

json

Parses arbitrary JSON into objects, arrays, and scalar values.

Input:

Selector:

For package.json, use the generic JSON reader:

Invalid JSON is a parsing error.

composer

Parses composer.json. Its virtual document is the same as the json reader, but the root must be a JSON object.

Project version:

PHP constraint:

yaml

Parses YAML into objects, arrays, and scalar values.

GitHub Actions input:

Selector for the lowest tested PHP version:

neon

Parses a NEON file into objects, arrays, and scalar values. It uses the native NEON parser rather than treating NEON as YAML.

For example, PHPStan may declare its target PHP version as a PHP_VERSION_ID:

The raw integer is available at:

To compare it with values such as 8.1, apply the php-version-id normalizer:

This reader parses the contents of the selected file only. It does not merge files referenced by PHPStan's includes setting or apply PHPStan defaults.

xml

Parses XML into a uniform node tree. Every node exposes:

Children are always a list, even if there is only one child. This avoids the common ambiguity where one XML element becomes an object but repeated elements become an array.

Input:

Selectors:

External entities are never loaded.

phpcs

Parses a PHPCS XML ruleset and presents the commonly needed information in a simpler semantic document:

Input:

Selector:

wordpress-plugin

Reads the first 8192 bytes of a WordPress plugin file and exposes these header fields:

Example selectors:

Missing known headers are exposed as null.

wordpress-theme

Reads the first 8192 bytes of a WordPress theme style.css and exposes:

Example:

wordpress-readme

Parses the header of a WordPress.org readme.txt and exposes:

Example:

Parsing stops when the first section such as == Description == begins.

php

Reads global constants and class constants without including or executing the PHP file.

Input:

Virtual document:

Selectors:

The PHP reader understands scalar literal constants and concatenated scalar literals. It intentionally does not evaluate function calls, variables, class constant references, or arbitrary PHP expressions.

Calls to define() with literal names and literal scalar values are also read.

html

Parses HTML and exposes:

Input:

Example selectors:

The full parsed markup is available under $.tree using the same node model as the xml reader.

markdown

Parses useful structural information from Markdown:

Markdown front matter:

Selectors:

Embedded HTML metadata is parsed through the HTML reader:

Links and images expose text or alt, url, and optional title fields. Fenced code blocks are ignored while collecting Markdown headings, links, and images.

Normalizers

Normalizers convert values before comparison.

identity

Returns the value unchanged.

This is the default behavior when no normalizer is configured.

string

Converts scalar values to strings:

trim

Removes whitespace from the beginning and end of strings. Other scalar types are unchanged.

trim-v-prefix

Removes one lowercase v prefix:

An uppercase V is not removed.

version

Parses and normalizes version strings using Composer's version parser.

This makes common equivalent representations comparable, for example:

Invalid versions produce a configuration error.

php-version-id

Converts PHP's integer version representation to a dotted version:

The input must be an integer or a string containing only decimal digits. This is useful for PHPStan's parameters.phpVersion setting.

composer-minimum

Extracts the inclusive numeric lower bound from a Composer constraint:

It rejects:

• constraints with no numeric versions;
• constraints with an exclusive lower bound such as >8.1, because no single concrete minimum exists.

A common pattern is:

The source-specific composer-minimum runs first. The check-level version normalizer then normalizes both the expected and actual values.

Complete WordPress example

This configuration checks the plugin release version and the minimum PHP version:

The same example is available as consistent-versions.example.yaml.

GitHub Actions integration

Add a step after Composer dependencies are installed:

An inconsistency exits with status 1, so the workflow fails. Invalid configuration, unreadable files, parse failures, and invalid selectors exit with status 2.

For a workflow triggered by a Git tag, the tag name is available in GITHUB_REF_NAME. It can be compared directly without creating a temporary file:

Run that check only for tag events:

Using the library API

The CLI is a thin wrapper around ConfigurationLoader and Engine.

Useful report methods:

Each CheckResult exposes:

Extending the package

Readers and normalizers are registries. Applications may register domain-specific implementations without changing the JSONPath language.

Custom reader

Implement Reader:

Register it:

Configuration may then use:

Readers that consume a named value rather than a file may additionally implement DirectInputReader. Its inputField() method declares the configuration field passed unchanged to read(). The built-in env reader, for example, declares variable; file readers continue to receive an absolute file path.

Custom normalizer

Implement Normalizer:

Register it:

Errors and exit codes

Configuration and parsing errors

These are reported to standard error:

Examples include:

• missing checks;
• missing expected;
• empty values;
• unknown reader;
• unknown normalizer;
• unreadable file;
• missing environment variable;
• invalid JSON, YAML, NEON, INI, Gettext, or XML;
• invalid JSONPath;
• selector returning zero or several values;
• selector returning an array or object;
• invalid version or Composer constraint.

Inconsistent values

Inconsistencies are normal check results and are printed to standard output:

All checks are evaluated, so one run reports every discovered inconsistency.

Security and limitations

Read-only behavior

The package never updates source files. There is no search-and-replace or automatic version bumping.

Environment variables

The env reader only reads the variable explicitly named in the configuration. Its value may be displayed in mismatch reports, so it should be used for non-secret metadata such as CI tag names, not credentials or tokens.

PHP files are not executed

The PHP reader uses its own limited lexer. It does not include or require the inspected file.

Only literal scalar constant expressions are evaluated. Dynamic expressions are skipped.

XML entities

External XML entities are never loaded. Only predefined XML entities and numeric character references are decoded.

Markdown scope

The Markdown reader extracts front matter, ATX headings, inline links, images, embedded HTML metadata, and the original text. It is not a complete CommonMark renderer.

For a stable documented version, prefer explicit front matter:

or explicit HTML metadata:

Do not depend on finding a version inside arbitrary prose.

No automatic inference

The tool does not guess:

• which file is authoritative;
• whether two different constraints mean the same thing;
• which array element is the minimum version;
• which value inside prose represents the project version.

The configuration states these decisions explicitly.

Development

Install dependencies:

Run the test suite:

Run PHP syntax checks:

Run PHPStan:

Run every quality check:

The repository checks its own minimum PHP version declarations with tests/consistent-versions.yaml. The self-check compares Composer's package constraint and platform version, PHPStan's target version, the oldest GitHub Actions matrix entry, and the machine-readable metadata in this README:

PHPStan analyses src and tests at level max. There is no baseline and no ignored error category.

The test suite covers all built-in readers, JSONPath selection, normalizers, successful checks, and mismatch reporting. CI runs the complete suite on PHP 8.1 and PHP 8.5.

License

Consistent Versions is open-source software licensed under the MIT License.