Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<file>` (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
Expand Down Expand Up @@ -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
11 changes: 8 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<stubs file>` 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/<stubs file>` 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.

Expand Down
76 changes: 76 additions & 0 deletions template/managed/.github/scripts/stubs-check.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
<?php
// Template-managed (ext-template). Prints a canonical signature listing
// of either the loaded extension or the curated stubs, so CI can diff
// them: the stubs must declare exactly what the extension registers.
//
// php -d extension=... stubs-check.php runtime {{NAME}}
// php stubs-check.php stubs stubs/{{STUBS_FILE}} 'Displace\{{NAMESPACE}}\'
//
// Run the two modes in separate processes: the stubs declare the same
// class names the extension registers.

declare(strict_types=1);

[$_, $mode, $target] = $argv + [null, null, null];

if ($mode === 'runtime') {
$classes = (new ReflectionExtension($target))->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 <ext> | stubs <file> <namespace-prefix>\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 .= ' = <optional>';
}
$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";
17 changes: 17 additions & 0 deletions template/managed/.github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
10 changes: 9 additions & 1 deletion template/managed/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
Expand Down Expand Up @@ -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)

Expand Down
Loading