Versioning a Public PHP Package with Semantic Versioning

Semantic versioning communicates breaking, additive and patch changes for consumers.

What It Does and When to Use It

Publish a valid Composer library manifest; Composer resolves release versions from VCS tags, so omit a hard-coded version field. A minimum platform requirement controls what syntax can be parsed; target-version tests find runtime and extension incompatibilities.

Requirements, Inputs and Expected Behavior

Confirm the runtime, extension, environment variables, and permissions before running the examples in production. Releasing a version tag does not guarantee backward compatibility without tests.

Example 1: Basic Operation

Publish a valid Composer library manifest; Composer resolves release versions from VCS tags, so omit a hard-coded version field.

{"name":"acme/formatter","require":{"php":"^8.4"},"autoload":{"psr-4":{"Acme\\Formatter\\":"src/"}}}

Example 2: Behavior and Validation

Publish a reviewed tag only after validation; a major release is required for breaking public API changes.

composer validate --strict
git tag v1.2.0
git push origin v1.2.0

Practical Example: Application Use

Distinguish major, minor, and patch release numbers; tests must establish actual compatibility.

<?php
function parseReleaseTag(string $tag): array {
    if (!preg_match('/^v?(\d+)\.(\d+)\.(\d+)$/',$tag,$m)) throw new InvalidArgumentException('Invalid version');
    return array_map('intval',array_slice($m,1));
}
print_r(parseReleaseTag('v2.1.0'));

Important Behavior and Edge Cases

The second example highlights: Publish a reviewed tag only after validation; a major release is required for breaking public API changes. The practical example adds: Distinguish major, minor, and patch release numbers; tests must establish actual compatibility.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Semantic versioning communicates breaking, additive and patch changes for consumers.
• Distinguish major, minor, and patch release numbers; tests must establish actual compatibility.
• Do not introduce syntax from a newer minor version before every production host supports it.