Weave Code
Crucible Laravel Package
cruciblephp/crucible
Crucible is a PHP package that provides a clean, extensible foundation for building robust applications. It pairs sensible defaults with flexible configuration and a developer-friendly API, helping teams ship maintainable features faster.
Crucible is a lightweight Laravel/PHP package that brings a clean, expressive API to common application tasks. It integrates smoothly with Laravel’s service container and configuration system, so you can adopt it incrementally without disrupting existing code.
- Laravel-ready service provider and configuration
- Fluent, readable API for concise workflows
- Framework-agnostic core usable in plain PHP
- Test-friendly design with predictable behavior
- PSR-compliant structure for easy integration
Frequently asked questions about Crucible
- How do I install Crucible in a Laravel project?
- Add cruciblephp/crucible to require-dev at a pinned version, alongside your existing Pest stack, in a single pilot repository rather than across your whole codebase. You will need a stock Laravel + Pest project, a working coverage driver such as pcov or Xdebug, and JUnit XML output enabled for the oracle comparison path. No application code changes are required because Crucible only touches the test and CI plane.
- Will Crucible run my existing PHPUnit and Pest suites unchanged?
- Yes, that is the core design goal: Crucible is an independent PHP runner that executes PHPUnit and Pest suites without requiring test rewrites. It validates itself against Pest as an oracle through compat-check, which is a strong engineering signal. That said, v1.1.5 shipped roughly fifteen parity and correctness fixes against stock Laravel + Pest projects, so run compat-check on your own suite instead of assuming perfect parity.
- Is Crucible a drop-in replacement for Pest?
- Positioning-wise yes, but adoption-wise treat it as a substitute decision: it overlaps pestphp/pest, pest-plugin-laravel and pest-plugin-phpstan, so you are replacing tooling rather than adding a layer. The assessment explicitly flags whether the vendor supports full Pest replacement versus a coexisting mutation and coverage role, plus licensing and commercial support terms, as open questions. Pilot Crucible alongside Pest at a pinned version instead of removing Pest up front.
- Which PHP and Laravel versions does Crucible support?
- The package targets PHP 8.3+ and its tested matrix skews modern, with references to PHP 8.5 and 8.3 typed constants. The release context does not document a clear Laravel version matrix, so confirm your specific combination by running compat-check against your own skeleton. Pin the Crucible version and re-verify whenever you upgrade Laravel or Pest.
- What is compat-check and should I run it in CI?
- compat-check treats your existing Pest suite as the oracle and compares Crucible's results against it, with v1.1.5 improving drift reporting so per-test failure messages and Crucible's own errors are surfaced instead of PHPUnit noise. Run it as a non-blocking CI job on a pilot repository before you trust Crucible's verdicts as a merge gate. It needs JUnit XML output enabled and a functioning coverage driver.
- Are there known Crucible bugs that could make failing tests pass?
- Yes. v1.1.5 fixed a negated toThrow() semantic bug that could silently pass failing tests whenever anything was thrown, which is a false-green failure mode. The same release added Quirk::ThrowInterfaceAsMessage because toThrow(Throwable::class) was being read as an interface match rather than Pest's message-fragment reading. Pin the version, add targeted tests around exception assertions, and keep compat-check running so divergent semantics surface as diffs rather than silent passes.
- How does Crucible's change-based test selection work?
- It selects the tests affected by the files you changed so you get fast feedback locally and on pull requests without running the full suite every time. Treat it as a feedback optimization rather than a correctness guarantee, and keep a full-suite run as the merge gate. Pair it with compat-check until Crucible's Pest parity has stayed green across several releases.
- How does crucible mutate affect CI time?
- crucible mutate is Crucible's mutation-testing engine, and it persists verdicts between runs so resumed runs can reuse prior judgments. v1.1.5 fixed resumed runs retaining stale verdicts, which deliberately triggers a one-time full re-judge on the first resume after upgrading. That is the correct behavior, but plan for a predictable CI cost spike on that first run.
- Is Crucible's sharding duration-balanced?
- No. The release explicitly corrects an earlier RESEARCH.md claim and states that shard wall-clock will be uneven. Do not assume linear speedup or size CI capacity around perfectly balanced shards. Measure your own suite's shard timings before relying on sharding to cut pipeline duration.
- Does Crucible add runtime dependencies or touch production code?
- No: Crucible belongs in require-dev and operates only on the test and CI plane, covering test execution, expectations, arch-style rules, coverage, sharding and mutation. There is no runtime dependency, no production code path, and no database or queue surface, so blast radius is low. The risk to manage is semantic drift in test outcomes, not production behavior.
Weaver
How can I help you explore Laravel packages today?