Teapot Laravel Package

Technical Evaluation

Context. 273 stars, composite score 2.045, MIT license, last release 2024-10-07, repository metadata unknown. The package is a narrowly scoped utility: it gives HTTP status codes a readable, named vocabulary instead of bare integers. That framing matters — this is a developer-ergonomics dependency, not infrastructure, and should be judged on readability ROI and supply-chain risk rather than on architectural weight.

Architecture fit

• Leaf, stateless dependency: no service provider obligations beyond optional registration, no configuration files, no migrations, no persistence, no lifecycle hooks. It sits at the HTTP edge — controllers, form requests, API resources, middleware, and exception-to-response mapping.
• Orthogonal to the Laravel request lifecycle, so it can be adopted per module without a framework-wide commitment.
• The real architectural value is a shared contract vocabulary: named status symbols make API behavior legible in code review, in cross-team contracts, and in generated documentation.
• Principal fit risk is duplication: Laravel already ships Symfony HttpFoundation, which exposes Response::HTTP_* constants, and Illuminate\Http\Response re-exports them. The package must demonstrably add something (enum type safety, reason phrases, ergonomics) over what the stack already provides.

Integration feasibility

• Composer-only install with no publishable assets; a competent engineer can pilot this in hours, not weeks.
• The gating checks are trivial but non-negotiable: PHP version floor, whether the API is class-constant or PHP 8.1 enum based, and whether it returns integers, PSR-7 objects, or Symfony responses.
• Because the surface is tiny, a one-to-two day spike can fully characterize the library before any production exposure.

Technical risk

• Runtime blast radius: low. Constants resolve at compile/opcache time; there are no I/O, concurrency, or state concerns.
• Product risk: moderate. Shipping a second convention alongside Symfony's constants creates "two ways to do the same thing," which is a durable review-friction tax if not governed.
• Supply chain: moderate-to-high for anything strategic. Small star count, likely single maintainer, and an unknown repository — no visible issue tracker, CI, or security policy to diligence. That is a blocker for treating it as a standard, not for a bounded pilot.
• Type-safety caveat: plain integer constants do not prevent an invalid status code from being passed. Only an enum-backed API delivers the correctness benefit that would justify the dependency.

Key questions

• What exactly is the API surface — constants, enum, value object, reason-phrase lookup — and which IANA and non-standard codes does it cover (418, 499, 599)?
• What is the PHP version floor, and does it use enums?
• What is the concrete differentiator versus Symfony\Component\HttpFoundation\Response::HTTP_*?
• What are the maintenance signals: commit cadence, open-issue backlog, release history, BC/semver policy, security reporting channel?
• Does it interoperate with PSR-7/PSR-17 and Symfony Response, or is it integer-only?
• Who owns it internally if upstream goes quiet?

TPM position: Conditional pilot, hold on standardization. Worth a time-boxed spike for API-heavy modules; do not make it a house standard until the repository is diligenced and the differentiator versus Symfony constants is proven.

Integration Approach

Stack fit

• Target Laravel 10/11 on PHP 8.1+ with Composer 2; coexists cleanly with HttpFoundation and PSR-7. No conflicts expected because the package occupies the same conceptual slot as existing constants rather than a new one.
• Best-fit contexts: API-first services where status codes are part of a published contract, and centralized exception→response mapping where magic integers currently concentrate.

Migration path

• Introduce in a single bounded context first — typically the API exception handler or one resource controller — rather than sweeping the codebase.
• Establish the convention explicitly: HTTP-emitting code uses named symbols; raw integer literals are disallowed in that layer. Without this rule, adoption decays into mixed style.
• Enforce mechanically with PHPStan/Psalm rules or a PHP-CS-Fixer rule so the convention survives team turnover.
• Migrate opportunistically ("leave it better than you found it") rather than via a dedicated refactor epic; the payoff per file is small and does not justify a big-bang change.

Compatibility

• Validate Composer constraints against the Laravel/Symfony version matrix before piloting; a PHP floor above the team's baseline is an immediate reject.
• Check for namespace/class collisions with existing helper classes and for duplicate-constant ambiguity during code review.
• Confirm behavior for non-standard codes if the product emits any (e.g., 418, 499, 599) — silent fallback to a generic reason phrase would be a contract bug.
• Confirm the constant-vs-enum model matches the team's PHP baseline; enum adoption is a one-way door for older services.

Sequencing

1. Repository due diligence — README, CI status, issue/PR activity, release notes, security policy.
2. Time-boxed spike comparing the API against Symfony constants; produce a one-page decision memo.
3. Pilot PR in one module with tests asserting status codes and reason phrases.
4. Land the lint/static-analysis rule and a short convention note in the engineering handbook.
5. Roll out module by module; track adoption via the lint rule's violation count.
6. Re-evaluate at the next major Laravel/PHP upgrade, when the dependency is most likely to block.

Operational Impact

Maintenance

• Ongoing cost is minimal: no runtime configuration, no migrations, no background processes. The recurring work is version pinning and a periodic dependency review.
• Exit cost is unusually low — the functionality can be inlined as a constants class in hours — which materially de-risks the supply-chain concern.
• Pin to a minor version and subscribe to release/advisory notifications; treat any major bump as a planned upgrade item.

Support

• MIT, community-supported, no SLA and no vendor accountability. Name an internal owner (platform or API guild) so the convention has a steward.
• Fallback plan should be documented up front: fork, vendor, or inline. Given the surface area, any of these is a same-day operation.

Scaling

• Runtime scaling: effectively zero impact. Constants resolve at compile time and are opcache-friendly; there is no per-request cost at any traffic level. This should not appear on a performance risk register.
• Organizational scaling is where the value and the cost live: consistency across many services and teams is the payoff, and governing one convention instead of two is the price. The TPM lever here is the lint rule, not the library.

Failure modes

• Abandonment / unpatched advisory — low severity given the tiny surface, mitigated by trivial inlining.
• PHP floor bump or breaking major — blocks framework upgrades; surfaces during upgrade planning.
• Ambiguous or incorrect reason-phrase mapping — misleading API responses and confused clients; caught by pilot tests if they assert reason phrases, not just codes.
• Convention drift — Symfony constants and package symbols used side by side, producing review friction and inconsistent contracts; mitigated only by the enforcement rule.
• False confidence in type safety — integer constants still permit invalid codes where an enum was assumed; validate at the boundary regardless.
• Namespace collision with existing helpers during rollout.

Ramp-up

• Engineer ramp-up is under an hour; the API is self-documenting by design.
• The TPM investment is the convention document plus the enforcement rule — roughly a day of platform work — without which adoption will not stick.
• Secondary benefit: named status symbols measurably reduce onboarding friction and review commentary on HTTP semantics, though this is a soft productivity gain that should not be sold as a hard ROI case.