Peridot Laravel Package

Technical Evaluation

Architecture fit

• Peridot is an event-driven BDD/spec framework for PHP built around an event emitter core (Evenement) with decoupled reporters and plugins. That architecture is genuinely extensible — reporters, hooks, and plugins subscribe to lifecycle events (runner.start, test.passed, etc.) rather than being hard-wired into the runner.
• It occupies the "RSpec/Jasmine for PHP" niche: describe/it specs with $this-bound context, beforeEach/afterEach, and focused/pending specs. Teams coming from Ruby, JS, or Pest-style testing will find the syntax familiar; teams standardized on PHPUnit xUnit conventions will not.
• Fit is therefore narrow and cultural, not technical. It does not replace PHPUnit's ecosystem (assertions are Peridot-specific, mocking comes via the peridot-doubles plugin, coverage depends on Xdebug/phpdbg rather than built-in tooling). It is best evaluated as an alternative spec runner, not a drop-in test platform.

Integration feasibility

• Composer-installable as a require-dev dependency with a single vendor/bin/peridot entry point and standard non-zero exit codes, so wiring it into CI is trivial. Configuration is a peridot.php file plus CLI flags.
• Coexistence with PHPUnit is technically possible — both can run in the same pipeline against the same codebase — which lowers the cost of a pilot. There is no first-class Laravel integration (no artisan command, no RefreshDatabase-equivalent trait), so Laravel teams would be writing their own bootstrap for the application container and database lifecycle.
• The real feasibility constraint is runtime support. The last release was January 2017, targeting PHP 5.x/7.x-era language and dependency constraints. Running it on PHP 8.x is unverified and likely to require patching (deprecations, reserved-word collisions, and transitive dependency pins on evenement and symfony/console). This should be treated as a hard gate, validated in a spike before any commitment.

Technical risk

• Abandonment risk (high): no releases in ~8 years, 325 stars, low opportunity score. No security patching, no PHP version tracking, no maintainer response path. Any defect becomes an internal fork obligation.
• Ecosystem drift risk (high): pinned transitive dependencies will conflict with modern packages over time, forcing --ignore-platform-reqs hacks or dependency isolation.
• Talent/tooling risk (medium): IDE support, static analysis integration, and coverage reporting are weaker than PHPUnit/Pest, which affects developer throughput and code-review quality more than it affects runtime correctness.
• Architectural risk (low): the event-driven design itself is sound and the plugin surface is clean; risk here is maintenance, not design.

Key questions

• What PHP version(s) must we support for the next 24 months, and does Peridot run cleanly on all of them today?
• Is spec-style BDD a real team preference, or is this a stylistic choice that PHPUnit dataproviders + Pest would satisfy at lower risk?
• Who owns the test framework internally if upstream is dead — do we have appetite to fork and maintain?
• Which plugins are we dependent on (peridot-doubles, peridot-concurrency, peridot-scope), and are those equally abandoned?
• What is the exit cost if we adopt and later migrate to Pest/PHPUnit — how many specs and how much bespoke plugin code would be stranded?

Integration Approach

Stack fit

• Composer/PHP projects: fine. Laravel/Symfony applications: workable but requires custom bootstrapping, since there is no framework bridge. This is the main integration tax — expect a small internal adapter (container boot, DB transaction wrapping, config loading) that is ours to own forever.
• Where the stack already uses PHPUnit, Peridot is additive complexity: two runners, two assertion idioms, two CI configurations. That cost is only justified if the spec syntax meaningfully improves test readability for the team.

Migration path

• Do not migrate. Adopt incrementally behind a pilot: install as require-dev, write net-new specs in Peridot for one bounded module, keep existing PHPUnit suites untouched.
• Define a decision gate up front (e.g., "if the PHP 8 spike fails or requires >2 days of patching, stop"). This keeps sunk-cost pressure low.
• If the pilot succeeds, expand module-by-module with a written convention doc; if it fails, the removal cost is a composer remove plus deleting one directory.

Compatibility

• Pin the PHP version and lock file for the pilot. Run composer audit and inspect the resolved dependency tree for outdated/abandoned packages before proceeding.
• Verify coverage tooling end-to-end (Xdebug or PCOV plus whatever report format CI consumes) — this is the most common late-stage surprise.
• Confirm the mocking story (peridot-doubles) is adequate; if not, the framework loses most of its value versus Pest.

Sequencing

1. Timeboxed spike on the current PHP runtime: install, run a 20-spec sample, produce a coverage report, confirm exit codes in CI.
2. Assess plugin needs (mocks, concurrency, reporters) and their maintenance status.
3. Build the framework bootstrap adapter (container + database lifecycle) if the stack is Laravel/Symfony.
4. Add a parallel CI job; do not replace the existing PHPUnit job.
5. Pilot one module with a named owner and a 4–6 week review checkpoint.
6. Decide: adopt (with a documented fork/maintenance plan), or standardize on a maintained alternative (Pest is the natural substitute for spec-style PHP testing).

Operational Impact

Maintenance

• Highest ongoing cost item. With upstream dormant, every PHP minor release, dependency bump, and CI image change is an unpriced internal ticket. Budget for a designated maintainer and, realistically, a vendored fork in the repo or a private Composer package.
• Dependency pinning will progressively block unrelated upgrades; expect to negotiate between "upgrade Symfony" and "keep the test runner working."

Support

• No vendor, no SLA, no security advisories. Community support is thin — 325 stars implies a small StackOverflow and issue-tracker footprint, so internal debugging of runner internals is likely.
• Onboarding documentation is essentially the README plus source. Assume we author our own runbook.

Scaling

• Suite runtime scales linearly by default; the concurrency plugin offers parallelism but is itself unmaintained and adds flakiness surface. For large suites this is a real throughput ceiling compared with PHPUnit's --parallel or Pest's parallel runner.
• Reporter/observability ecosystem is thin: JUnit XML and TeamCity reporters exist but expect to hand-roll anything for modern dashboards.

Failure modes

• PHP upgrade breaks the runner mid-quarter, blocking the platform roadmap — highest-severity, highest-likelihood.
• Dependency resolution conflicts force --ignore-platform-reqs, producing silent divergence between local and CI environments.
• Custom bootstrap drift causes tests to pass locally and fail (or worse, silently skip) in CI.
• Plugin abandonment removes mocking or concurrency capability with no replacement path.
• Bus-factor of one: the person who understood the event/plugin model leaves.

Ramp-up

• Low for writing specs (a day for anyone with RSpec/Jest exposure), moderate for CI/bootstrap setup (days), high for extending internals or writing custom plugins (weeks, and only worth it if we commit long-term).
• Net: the learning curve is not the problem — the ownership curve is. Treat this as adopting a small internal project, not adopting a package, and price it accordingly before recommending it over a maintained alternative.