Tomato Category Module Laravel Package

Technical Evaluation

Package: tomatophp/tomato-category-module — v1.0.1 (MIT), part of the TomatoPHP module suite.

The decision in one line. This is a buy-to-save-a-few-dev-days decision on a package with zero external validation (0 stars, 0 dependents, one patch release, last shipped 2024-03-20). The functional scope is genuinely useful; the supply-side risk is not priced into the package's own README, so a TPM has to price it.

Architecture fit. The shape is right: taxonomy as a self-contained module with its own migrations, an Eloquent model exposing a hierarchical tree, a polymorphic relation so any model can be categorized, translation support for labels, and prebuilt admin CRUD. That keeps categorization orthogonal to domain tables instead of bolting a category_id column onto every entity — the correct long-term structure. The value is concentrated in the admin/CRUD layer and the migration set; the underlying schema is something a mid-level Laravel developer would produce in a day. Fit is strong only if you are already on the Tomato stack (Laravel + Livewire + Filament, or the Splade variant). On Nova, Backpack, or hand-rolled Blade you are buying a UI layer you will discard.

Integration feasibility. Mechanically low: composer require, publish migrations/config/assets, php artisan migrate, register the panel plugin. The cost lives in seams you inherit rather than choose:

1. Admin stack alignment — the description references both Splade and Tomato/Filament; confirm which build you are pulling and that its Filament/Splade major matches your host app.
2. Translation strategy — TomatoPHP modules typically lean on spatie/laravel-translatable; that decision changes column types and query patterns, and it is hard to reverse later.
3. Tree strategy — adjacency-list, nested-set, or closure-table determines whether moving a subtree is one UPDATE or a bounded rewrite. At 10k nodes this is a performance decision, not a style preference.
4. Morph map — polymorphic pivots need a stable morph map; adopting one late means data migration.

Technical risk, ranked.

1. No external validation (high). Zero stars and zero dependents means zero peer review, zero third-party blog posts, zero Stack Overflow answers. Every bug becomes "read the source." For anything on a revenue path (catalog, content classification), you are the de facto maintainer.
2. Staleness / bus factor (high). Single-vendor OSS, last release 15+ months ago. A dormant module in a fast-moving ecosystem (Filament majors ship roughly yearly) drifts out of compatibility without anyone filing an issue.
3. Ecosystem coupling (medium-high). Cohesive-by-design suites create gravitational pull; exit cost is a bespoke taxonomy implementation — bounded, but real, and it lands on whoever inherits the codebase.
4. Change opacity (medium). v1.0.1's notes are an auto-generated changelog link with no commit summaries. You cannot distinguish a typo fix from a silent dependency bump.
5. Versioning discipline (low-medium). Post-1.0, so semver should hold, but there is only one data point.

Key questions to resolve in the spike (not by email — the maintainer may be unresponsive):

• Does composer.json support your Laravel (10/11/12), PHP (8.2/8.3), and Filament (v3/v4) versions? Run composer why-not rather than reading badges.
• Filament plugin or Splade package — which artifact does the tag actually build, and does it match your admin layer?
• Which tree algorithm, and what is the measurable cost of a subtree move at production node counts?
• Does the pivot cascade on category delete, or leave orphans? Is deletion soft or hard?
• Are migrations additive-only and table-namespaced (collision risk with an existing categories table)?
• Is there CI, and what does test coverage actually exercise? (Assume no CI until proven otherwise.)
• What is the real diff between v1.0.0 and v1.0.1?

Integration Approach

Stack fit. Assumes Laravel 10/11, PHP 8.1+, Livewire, and either Filament v3 or Splade. If your admin layer is anything else, scope the evaluation down to the model/migration pair — and at that point a leaner, better-maintained taxonomy package is almost certainly the better call.

Build vs. buy, quantified. Hand-rolling category CRUD with translations and a polymorphic pivot is roughly 3–6 developer-days including tests. This package saves most of that, but adds 1–2 days of spike and diff verification plus a permanent "we own the fork if it breaks" liability. Net positive only if you are staying in the Tomato stack and taxonomy is not revenue-critical. If either condition fails, hand-roll or pick a package with dependents. The opportunity score (6.59) reflects that the problem is worth solving; the package score (0.4) reflects that this artifact has not earned the trust.

