Presenter Laravel Package

Technical Evaluation

Verdict: Adopt conditionally. The package is a thin, MIT-licensed convenience wrapper around a pattern most Laravel teams re-implement by hand, so technical risk is low but so is strategic upside. Its value is convention enforcement, not capability. Treat it as a pattern library we can fork, not a platform dependency.

Architecture fit

• Fits Laravel's MVC seam cleanly: a Presentable trait on Eloquent models exposes present(), returning a presenter class that formats model attributes for the view layer. This is additive — no service provider gymnastics, no schema, no query interception.
• Keeps formatting logic out of Blade and out of models, which aligns with how we already want to separate domain entities from transport/view concerns. It complements, rather than competes with, API Resources: Resources own JSON contract shape, presenters own human-readable display strings.
• The main architectural caution is that presenters can become a junk drawer. Without a written boundary ("formatting only — no queries, no relation traversal, no HTML-heavy markup"), this package accelerates the exact coupling we're trying to avoid.

Integration feasibility

• Composer-installable, Laravel package auto-discovery expected. Integration is a same-day spike: composer require hemp/presenter, one trait on one model, one presenter class, one Blade call site.
• No data migration, no runtime infrastructure, no cross-service contract. Reversible by deleting a class and a trait use.

Technical risk

• Ecosystem signal is weak: 247 stars but 0 dependents is the key data point. Stars measure interest; dependents measure production trust. We would be one of the first real consumers, meaning undiscovered edge cases surface on our schedule, not the maintainer's.
• Maintainer concentration: single-maintainer, low-velocity project. A 2024-03-22 release suggests it isn't abandoned, but it isn't actively hardened either.
• Mitigating factor: the code surface is small enough that a full read-through is an afternoon, and MIT licensing makes forking or vendoring a one-engineer-day contingency. Blast radius if the project stalls is near zero — this is a leaf dependency, not a transitive one.
• Framework drift: the live risk is a future Laravel major making the package's illuminate/* constraints unsatisfiable. Since the package touches stable Eloquent/container APIs, a fork patch is typically a composer.json bump.

Key questions for the maintainer / internal spike

1. Which Laravel and PHP versions are supported today, and is there a stated policy for new Laravel majors?
2. Does present() memoize the presenter instance per model instance, or instantiate on every call? (Determines whether calling it repeatedly in a Blade loop is free.)
3. Does the package alter toArray()/JSON serialization, or is presenter output strictly view-layer? We must not silently change API payloads.
4. How does a presenter handle null attributes and null relations — graceful pass-through or exception?
5. Can presenters be resolved through the container with dependencies injected, or are they attribute-only?
6. Is there a documented successor or transfer plan if the maintainer steps away?

Integration Approach

Stack fit

• Appropriate for Laravel 9–11 / PHP 8.1+ applications rendering server-side Blade or Inertia views. Poor fit for API-only services, where API Resources already own the presentation concern and a second formatting layer would be duplication.
• Do not introduce it into codebases already standardized on a different presenter implementation (laracasts/presenter or hand-rolled accessors). Two coexisting presenter idioms is worse than either one alone.

Migration path

1. Compatibility spike (0.5 day): install on a scratch branch, exercise on the lowest and highest Laravel versions we run, read the full source, run one presenter through a real Blade template. This doubles as the due-diligence code review.
2. Insulation layer (0.5 day): define App\Presenters\Presenter extending the vendor base class and require all presenters to extend ours. This buys us a single swap point if upstream breaks or we fork.
3. Convention ADR (0.5 day): document allowed presenter responsibilities, naming, return types, escaping expectations, and the explicit rule that presenters never trigger lazy loads or queries.
4. Pilot (2–3 days): two low-risk models (e.g., User, Invoice) with a small number of call sites. No API surface touched. Measure developer reaction and diff size.
5. Ratchet, don't rewrite: apply to new view work and models touched for other reasons. Do not schedule a backfill of existing formatting helpers — the ROI is negative.

Compatibility and sequencing

• Run the spike before the ADR, and the ADR before any second team touches the package. The failure mode here is divergent usage, not broken code.
• Pin exact versions in composer.json and rely on Dependabot/Renovate to surface upstream releases for review rather than auto-merging them.
• If the spike reveals unsupported Laravel versions, vendor the source into app/Support/Presenter or a path repository under MIT and remove the external dependency entirely. At this code size, vendoring is a legitimate first-choice option, not a fallback.

Operational Impact

Maintenance

• Near-zero ongoing cost in steady state. No migrations, no config, no background jobs, no storage.
• The real maintenance cost is governance: reviewing presenter classes for scope creep and preventing a second formatting idiom from emerging. Budget a small amount of architecture-review attention, not engineering hours.
• Fork contingency: ~1 engineer-day to lift and maintain in-house. Acceptable.

Support

• No vendor SLA. Support is our own GitHub-issue triage plus the ability to patch. Acceptable only because the blast radius is confined to view rendering — a total failure is a rendering bug, not data loss or outage.
• Assign one named owner (backend lead) so forks and version bumps have a decision-maker.

Scaling

• CPU and memory impact is negligible relative to Blade rendering and query time.
• The scaling risk is indirect and worth calling out explicitly: presenters are a convenient place to hide $this->model->relation->field, which converts a clean eager-loaded page into an N+1 storm that's invisible in code review. Enforce the no-relations rule or add a query-count assertion in tests.
• For high-traffic pages, memoize expensive derived strings at the presenter level or precompute at write time; the package provides no caching, which is appropriate — caching belongs to us.

Failure modes

• Presenter class not registered on the model → runtime error at first render; caught immediately in the pilot.
• Null attribute or null relation inside a presenter → exception or silent empty string depending on implementation; verify in the spike and standardize null handling.
• Accidental serialization leakage → presenter output bleeding into JSON responses and breaking client contracts; mitigated by keeping presenters out of toArray() paths and covering with a contract test.
• Unescaped HTML from a presenter in Blade → XSS surface; the convention doc must state that presenters return plain strings or explicitly-marked safe HTML, and that {!! !!} requires review.
• Static analysis gaps → no enforced return types; add PHPStan rules and typed presenter methods to compensate.

Ramp-up

• A mid-level Laravel developer is productive in under half a day; the concept is familiar and the API is small.
• The onboarding cost is cultural, not technical: new hires must learn our presenter conventions and, critically, learn when not to use one. Put that in the ADR and link it from the repo README.
• Net recommendation: proceed with the spike and the insulation layer, keep the pilot scoped to two models, and re-evaluate at the next Laravel major. If the package fails the compatibility spike, vendor it — the decision cost of doing so is lower than the cost of dependency uncertainty.