Rusty Laravel Package

Product Decisions This Supports

• Documentation-as-contract for anything developer-facing. If the roadmap includes a public PHP SDK, API client, or plugin surface, Rusty is a working reference for the "docs that can't rot" pattern: example snippets in docblocks become executable tests, so a stale README fails CI instead of a customer's first integration. That directly informs whether documentation quality is a feature investment or a support cost center.
• Build vs. buy, resolved toward build. With 47 stars, zero dependents, and an archived repo, this is not a purchase decision — it's a spec. The decision it supports is "do we spend 1–3 engineer-days reimplementing the extraction-and-execute loop against our current PHPUnit version, or do we accept no coverage for doc examples?" That is a tractable, low-risk trade against a ~few-hundred-line concept.
• Release-gating policy. Doctests change what "green build" means: doc examples become a merge blocker. That's a policy decision with real cost (slower PRs, more test maintenance) and real payoff (fewer "your example doesn't work" tickets). Rusty lets you prototype that policy cheaply before committing.
• SDK surface-area review. Forcing every public method to carry a runnable example is an excellent forcing function for API design — if an example is ugly, the API is ugly. Useful input to API-freeze and backward-compatibility discussions.
• Dependency lifecycle review. A useful case study for the team's dependency policy: archived, unmaintained, zero downstream users. Good material for codifying "max acceptable maintenance risk for dev-only dependencies" before the next library choice comes up.
• Not a decision driver for application code. This is a library-authoring tool. It should not shape roadmap for internal CRUD apps, monoliths, or services where docblocks are sparse and behavioural coverage comes from integration tests.

When to Consider This Package

Consider the pattern (and read this repo as the reference implementation) when:

• You ship a PHP library or SDK where docblock snippets are the primary onboarding path and are read far more than the source is.
• Your stack is legacy-adjacent: roughly PHP 5.6–7.x with PHPUnit ≤5-era APIs. Rusty predates modern PHPUnit; expect the integration points to be incompatible with PHPUnit 10/11 and PHP 8.3+ syntax.
• You have capacity to own the code. Archived means no security patches, no PHP-version bumps, no issue triage. Treat adoption as a fork, not a dependency — vendor it, add it to your own CI, assign an owner.
• You can sandbox code execution. Doc examples are evaluated at test time; verify the execution path (this likely uses eval or a generated temp file) against your security review, static-analysis stack (PHPStan/Psalm will not see through it), and coverage tooling.
• You're running a time-boxed spike — a day to prove the workflow, then decide build-vs-drop. That's the highest-value use of an archived repo with 47 stars.

Look elsewhere — or drop the idea — when:

• You're on modern PHPUnit/PHP 8.x+. The integration surface will fight you; the reimplementation is cheaper than the archaeology.
• The consumers are internal application developers, not external integrators. Integration and contract tests already cover the risk; doctests mostly duplicate them.
• Your org bans eval in CI or requires full static-analysis coverage of test code — a hard blocker regardless of package quality.
• You need maintenance guarantees (SLAs, CVE response, vendor support). Archived fails procurement on principle.
• You actually want behavioural specs, not documentation examples — Behat/Codeception-style BDD, or plain PHPUnit @example/data providers, address that need with maintained tooling. For docblock correctness (types, signatures) rather than behaviour, PHPStan/Psalm already do the job.
• Your docs are prose-first (guides, tutorials, migration notes). Rusty only validates fenced code blocks; it does nothing for the content that usually rots fastest.

How to Pitch It (Stakeholders)

To executives (30 seconds): This is a small, archived open-source tool that turns code samples in documentation into automatically-run tests — the same idea Rust uses, ported to PHP. We are not recommending adoption: it's unmaintained, has no downstream users, and won't run on our current PHP/PHPUnit versions. We are recommending we copy the idea for our developer-facing SDK, where broken examples are a recurring, quantifiable support cost. Estimated cost: 1–3 engineer-days to build a minimal in-house version, with no new dependency and no maintenance risk. Success metric: reduction in "example doesn't work" support tickets and time-to-first-successful-call for integrators.

To engineering (the real pitch):

• What it does: extracts fenced code blocks from PHPDoc comments and executes them as part of the test suite. Docs and behaviour drift apart → CI goes red.
• Why not just use it: last touched years ago, targets PHPUnit's old extension points, zero dependents means zero field-testing, and archived means we own any CVE. The execution model (verify: likely eval-based) is opaque to PHPStan/Psalm and to coverage tooling.
• What we'd build instead: a PHPUnit test case that reflects over the classes we choose, pulls ```php blocks out of docblocks, writes each to a temp file, and asserts it runs clean — scoped to our public SDK namespace only. Roughly a few hundred lines, PHPUnit-version-agnostic, no eval, and we control the sandbox.
• Guardrails we'd set up front: explicit allowlist of namespaces, no network or filesystem access in examples, hard timeout per snippet, and a documented escape hatch for examples that are illustrative-but-not-runnable.
• What we'd measure: number of doc examples under test, CI time added (target: under 60s), and the count of docs-vs-code drift incidents caught before release.

The one-line framing: Rusty is a design reference, not a dependency — buy the idea, build the twenty lines that matter.