Tomato Roles Laravel Package

Product Decisions This Supports

• Admin RBAC as a scoped roadmap milestone. This package directly supports internal access-control work for back-office, support, and operations features — giving admin users roles, permissions, and gated actions in the Tomato Admin/Splade panel. Scope it explicitly to internal tooling authorization, not customer-facing access control.

• Tactical roadmap acceleration, not differentiation. Adopt it as a time-boxed accelerator for an "admin roles and permissions" milestone if the product is already committed to the Tomato Admin/Splade stack. It removes boilerplate CRUD (role editor, permission attach, user assignment, prebuilt seeders) — it buys speed, not product value.

• Build vs. buy / adopt decision. Adopt only for straightforward ACL inside an existing Splade codebase. For core authorization, complex or row-level policy logic, multi-tenancy, SSO, or compliance-sensitive access control, the better default is spatie/laravel-permission directly with a hand-built admin UI (~2–4 engineer-days) or an internal layer behind an abstraction — because the authorization engine, not the admin screen, is where the risk lives.

• Feature use cases in scope: role/permission CRUD; assigning roles to admin users from the panel; gating Splade admin routes, menus, and actions; seeding default admin/viewer roles per environment; prototyping permission-aware admin workflows before committing to a long-term authorization model.

• Decision guardrail. Treat this as an opportunistic internal-tool dependency, not a platform bet. Weigh the weak adoption signal (2 stars, 0 dependents, no CI, no support channel) against evidence of active maintenance (v1.1.20 → v1.1.21 with an external PR merged). The v1.1.21 fix lands in a filterable UserTable, meaning the shipped surface is broader than a narrow role editor — scope blast radius before assuming "role editor only."

• Fund validation as part of the decision, not cleanup. Authorization defects are silent privilege escalation, not visual glitches. Budget the spike and the negative-case test suite into the adoption decision. Stale permission caches and cross-guard leakage are the two failure modes that become security incidents.

• Preserve the exit path. Keep domain code asking $user->can('resource.action') and vendor the package behind an abstraction. The swap back to Spatie (or an internal build) becomes a matter of replacing internals — a reversible decision, which de-risks approving it at all.

When to Consider This Package

• Consider it when: the product is already on Tomato Admin + Splade; the need is plain admin-side RBAC; the internal user base is small; the team can pin exact versions, review or fork the source, and wrap adoption with tests, audit logging, and upgrade notes.

• Strong fit criteria: Laravel/Livewire/Splade compatibility is verified against our exact version matrix; the permission model matches role-based admin needs (no ABAC, no row-level rules); the team explicitly accepts low ecosystem validation; and a fallback to spatie/laravel-permission is feasible within a sprint.

• Look elsewhere when: authorization is customer-facing, security-critical, compliance-driven, multi-tenant, or requires ABAC, SSO, fine-grained row-level policies, high-scale auditability, or vendor support.

• Look elsewhere also when: the product is not on Tomato Admin/Splade. The package's entire value is the pre-wired role/permission UI — if your admin UI is Filament, Nova, Inertia, or a custom SPA, you gain nothing over the underlying Spatie schema you likely already have.

• Hard stops: confirm whether it wraps Spatie or reimplements the engine. Wrapping = thin UI shell over a battle-tested core (good risk profile). Reimplementing = a bespoke authorization core with near-zero external review (do not adopt for anything security-relevant). Also confirm multi-tenancy/team scoping before committing — if the package is global-scope-only and you need tenants, that's a wrap-it-yourself effort.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost accelerator for internal admin access control — it gives us role and permission management in the admin panel out of the box, saving roughly a sprint of boilerplate if we're already on the Tomato Admin/Splade stack. It is an internal-tooling dependency, not a customer-facing or strategic platform bet. The main risk isn't abandonment (the package is actively patched) — it's correctness: authorization bugs are silent privilege escalation. So we approve it as a reversible, vendored dependency with a mandatory validation spike and negative-case tests, and a documented one-sprint exit to raw spatie/laravel-permission.

For engineering: Verify the stack match and whether it wraps Spatie before writing any code. Pin exact versions (Laravel, Livewire, Splade, this package) as a tested matrix — this is a single-maintainer package where a minor bump surfaces as a Livewire failure, not a clean composer conflict. Prove deny-by-default in 15 minutes (HTTP 403 and hidden UI), test cache invalidation round-trips (assign → allow → revoke → deny without restart), and test guard isolation explicitly. Keep domain logic behind $user->can(), centralize permission strings in one constants/enum file, and treat the package as forked-and-vendored with a named owner. Budget ~0.5 day to first working role assignment, 1–2 days to production confidence, and 2–5 engineer-days per Laravel major for upkeep.