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 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 string) map[string]string

DefaultIniValues returns the ini key/value pairs that shivammathur/setup-php@v2 sets on Linux runners by default, before any user-supplied ini-values. The caller merges the user values over the top so users can still override.

Version-conditional defaults:

• PHP 8.x (8.0–8.9): opcache.enable, opcache.jit, opcache.jit_buffer_size per compat-matrix.md §2.3 (jit_versions regex 8.[0-9]).

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

Data source: docs/compat-matrix.md §2.1 and §2.3; mirrored in testdata/default_ini_values.golden.

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.