Peridot Expect Plugin Laravel Package

Technical Evaluation

Architecture fit. This is not a Laravel package — it is a Peridot plugin. Peridot is a standalone BDD/spec runner for PHP in the RSpec/Jasmine lineage, and its extension model is a peridot.php bootstrap that returns a closure receiving the Configuration object. This plugin uses that hook to register the expect() assertion DSL into the spec scope so tests read as expect($value)->to->be->equal(42) rather than $this->assertEquals(42, $value).

The integration surface is therefore narrow and well-bounded:

• Dev-only dependency. No service provider, no facade, no config publishing, no Artisan commands, no migrations, no runtime request path.
• It does not touch Laravel's container, Eloquent, HTTP kernel, or queue. The only thing it shares with a Laravel app is Composer and the vendor/ directory.
• Its real coupling is to Peridot and to the expectation-php/expect assertion library — two additional, independently-versioned dependencies that also need to be alive.

Integration feasibility. Mechanically trivial: composer require --dev expect/peridot-expect-plugin, add one line to peridot.php, write specs under spec/. The difficulty is not installation — it is that adoption presumes Peridot is (or becomes) your test runner. Laravel's first-party stack is PHPUnit, with Pest as the modern expressive layer. Choosing this plugin means running a second test framework and assertion vocabulary alongside the default one: a second binary, a second CI stage, a second directory convention, and two ways to write a test in the same repo.

Technical risk. The signals here are weak across the board: 1 star, 0 dependents, composite score 0.035. There is no observable production usage anywhere in the ecosystem, which means no community-derived bug surface, no Stack Overflow corpus, and no third-party tutorials.

The last row is the one that actually matters to a TPM: the worst outcome isn't the plugin breaking, it's the plugin appearing to work while assertions are inert.

Key questions.

1. Is Peridot already the team's runner anywhere, or would this introduce a second framework? (If the latter, the decision is "adopt Peridot," not "add a plugin.")
2. What is the repo's last commit date, open-issue count, and supported PHP range? Star count is a proxy; commit recency is the fact.
3. Does the plugin pin Peridot and expect to versions that still support our PHP version (8.2/8.3/8.4)?
4. Can it emit JUnit XML or otherwise feed our CI reporting and coverage pipeline?
5. What fails if the plugin bootstrap is missing or throws — do specs error loudly, or does the suite pass vacuously?
6. Who owns the fork if upstream goes dark? Is there a named maintainer and a documented patching path?
7. Does it duplicate a capability Pest already provides (higher-order expectations, expect()->toBe()) at zero marginal cost?

Integration Approach

Stack fit. Treat it as pure dev tooling, not a Laravel dependency.

• composer require --dev only; confirm composer install --no-dev produces an image with zero trace of it.
• No service provider registration in config/app.php or bootstrap/providers.php — the package has none to register, and none should be invented.
• Keep it out of the default composer test script if PHPUnit remains the primary runner; give it its own script alias and its own CI job.
• Isolate spec files in a dedicated spec/ tree so the tests/ suite and its PHPUnit config remain untouched.

Migration path. Do not frame this as a migration. Two honest paths:

1. Peridot already present — add the plugin additively to one spec directory, run it in a non-blocking CI job for a sprint, then decide.
2. Peridot not present (the likely case for a Laravel shop) — the real cost is a runner migration measured in engineer-weeks, and the capability being gained (a chained expect() grammar) is already available in Pest with a vastly larger ecosystem. This is a spike, not a backlog ticket. My recommendation is to not adopt; if the goal is expressive assertions, standardize on Pest and revisit only if a team is already committed to Peridot for other reasons.

Compatibility. Before writing a line of spec code, resolve the transitive graph:

• expect/peridot-expect-plugin → peridot-php/peridot → PHP constraint.
• expect/peridot-expect-plugin → expectation-php/expect → PHP constraint.
• Check for conflicts on shared dev dependencies (PHPUnit polyfills, sebastian/*, mocking libraries) introduced by Peridot's own test deps.

Pin all three explicitly in composer.json rather than floating ranges, and add a composer why-not php ^8.x check to the upgrade runbook. If a Laravel major upgrade bumps PHP, this plugin is a candidate to break first and be maintained last.

Sequencing.

1. Verify viability (0.5 day): clone, run its own test suite, inspect last commit, check PHP constraint against our runtime, confirm the DSL actually registers.
2. Prove non-execution safety: deliberately break the bootstrap and confirm CI goes red. If it stays green, stop — the plugin is unusable regardless of quality.
3. Pilot (1 sprint): one spec directory, one CI job, no gating. Measure developer friction.
4. Decide: adopt narrowly, or retire and consolidate on PHPUnit/Pest.
5. If adopted: fork to an internal namespace, document the pinning policy, assign an owner.

Operational Impact

Maintenance. Effectively zero upstream maintenance is the base case given the adoption numbers. Budget for a vendored fork carried in a private Composer repository, or accept that a composer update can silently strand the toolchain. Any fork inherits three packages, not one — the maintenance obligation is larger than the plugin's own footprint suggests. Assign a named owner before adoption; "the team" is not an owner.

Support. No vendor, no commercial option, no community. Support means reading the plugin source, then Peridot's source, then the expect library's source — in that order, and possibly all three for a single defect. Stack Overflow and blog coverage are effectively nil. Realistic MTTR for a novel failure: half a day to two days for a capable PHP engineer, with no escalation path.

Scaling. Adequate for small suites. Constraints compound at scale:

• Peridot's runner is single-process by default; parallelism via ParaTest is not the same maturity story as PHPUnit's.
• No first-party JUnit XML or coverage integration — CI dashboards, flaky-test detection, and PR annotations may need custom glue.
• A second runner doubles CI matrix cost and cache footprint for zero additional coverage.

Failure modes.

Ramp-up. Laravel developers own PHPUnit fluency; Peridot's DSL is a new vocabulary with a chained grammar (->to->be->equal(), negation modifiers, custom matchers) that has its own idioms and edge cases. Realistic ramp-up is 1–2 days per engineer to productive, plus ongoing context-switching cost for anyone moving between tests/ and spec/. Onboarding material must be written in-house — nothing exists to link to.

Bottom line. Architecturally harmless and operationally cheap to trial, but it solves a problem the stack does not have, on a foundation with no adoption and no maintenance signal. Recommend a time-boxed spike at most; default position is to decline and standardize expressive assertions on Pest, which already occupies the same niche with a healthy ecosystem.