compat

Documentation

Overview

Package compat is the single source of truth for drop-in compatibility with shivammathur/setup-php@v2. All data in this package is derived from the audit documented in docs/compat-matrix.md and should be updated via deliberate PRs that bump the pinned reference.

Index

• func BaseIniFileName(iniFile string) (filename, warning string)
• func BundledExtensions(phpVersion string) []string
• func DefaultIniValues(phpVersion, arch string) map[string]string
• func OurBuildBundledExtras(phpVersion string) []string
• func UnimplementedInputWarning(inputName, value string) string
• func XdebugIniFragment(phpVersion string) map[string]string

Functions

func BaseIniFileName

func BaseIniFileName(iniFile string) (filename, warning string)

BaseIniFileName maps the user-facing `ini-file` input to the upstream PHP source file name stored under share/php/ini/ in the core bundle. Returns ("", "") for "none" (effective php.ini is written empty). Any value that isn't one of the five v2 aliases falls back to production and returns a ::warning:: line.

Data source: docs/compat-matrix.md §1.1 note on parseIniFile (src/utils.ts L88-97).

func BundledExtensions

func BundledExtensions(phpVersion string) []string

BundledExtensions returns the set of extensions compiled in to (or bundled with) the shivammathur/setup-php@v2 Linux build for a given PHP version — i.e. what `php -m` reports after setup-php runs with an empty `extensions:` input, based on the Ondrej PPA build for that version. Returns nil for unknown versions.

Names are returned as user-facing extension identifiers (lowercase, `Zend OPcache` → `opcache`), suitable for matching against `extensions:` input. The underlying golden files preserve the raw `php -m` casing for audit purposes; normalization happens here.

The returned slice is a copy; callers may mutate it without affecting other callers.

Data source: docs/compat-matrix.md §3; mirrored in testdata/bundled_extensions_<ver>.golden.

func DefaultIniValues

func DefaultIniValues(phpVersion, arch string) map[string]string

DefaultIniValues returns the ini key/value pairs that shivammathur/setup-php@v2 applies to every Linux run by default via its bundled ini templates. The result is keyed by PHP minor version AND architecture — aarch64 diverges from x86_64 on opcache.jit_buffer_size per v2's src/configs/ini/jit_aarch64.ini (see docs/compat-matrix.md §2.4).

Extension-tied defaults (e.g. xdebug.mode=coverage) are applied at compose time by their respective handlers, not by this function.

Data sources: docs/compat-matrix.md §2.1 (base), §2.3 (x86_64 jit), §2.4 (aarch64 jit); golden file testdata/default_ini_values.golden pins the x86_64 form.

func OurBuildBundledExtras

func OurBuildBundledExtras(phpVersion string) []string

OurBuildBundledExtras returns extensions our own PHP core bundle compiles in beyond v2's baseline (BundledExtensions). Reflects the current builder's ./configure flag set. Merge with BundledExtensions when the runtime needs the full "preloaded by this bundle" list.

See docs/superpowers/specs/2026-04-17-phase2-t12-handoff.md for the planned builder alignment; this list is intentionally a superset of v2's baseline until that work lands.

func UnimplementedInputWarning

func UnimplementedInputWarning(inputName, value string) string

UnimplementedInputWarning returns the canonical one-line warning emitted when a user sets an input that buildrush cannot implement given its architecture. The text starts with GitHub Actions' "::warning::" prefix so runners fold it.

func XdebugIniFragment

func XdebugIniFragment(phpVersion string) map[string]string

XdebugIniFragment returns the ini key/value pairs from v2's xdebug.ini when xdebug3 is active for the requested PHP version (matches regex 7.[2-4]|8.[0-9] per docs/compat-matrix.md §2.2). Returns nil for any other version.

Deliberate divergence from v2's mechanism: v2 unconditionally writes this fragment for every matching PHP version, even when xdebug is not installed (PHP silently ignores ini keys for unloaded extensions). We take the stricter approach and have the caller apply this map only when xdebug is present in the resolved extension set. The observable end-state — the effective ini value when xdebug *is* loaded — is identical; only the file on disk differs.