Tomato Components Laravel Package

Technical Evaluation

Architecture fit. tomato-components is a presentation-layer Blade component kit — no domain logic, no data access, no service integrations. That is architecturally the safest kind of dependency to evaluate: the blast radius of a bad component is a rendered page, not corrupted state. The catch is that fit is effectively binary. It only pays off inside a Splade rendering + TomatoPHP admin panel stack. On Inertia, Livewire, Filament, or a bespoke Blade design system, reuse value approaches zero and the "integration" becomes a rewrite of Splade-specific markup. As a TPM, treat this package evaluation as a proxy decision: are we standardizing internal tooling on Splade + TomatoPHP for the next 12–18 months? If that platform bet isn't already made or being made, this package is not the thing to decide on.

Integration feasibility. Mechanically trivial: one composer require, service provider auto-discovery, a vendor:publish step. Realistically the cost sits in discovery, not installation. There is no documentation, no component index, and no test suite — the catalogue lives entirely in resources/views/components/. Budget one to two engineer-days to audit the package source and enumerate the components, plus one day to rebuild a single existing screen as a timed spike. That spike delta is the entire business case, and it should be measured before any adoption commitment.

Technical risk. The risk profile here is not "it breaks loudly on install" — it's "it silently rots in place." Zero stars, zero dependents, last release February 2023, a release note that is nothing but a compare URL, and a single maintainer. Compatibility with current Laravel and Splade versions is unverified, not verified-good; the declared constraint ranges are the only evidence available. The three concrete failure modes we should pre-commit mitigations for are Tailwind purging the package's utility classes (vendor paths missing from content globs), component name collisions with Splade's own card/modal/alert (silent prop-dropping, not an exception), and visual regression after a framework upgrade with no upstream tests to catch markup drift.

Key questions to resolve before a go decision:

• Which five to ten components do we actually need, and are any of them load-bearing on multiple screens?
• Does composer why-not pass cleanly against our target Laravel/PHP/Splade versions — and are we prepared to walk away rather than force with --ignore-platform-reqs?
• Is Splade + TomatoPHP already committed, or is this package being used to justify that platform choice retroactively?
• Who is the named owner of the pinned version, the component inventory, and the fork point?
• Does an internal design system already exist? Two component systems is worse than one imperfect one.
• What is the exit cost — how many screens would need rework if we drop the package in six months?

Integration Approach

Stack fit is a hard gate, not a preference. Pre-flight check: splade and/or tomato-admin must already be in composer.json. If not, stop — the components will not drop in, and the effort converts from "adopt a kit" to "build a design system with a stranger's markup as reference."

Migration path. This package migrates nothing; it is incremental and additive. Do not plan a sweep. Adopt per component, starting with one screen we already own and have already written in plain Blade — a settings page or CRUD index is the ideal known-good target. Rebuild it on a throwaway branch with the package's components and time both versions. Under roughly a 20% delta, the kit costs more in ownership than it saves in keystrokes and we decline.

Compatibility discipline.

• Pin the exact version (:1.0.3), never a floating ^1.0, and commit the lockfile. An undocumented patch should not be able to change component markup inside our dependency tree.
• Never bump in a composer update sweep. Bump deliberately, on a branch, with the view-directory diff read and classified (dependency constraint change vs. Blade slot fix vs. cosmetic).
• Publish config once, diff against the package default, commit only intentional deviations with a comment explaining why. That comment is the future migration note.

Sequencing (four to six weeks elapsed, low engineer load):

1. Week 1 — Stack gate and source audit. Verify Splade/TomatoPHP presence and run composer why-not. Enumerate resources/views/components/ and produce the component inventory. Confirm whether it ships compiled assets or expects a Vite build.
2. Week 1–2 — Single-screen spike. Timed rebuild of one existing screen. Decision gate: adopt, or extract patterns and stop.
3. Week 2 — Wrapper layer. One in-house wrapper file per adopted component (x-admin-* aliases), created on day one. This is the single swap point per component and the only place design tokens live without forking upstream markup.
4. Week 2–3 — Hardening. Add vendor paths to Tailwind content globs, write one rendering smoke test per adopted component, wire only per-component assets into vite.config.js where the package allows it.
5. Week 3–4 — Containment. Restrict usage to internal admin surfaces only. Nothing customer-facing, nothing with an availability commitment.
6. Ongoing — Fork decision gate. For anything load-bearing, copy the Blade source into our own namespace under the MIT license header before the first break, not after. Plan to extract liked patterns into a thin in-house library and drop the Composer requirement.

Strategic framing to hold onto: this is code to acquire and own, not a dependency to install and forget. The realistic play is an acquirable scaffold — spike, inventory, copy, absorb — with the Composer requirement being a temporary convenience rather than a permanent commitment.

Operational Impact

Maintenance. We own it from the day it lands. Upstream cadence is effectively zero, so maintenance cost is a function of our own change rate, not theirs. Budget a named owner with a small recurring allocation — enough to review upgrade diffs, re-run the smoke and browser tests after any Laravel or Splade bump, and keep the inventory current. Record in the repo: installed version, install date, commit SHA of the pinned tag, and the list of components in use. That paragraph is the difference between a cheap speedup and a quiet liability.

Support. There is none, in any meaningful sense — zero dependents means no community to search, no issues to mine, no Stack Overflow trail. Internal escalation path terminates at the owner. This is acceptable only because the package is internal-facing and MIT-licensed, so "support" is fully substitutable by "we can read and edit the source." It is not acceptable if anyone expects a security patch cadence or compatibility guarantees with future Laravel majors.

Scaling. Technically it scales fine — static Blade rendering adds no runtime complexity. The scaling risk is organizational: if multiple teams start consuming it independently, they will diverge on markup, overrides, and Tailwind configuration. The wrapper component layer is the mitigation, and it must land in week two, not later. Enforce the rule that pages never call package components directly.

Failure modes to instrument for:

• Silent unstyled render — Tailwind content globs missing vendor/ paths, or a Tailwind major/prefix mismatch. Verify visually, never by grepping the DOM; classes present in markup prove nothing.
• Silent name collisions with Splade — load order decides the winner and props are quietly ignored rather than throwing. Aliasing everything through x-admin-* makes the ambiguity disappear.
• Stale caches masquerading as bugs — renders under php artisan serve but not after deploy is almost always compiled views or a missing view:cache in CI.
• Published assets missing in the release pipeline — public/vendor/… gitignored and never copied; symptom is unstyled staging and fine local.
• Forced republication destroying customizations — ban vendor:publish --force from muscle memory; diff first.
• Deferred runtime failure from forced installs — --ignore-platform-reqs moves the break to an admin screen at the worst possible moment.
• Post-upgrade visual regression — no upstream tests exist. Mitigate with three to five browser tests (Playwright screenshots or Pest browser) over the screens using these components, run in CI. That is the only thing that will tell us a Blade slot changed shape.

Ramp-up. Onboarding a new engineer is cheap if three artifacts exist: the component inventory, the wrapper convention, and the pinned version with its rationale. Without them, knowledge is entirely tribal in vendor/ and every new engineer burns their first hour re-deriving the catalogue. Write an ADR that states the platform bet, the adopted component list, the measured spike delta, and the fork point. Revisit it at the next Laravel major — that is the natural moment to decide whether to extract in-house and drop the requirement.

Metrics to report after adoption: measured time delta on the spike screen, count of components adopted versus available, percentage of admin screens using wrappers only, and number of upstream-fix dependencies we absorbed ourselves. If that last number trends up, the extract-and-own path should be accelerated.