Skip to content

v0.5.0 — API freeze

Latest

Choose a tag to compare

@s2x s2x released this 17 Aug 20:39

Supports liblbug 0.19.x. Prebuilt binaries for PHP 8.2–8.5 on linux-x86_64, linux-aarch64
and macos-arm64 are attached below, with SHA256SUMS.

This release adds no features. It writes down what the package promises to keep, ahead of the
SemVer declaration in 1.0.0 — because after that, a class nobody thought about is a class that
went public by accident and cannot be taken back.

The promise is a test, not a paragraph

tests/Unit/ApiSurfaceTest requires every class under src/ to be listed as public or internal.
A new class fails the suite until someone chooses. It also asserts that everything except the
exception classes is final, and that no internal class has lost its @internal.

Verified that it is not vacuous: dropping a stray class Scratch {} into src/ fails two of
its four tests with messages naming the offender.

Three things stated rather than implied

  • Calling Connector is covered by SemVer; implementing it is not. It carries one method per
    liblbug C call, and liblbug is itself pre-1.0, so methods will be added in minor releases as the
    C API grows. Freezing it at our 1.0 would have cost a 2.0.0 for the first new C call worth
    exposing. The same applies to Handle, public only because those signatures need a type.
  • A liblbug minor release requires a release here. The README now carries the compatibility
    matrix and the reason: patch releases inside a supported series pass the runtime check, 0.20
    is refused until we ship support, because the alternative is reading a struct at wrong offsets.
  • Windows is not supported — not "not yet". Nothing has ever run there. The platform table
    says which combinations are covered by CI, which ship as binaries, and which merely ought to work.

Also

  • Config::with() rejects names it does not know. A typo used to escape as a bare \Error that
    no catch (LadybugException) would see. PHPStan cannot catch this — a mixed ...$overrides
    signature is opaque to it — which is why the check is hand-written.
  • Cdef, ValueReader, ExtHandle and FfiHandle are marked @internal.
  • QueryException::$parameters holds the values that were bound. __toString() never prints them,
    so an uncaught exception or a log line does not leak them, but var_dump() and anything that
    serialises the object will. Documented as the trade it is.

Found by releasing

build/ was not ignored, so 0.4.0 committed the generated PIE mirror into the repository. That
deadlocked this release: the mirror script refuses to publish from a dirty working tree, and its
own output was what made the tree dirty. Reading the script would not have shown it; running it
did.