diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eadf9bd..1a1dbe2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,6 +35,7 @@ jobs: for f in Makefile build.rs about.toml about.hbs \ .github/workflows/ci.yml .github/workflows/release.yml \ .github/workflows/docs.yml .github/dependabot.yml \ + .github/scripts/stubs-check.php \ Cargo.toml composer.json src/lib.rs src/error.rs \ README.md PLAN.md CHANGELOG.md RELEASE.md \ .cargo/config.toml rust-toolchain.toml .ext-template.conf; do diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f70fff..553a6b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,24 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Extensions pick changes up with `bin/sync`; the version records which scaffold an extension was synced from. +## [0.2.2] - 2026-10-29 + +### Added + +- **Stubs check.** `.github/scripts/stubs-check.php` prints a canonical + signature listing of the built extension and of `stubs/` (classes, + finality, parents, interfaces, constants, method modifiers, parameters, + defaults, return types); the managed CI diffs the two on every leg and + `make stubs-check` runs the same locally. Curated stubs can no longer + drift from the registered classes. Skipped with a warning until an + extension has a stubs file. + +### Changed + +- Actions: `actions/checkout` v7, `configure-pages` v6, `deploy-pages` v5, + `upload-pages-artifact` v5, `softprops/action-gh-release` v3 (Node 24 + runtime) — the first Dependabot batch. + ## [0.2.1] - 2026-10-29 ### Fixed @@ -55,6 +73,7 @@ First release: the `template/managed/` and `template/seed/` trees, POSIX `bin/render` and `bin/sync`, per-repo `.ext-template.conf`, and the `versions.conf` pin cascade. +[0.2.2]: https://github.com/DisplaceTech/ext-template/compare/v0.2.1...v0.2.2 [0.2.1]: https://github.com/DisplaceTech/ext-template/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/DisplaceTech/ext-template/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/DisplaceTech/ext-template/releases/tag/v0.1.0 diff --git a/README.md b/README.md index 8e9edab..9bbbfb1 100644 --- a/README.md +++ b/README.md @@ -111,9 +111,14 @@ track record. Release binaries stay NTS-only. ## Stubs -Committed stubs are curated (generics, `@throws`, prose), so -`make stubs` writes cargo-php's output to `target/` for a -signature diff instead of overwriting them. On Linux, cargo-php's +Committed stubs are curated (generics, `@throws`, prose) and must +declare exactly what the extension registers. The managed CI enforces +that on every leg: `.github/scripts/stubs-check.php` lists the built +extension's classes and methods (finality, parents, interfaces, +parameters, defaults, return types) and the stub file's, and the two +listings must be identical; `make stubs-check` runs the same diff +locally. `make stubs` writes cargo-php's raw output to +`target/` as a starting point, never over the curated file. On Linux, cargo-php's `dlopen()` needs PHP's embed library preloaded (`make stubs STUBS_PRELOAD=/usr/lib/libphp8.4.so`); macOS needs nothing. diff --git a/template/managed/.github/scripts/stubs-check.php b/template/managed/.github/scripts/stubs-check.php new file mode 100644 index 0000000..39430e0 --- /dev/null +++ b/template/managed/.github/scripts/stubs-check.php @@ -0,0 +1,76 @@ +getClassNames(); +} elseif ($mode === 'stubs') { + $before = get_declared_classes(); + require $target; + $prefix = $argv[3] ?? ''; + $classes = array_filter( + array_diff(get_declared_classes(), $before), + static fn (string $c): bool => str_starts_with($c, $prefix), + ); +} else { + fwrite(STDERR, "usage: stubs-check.php runtime | stubs \n"); + exit(2); +} + +$classes = array_values($classes); +sort($classes); +$out = []; +foreach ($classes as $name) { + $c = new ReflectionClass($name); + $interfaces = $c->getInterfaceNames(); + sort($interfaces); + $out[] = sprintf( + '%s %s extends %s implements %s', + $c->isFinal() ? 'final class' : ($c->isAbstract() ? 'abstract class' : 'class'), + $name, + $c->getParentClass() ? $c->getParentClass()->getName() : '-', + implode(',', $interfaces), + ); + foreach ($c->getReflectionConstants() as $k) { + if ($k->getDeclaringClass()->getName() === $name) { + $out[] = ' const ' . $k->getName() . ' = ' . var_export($k->getValue(), true); + } + } + $methods = $c->getMethods(); + usort($methods, static fn ($a, $b): int => strcmp($a->getName(), $b->getName())); + foreach ($methods as $m) { + if ($m->getDeclaringClass()->getName() !== $name) { + continue; + } + $params = []; + foreach ($m->getParameters() as $p) { + $s = ($p->getType() ?? 'mixed') . ' ' . ($p->isPassedByReference() ? '&' : '') + . ($p->isVariadic() ? '...' : '') . '$' . $p->getName(); + if ($p->isDefaultValueAvailable()) { + $s .= ' = ' . var_export($p->getDefaultValue(), true); + } elseif ($p->isOptional() && !$p->isVariadic()) { + $s .= ' = '; + } + $params[] = $s; + } + $out[] = sprintf( + ' %s function %s(%s): %s', + implode(' ', Reflection::getModifierNames($m->getModifiers())), + $m->getName(), + implode(', ', $params), + $m->hasReturnType() ? (string) $m->getReturnType() : 'none', + ); + } +} +echo implode("\n", $out), "\n"; diff --git a/template/managed/.github/workflows/ci.yml b/template/managed/.github/workflows/ci.yml index 30728f8..76bb48e 100644 --- a/template/managed/.github/workflows/ci.yml +++ b/template/managed/.github/workflows/ci.yml @@ -165,3 +165,20 @@ jobs: TEST_PHP_EXECUTABLE=$(which php) \ TEST_PHP_ARGS="-d extension=$EXT" \ php run-tests.php -q --show-diff tests/phpt + + - name: Stubs match the registered classes + # The curated stubs must declare exactly what the extension + # registers: classes, finality, parents, interfaces, constants, + # and every method's modifiers, parameters, defaults and return + # type. Two processes because both sides declare the same names. + shell: bash + run: | + if [ ! -f stubs/{{STUBS_FILE}} ]; then + echo "::warning::stubs/{{STUBS_FILE}} doesn't exist yet; skipping the stubs check" + exit 0 + fi + if [ "$RUNNER_OS" = "macOS" ]; then SUFFIX=dylib; else SUFFIX=so; fi + EXT="$PWD/target/debug/lib{{NAME}}.$SUFFIX" + php -d extension="$EXT" .github/scripts/stubs-check.php runtime {{NAME}} > "$RUNNER_TEMP/stubs-runtime.txt" + php .github/scripts/stubs-check.php stubs stubs/{{STUBS_FILE}} "Displace\\{{NAMESPACE}}\\" > "$RUNNER_TEMP/stubs-curated.txt" + diff -u "$RUNNER_TEMP/stubs-curated.txt" "$RUNNER_TEMP/stubs-runtime.txt" diff --git a/template/managed/Makefile b/template/managed/Makefile index cf5545d..c38011f 100644 --- a/template/managed/Makefile +++ b/template/managed/Makefile @@ -8,7 +8,7 @@ FEATURES ?= CARGO_FLAGS := $(if $(FEATURES),--features $(FEATURES),) -.PHONY: help build release test clippy fmt fmt-check stubs install uninstall clean check-cargo-php +.PHONY: help build release test clippy fmt fmt-check stubs stubs-check install uninstall clean check-cargo-php help: @echo "ext-{{NAME}} — common tasks" @@ -20,6 +20,7 @@ help: @echo " make fmt cargo fmt" @echo " make fmt-check cargo fmt --check" @echo " make stubs Generate target/{{STUBS_FILE}} to diff against stubs/" + @echo " make stubs-check Fail if stubs/ differs from the registered classes" @echo " make install cargo php install (loads the extension into your PHP)" @echo " make uninstall cargo php remove" @echo " make clean cargo clean" @@ -99,6 +100,13 @@ STUBS_PRELOAD ?= stubs: check-cargo-php build $(if $(STUBS_PRELOAD),LD_PRELOAD=$(STUBS_PRELOAD) )$(CARGO) php stubs --out target/{{STUBS_FILE}} +# What CI runs: the curated stubs must match the registered classes. +stubs-check: build + @test -f stubs/{{STUBS_FILE}} || { echo "no stubs/{{STUBS_FILE}} yet"; exit 0; }; \ + $(PHP) -n -d extension=$(EXT_PATH) .github/scripts/stubs-check.php runtime {{NAME}} > target/stubs-runtime.txt && \ + $(PHP) -n .github/scripts/stubs-check.php stubs stubs/{{STUBS_FILE}} 'Displace\{{NAMESPACE}}\' > target/stubs-curated.txt && \ + diff -u target/stubs-curated.txt target/stubs-runtime.txt && echo "stubs match the registered classes" + install: check-cargo-php $(CARGO) php install --release $(CARGO_FLAGS)