Rusty Laravel Package

Technical Evaluation

Architecture fit. Rusty implements the "documentation as tests" pattern (Rust-style doctests) for PHP: it extracts executable code samples from docblocks and runs them as part of the test suite. Architecturally this is a clean, orthogonal fit for a Laravel codebase — it lives entirely at the test layer, adds no production runtime dependency, and provides a CI guardrail against documentation drift. That property is genuinely valuable for SDK-style packages, service classes with usage examples, and onboarding-oriented docs. However, the package itself is archived, 47 stars, 0 dependents — it is effectively a single-author reference implementation, not an ecosystem-standard tool. The opportunity score (2.38) reflects that the pattern is useful while the package is low-value as a dependency.

Integration feasibility. Low-to-moderate as-is, moderate as a fork. Rusty is expected to integrate through a PHPUnit test case or suite that you point at source directories; the integration surface is small (test harness + docblock parser), which makes a fork tractable. But any Laravel 10/11 codebase on PHP 8.2+ with PHPUnit 10/11 will almost certainly require patching: PHPUnit's extension/listener APIs, test-suite configuration, and attribute-based metadata have all changed since this package's active period.

Technical risk. High:

• Unmaintained upstream — no fixes for PHP minor-version drift or PHPUnit API churn; archival means zero support path.
• Transitive dependency exposure — docblock parsing typically pulls phpdocumentor/reflection-docblock and related packages; we inherit their CVE exposure with no upgrade path from the author.
• Arbitrary code execution by design — running code embedded in comments is a deliberate feature, but it means documentation content becomes executable input. That is acceptable inside CI with review, but it must never run against untrusted branches or generated docs without gating.
• Determinism and flakiness — examples that touch time, IO, or framework bootstrapping can produce brittle failures unrelated to the code under test.

Key questions.

1. Which PHP and PHPUnit versions does the last release actually support, and how large is the fork delta to reach PHP 8.3 / PHPUnit 11?
2. What is the hook mechanism — custom TestCase, suite, listener, or extension? This determines fork cost.
3. Does it isolate each example (fresh process/state), or run everything in one PHPUnit process?
4. Are there maintained alternatives that cover the same need (e.g. phpstan/phpstan-doctest, or a generated-test approach)?
5. What is the actual organizational goal — doc accuracy, onboarding examples, or API contract verification? The build-vs-fork decision hinges on this.
6. Who owns the fork, and what is the deprecation trigger?

Integration Approach

Stack fit. Conceptually compatible with Laravel's default PHPUnit setup, but written in a pre-Pest, pre-PHPUnit-10 era. Pest-based projects would need an adapter or a bridge test case. No framework coupling is an advantage — this is not a Laravel-specific package and does not conflict with the framework's service container or bootstrap.

Migration path. Three viable routes, in order of preference:

1. Adopt a maintained equivalent (phpstan/phpstan-doctest if PHPStan is already in the stack) — lowest total cost of ownership, no fork.
2. Fork and vendor Rusty into the monorepo as a first-party dev dependency, pinned to a known-good PHPUnit major, with a written maintenance contract.
3. Build a minimal internal equivalent — a Pest dataset or PHPUnit data provider that scans configured directories, extracts fenced examples, writes them to a temp test file, and runs them in a subprocess. Roughly 150–250 LOC, fully owned, no archival risk.

Compatibility. Assume breakage on PHPUnit 10+ (metadata, lifecycle, result APIs) and on PHP 8.x (typed properties, deprecations in older parsing code). The docblock parser is the most version-sensitive component.

Sequencing.

1. Discovery spike (1–2 days): confirm supported versions, hook point, and fork delta; shortlist alternatives.
2. Fork or replace decision gate — do not proceed to pilot without a named owner.
3. Pilot (1 sprint): enable on one package/module with 10–20 curated examples; measure CI time delta and false-positive rate.
4. Hardening: subprocess isolation, per-example timeouts, exclusion annotations, CI job separated from unit tests.
5. Rollout or sunset: expand corpus incrementally; retire if maintenance cost exceeds the drift it prevents.

Operational Impact

Maintenance. The dominant cost. Archived software is our software: budget roughly 3–5 engineer-days for initial fork remediation and 1–2 days per quarter for PHP/PHPUnit upgrades. This must be an explicitly funded line item, not absorbed silently by the platform team.

Support. None from upstream. Internal expertise will be concentrated in one or two engineers — a key-person risk. Document the fork's design and upgrade procedure from day one.

Scaling. Docblock parsing is fast per file but scales linearly with source count; on a large monorepo this becomes a meaningful addition to CI wall-clock and should run as a separate, parallelizable CI job rather than inside the unit-test suite. Per-example process isolation trades speed for reliability — recommend isolation for anything touching the container, database, or clock.

Failure modes.

• Silent skip — examples failing to parse or being excluded quietly, giving false confidence in doc accuracy.
• Brittle examples — flaky failures from time/IO/framework bootstrapping, eroding trust in the suite.
• Execution risk — doc content executed in CI; needs branch-protection and review gating.
• Dependency rot — transitive CVEs with no upstream patch, forcing emergency vendoring.
• Abandonment drift — the fork diverges from any future upstream (there is none) and becomes tribal knowledge.

Ramp-up. Low for documentation authors — writing examples is intuitive and the feedback loop is fast. Medium-to-high for platform owners, who must understand the extraction and execution model well enough to debug edge cases and own upgrades. Expect half a day of onboarding for contributors and two to three days for the owning engineer.

Recommendation. Do not adopt the archived package as a direct dependency. Treat the pattern as worth evaluating: run the discovery spike, prefer a maintained alternative, and only fork Rusty if documentation accuracy is an explicit quality goal with a named owner and a funded maintenance line.