Praspel Extension Laravel Package

Technical Evaluation

What this package is. atoum/praspel-extension is a plugin that teaches atoum — a PHP unit-testing framework — to consume Praspel contracts (PHP Realistic Annotation and Specification Language), the Design-by-Contract DSL from the Hoa project. In practice it wires Praspel’s @requires / @ensures / @invariant annotations into atoum’s assertion and data-generation pipeline so contract compliance can be exercised from an atoum test suite. It is a thin bridge, not a test framework or a static analyzer.

Architecture fit. The plugin is architecturally clean in isolation — atoum has a first-class extension mechanism ($script->addExtension(...)), and Praspel is a separate language layer, so the dependency arrows are one-directional. But the fit for a modern Laravel/PHP codebase is poor for three structural reasons:

1. It is an atoum extension, not a PHPUnit/Pest extension. Laravel ships PHPUnit/Pest by default; adopting this package means adopting atoum as a second test runner (or replacing PHPUnit entirely).
2. Praspel is not a Composer-only dependency. The contract engine relies on the praspel C extension (plus hoa/praspel and related Hoa libraries) loaded into the PHP runtime. That is a runtime/platform dependency, not a vendor directory — it must be compiled for the target PHP ABI on every CI image and developer machine.
3. The repository is a Contributions-* repo, not a first-party package — an early signal that it was never promoted to a supported, versioned product line.

Integration feasibility. Low. The stack required is: atoum (niche, maintained but not the market default) → hoa/praspel (Hoa project defunct) → ext-praspel (C extension, no PHP 8 support) → PHP 5.6/7.0-era runtime. Every layer is either abandoned or off the mainstream path. The 0.12 composite score, 4 stars, 0 dependents, and a 2017 last release are consistent with this: there is effectively no ecosystem validation and no downstream signal to lean on.

Technical risk. Very high:

• Archived and unpatched. No security fixes, no PHP-version compatibility work, no upstream triage.
• Compilation fragility. A C extension pinned to an old ABI will not build on PHP 8.x; even on 7.x it is platform-sensitive (Linux-only in practice; Windows/macOS friction).
• Composer resolution hazards. Old version constraints on atoum/atoum and Hoa packages will collide with a modern Laravel dependency graph; installing it in the main app is likely to force downgrades.
• Silent-skip failure mode. If the extension is absent, contract checks may be skipped or degraded rather than hard-failing — creating false confidence, the worst outcome for a correctness tool.
• Opportunity cost. The ideas (contracts as executable specifications, generated test data) are valuable; the implementation is a dead end.

Key questions to answer before any investment:

• Do we have a genuine Design-by-Contract requirement (regulatory, safety-critical, or spec-heavy domain), or is this "we like the idea of contracts"?
• Can the same outcome be achieved with PHPStan/Psalm assertions, PHPUnit data providers, or property-based testing (e.g., Eris/Infection) — all of which are maintained and PHP-8-native?
• Is there any existing Praspel annotation inventory in the codebase that would need to be preserved, or is this greenfield?
• Are we willing to own a fork of an archived C extension plus a dead PHP library — i.e., accept indefinite maintenance burden with no upstream?
• What is the blast radius if the CI contract job is red for a week because a base image changed?

Verdict: technically interesting as a reference implementation of contract-driven testing; not viable as a production dependency in a Laravel stack.

Integration Approach

Stack fit. Effectively zero for a current Laravel application. Laravel 9/10/11 target PHP 8.1+; this package’s entire transitive stack (Hoa, ext-praspel, old atoum) targets PHP 5.6–7.x. There is no plausible path to running it inside the application’s primary composer.json without downgrading PHP and the framework. It also does not integrate with Pest, PHPUnit, Paratest, or the standard Laravel php artisan test workflow.

Migration path (if the capability is genuinely needed). Do not migrate the application to this package. Instead:

1. Inventory any Praspel annotations in the codebase (@requires, @ensures, @invariant, @behavior, @throwable) and classify them as (a) business invariants worth preserving, (b) input validation, (c) documentation that has drifted.
2. Re-express category (a) as PHPStan/Psalm @assert annotations, native assert()-style guards, or explicit domain-invariant tests; category (b) as Laravel Form Requests/validators; category (c) as docblocks or delete.
3. Replace generated-data testing with PHPUnit data providers, Faker-based fixtures, or a property-based library — all maintained, PHP-8-native, and compatible with the existing CI.
4. Only if a hard requirement exists (e.g., contractual evidence that specifications were executed), stand up an isolated, pinned Docker job (php:7.0-cli + compiled praspel + atoum) that runs against a read-only copy of the relevant classes. This keeps the dead stack entirely outside the production dependency graph.
5. Decommission with a documented sunset date; do not let the isolated job become load-bearing.

Compatibility. PSR-0/PSR-4-era autoloading; no PHP 8 attributes, no typed properties, no enums, no readonly, no match. atoum’s extension API has drifted since 2017 and the plugin is unlikely to load against atoum 3.x/4.x without patching. Expect to vendor and patch.

Sequencing. Decide-on-requirement → inventory → re-express → validate parity → sunset. The decision gate is step 1; if there is no hard requirement, stop there.

Operational Impact

Maintenance. Effectively total ownership. The repo is archived; PRs and issues will not be triaged upstream. Any fix (PHP version bump, security patch in a transitive Hoa package, CI image update) becomes internal work. Budget for a named owner and a quarterly compatibility review — otherwise it rots silently.

Support. No vendor, no community (4 stars, 0 dependents), sparse and partly French-language documentation from a defunct project. Onboarding materials must be written internally. Tooling like IDE autocomplete, static analysis of .phpt-style contracts, and stack traces across the C boundary are all weak.

Scaling. Two distinct concerns:

• Suite scale: Praspel’s contract-driven data generation is combinatorial by nature; a handful of contracts with wide input domains can dominate CI wall-clock time or exhaust memory before the suite even starts.
• Team scale: two niche DSLs (Praspel annotations + atoum extension conventions) must be learned by every contributor who touches contract-bearing code. Knowledge concentrates in one or two people — a key-person risk.

Failure modes (ordered by likelihood and severity):

1. Base-image drift breaks ext-praspel compilation → entire contract job goes red; no upstream fix.
2. Silent skip when the extension is not loaded → green build, zero contract coverage (highest-severity because it is invisible).
3. Composer conflict during a routine framework upgrade → forced pinning or removal under time pressure.
4. Non-deterministic generation → flaky CI, eroded trust, quarantined tests.
5. Memory exhaustion on complex contracts → job killed, partial results.
6. Security exposure from an unpatched transitive dependency if the package is ever loaded in a non-isolated runtime.

Ramp-up. High for the value delivered. A new engineer needs: atoum fundamentals (1–2 days), Praspel annotation semantics and its generator model (3–5 days), and the extension’s registration/configuration conventions (1 day) — roughly one engineer-week before productive use, with no external courses, books, or community to accelerate it. Compare to PHPStan/Psalm assertions, where most PHP engineers are already productive within hours and the tooling is on the mainstream support path.

Recommendation. Treat this as a reference architecture, not a dependency: mine it for how contract-driven data generation can be surfaced through a test framework, then implement the same capability with maintained, PHP-8-native tooling. If a hard contractual-evidence requirement exists, isolate the legacy stack in a pinned, non-production CI job with an explicit sunset plan and a named owner.