Migration path. Two separable workstreams:

• Schema adoption — publish and run migrations as an isolated deployment step, never bundled into a feature release. Verify with --pretend, confirm table namespacing, confirm rollback works.
• Data adoption — if a categories table or enum-based taxonomy already exists, budget a backfill plus a dual-read period behind a feature flag. Re-pointing historical entity→category links through the polymorphic pivot is the bulk of the effort and the line item to size first; it is largely independent of which release you adopt.

Fork posture (a TPM decision, not a dev one). MIT + zero dependents means a hard fork into your org namespace is cheap and often correct: it converts an unmaintained dependency into owned code on your upgrade cadence. Decide this before integration, not after the first blocked Filament upgrade — retrofitting a fork mid-project is where schedules slip.

Compatibility axes to verify. Framework constraint satisfaction; database driver parity (tree implementations often depend on transactional semantics and behave differently on MySQL vs. Postgres vs. SQLite in CI); Livewire version alignment with Filament; locale fallback behaviour if you ship multi-language.

Sequencing.

1. Sandbox spike (1–2 days): install in a throwaway app, publish, migrate, attach categories to a dummy model, exercise reorder/delete in the admin.
2. Diff review v1.0.0→v1.0.1 — gating step the release notes do not let you skip.
3. Fork-or-depend decision, then dev integration with backfill script and a rehearsed rollback.
4. Staging at production-shaped data volume — measure tree render and subtree move cost.
5. Production behind a flag; retire the legacy taxonomy path only after one full read/write cycle.

Operational Impact

Maintenance. Ongoing cost is dominated by Filament/Laravel major upgrades, not by this package's churn — which is precisely the problem, because the package is not tracking them. Budget explicit re-verification work at each Filament major. Pin exact patch versions, commit the lockfile, and upgrade deliberately. An unmaintained module plus a floating constraint is how you get a broken admin panel on a Tuesday.

Support. GitHub issues, no SLA, likely slow or absent response. There is no community layer to fall back on at 0 stars — no blog posts, no answered questions, no second implementation to diff against. If taxonomy sits on a revenue-critical path, pre-approve "fork and patch" as a normal operating mode with an owner and a time budget, rather than treating it as an incident.

Scaling. Reads are cheap and cacheable — the category tree is a natural long-TTL cache invalidated on write. Watch four things: N+1 queries when rendering trees without eager loading; subtree-move cost if the implementation is nested-set; polymorphic joins on the hot path ("all entities in category X"); and pivot indexes — index both category_id and the morph pair. Load-test at realistic node counts and entity-per-category fan-out before launch.

Failure modes.

• Migration collision or duplicate publish → mitigate with --pretend dry runs and a rollback-verified migration step.
• Orphaned pivot rows on category deletion if cascade is not enforced at the FK level — enforce in the schema, not application code.
• Tree corruption under concurrent reorder — reordering must be transactional and ideally serialized; test with concurrent admin writes.
• Silent behaviour change from an unread patch upgrade → mitigated by the diff-review gate.
• Filament upgrade breaking plugin registration — surfaces as missing admin screens; trivially caught in staging, easily missed if admin surfaces are untested.
• Missing locale fallback producing blank category labels in secondary languages — a user-visible defect that looks like a data bug.

Ramp-up. Low for a Laravel developer on day-to-day use (attach categories, manage the tree). Moderate for anyone customizing the Filament resource or reasoning about tree internals — and there is no documentation to lean on beyond the source. Estimate well under a sprint for basic integration by one developer; onboarding cost is acceptable for a team already fluent in the Tomato/ Filament idiom and notably higher for anyone else.

Recommendation. Conditional go. Adopt only if (a) you are already committed to Laravel + Filament/Splade, (b) taxonomy is not revenue-critical, and (c) you accept forking as a routine maintenance mode. Otherwise treat it as a reference implementation: read the migrations and model, build the small piece you actually need, and avoid inheriting a dormant single-vendor dependency for a problem worth a few developer-days.