Tomato Roles Module Laravel Package

Technical Evaluation

Architecture fit

• tomatophp/tomato-roles-module is a TomatoPHP admin-panel module that wraps role/permission management (a Filament UI layer over spatie/laravel-permission, plus migrations, seeders, and a TomatoRolesServiceProvider). It is additive: it registers resources, permissions and a config publish tag, and does not restructure the host application.
• Fit is therefore conditional on our stack already being Laravel + Filament and either using or willing to adopt spatie/laravel-permission. If our authorization is policy/gate-based with a custom RBAC schema, this module pulls a second source of truth into the app and should be rejected.
• The package is opinionated about the TomatoPHP ecosystem (admin panel layout, tomato-admin/tomato-php sibling packages, its own Setting/helpers conventions). Adopting one module tends to pull in the family; treat it as an ecosystem decision, not a component decision.

Integration feasibility

• Low code-level effort: composer require, publish config/migrations, run migrations, register the plugin on our Filament panel. Realistically 1–3 days for a first environment if Filament is already installed, longer if it is not.
• The hard work is not installing it, it is reconciling its permission naming/seeding with the permissions our app already checks. Budget most of the effort for a permission-naming migration and a backfill.
• v1.0.3 is a patch release with no documented content beyond a diff link. There is no changelog prose, no migration notes, and no confirmation that the patch is non-breaking. Treat the semver signal as unverified.

Technical risk

• Maintainer concentration / bus factor: single-maintainer, high-velocity vendor. Expect frequent small releases and limited long-term support guarantees. Mitigation: fork-pin or vendor the package internally.
• Transitive coupling: version churn in spatie/laravel-permission, Filament major versions, and PHP/Laravel minimums can make a module lag behind framework upgrades. A patch bump may exist precisely to chase one of these — unknown from the notes.
• Security surface: an admin UI that grants roles and permissions is privilege-escalation-adjacent. Any authorization bypass or mass-assignment issue in the module is high severity for us. Requires review of the resource forms and the guard/model configuration, not just the install.
• Undocumented patch: a v1.0.2 → v1.0.3 bump with no notes means we cannot assess regression risk; treat as an unknown-risk change and diff it before adopting.

Key questions

• What exactly changed in v1.0.3 (diff review: migrations, permission names, guard config, Filament API usage)? Is it genuinely non-breaking?
• Which spatie/laravel-permission and Filament major versions does it pin, and does the pin match ours?
• Does the module support multi-guard and multi-tenant permission scoping, or assume a single default guard?
• What is the vendor's release/support policy, security disclosure process, and test coverage? Is CI green on our PHP and Laravel matrix?
• Can we consume it as a thin UI over our existing permission tables, or does it require its own seeders and schema conventions?

Integration Approach

Stack fit

• Required: Laravel (recent LTS-ish major), Filament panel, spatie/laravel-permission. Preferred: an existing TomatoPHP admin panel, since the module assumes sibling packages and helpers.
• If we run Filament but not TomatoPHP, expect to disable or stub some plugin registrations; verify the module does not hard-depend on tomato-admin views at runtime.
• If we run neither Filament nor Spatie, this is a poor fit — the value is the prebuilt management UI, and we would be paying the dependency cost for something we can build in a few hundred lines.

Migration path

1. Sandbox install in a disposable branch; run composer require, publish config and migrations, migrate a restored production-like dump.
2. Diff v1.0.2 → v1.0.3 explicitly and record findings; do not adopt an undocumented patch blind.
3. Inventory existing roles/permissions in code (Gate::define, policies, can: middleware, seeders) and produce a mapping table to the module's naming.
4. Backfill: write a one-off migration/command to reconcile existing roles/permissions tables with the module's expected seed set; keep the old checks working until the map is complete.
5. Enable the Filament resource for a small pilot group of admins before broad rollout.

Compatibility

• Verify against our exact PHP, Laravel, Filament and Spatie versions via composer why-not and a CI matrix run.
• Check for config/migration collisions if we already publish Spatie's config — the module may ship its own copy or override guard settings.
• Confirm the module's migrations are additive and idempotent; any table rename or column drop in a patch release is a blocker.

Sequencing

• Phase 1 (week 1): evaluation spike, diff review, dependency audit, go/no-go.
• Phase 2 (weeks 2–3): permission inventory + naming map + backfill script in staging.
• Phase 3 (week 4): pilot with a restricted admin group behind a feature flag; capture audit-log gaps.
• Phase 4: general rollout, then freeze the version (pin exact, commit lockfile) and schedule quarterly upgrade reviews.
• Do not start Phase 2 until the Phase 1 diff review clears the undocumented patch.

Operational Impact

Maintenance

• Ongoing cost is dominated by upgrade tracking, not bug fixing: every Filament or Spatie major bump likely requires a module bump. Budget ~1–2 engineer-days per quarter for version upkeep, plus a spike whenever the vendor ships a minor.
• Because the v1.0.3 notes are empty, we must institutionalize our own change review: pin exact versions, read diffs, and keep a fork if the vendor goes quiet for more than a couple of release cycles.

Support

• No commercial support expected; upstream is community/single-vendor. Internal ownership must be assigned to a named team, with a documented fallback: we can replace the Filament resource layer while keeping Spatie tables intact, so the exit cost is moderate, not severe.
• Escalation for security issues in an admin RBAC UI should route to our security owner, not just the platform team.

Scaling

• The package is a UI and schema layer; scaling characteristics are those of spatie/laravel-permission. Permission checks are cached, so read load is fine; the risk is cache invalidation storms after role edits and slow admin queries on very large permission sets.
• Multi-tenant or per-team scoping is the likely breaking point — validate before we depend on it for tenant isolation.

Failure modes

• Silent privilege drift: module seeders and app seeders disagree, granting or revoking permissions unexpectedly after a deploy.
• Admin lockout: a role edit removes the last admin's access; needs a break-glass path independent of the UI.
• Upgrade breakage: framework bump makes the module incompatible, blocking our own upgrade train.
• Undocumented patch regressions: v1.0.3-class releases introducing config or migration changes we did not review.
• Cache staleness: permission cache not cleared on deploy, producing inconsistent authorization across nodes.

Ramp-up

• A Laravel developer familiar with Filament needs roughly half a day to be productive with the module, plus 1–2 days to understand the permission model and our naming map.
• Add 1 day of security review for anyone touching the role-management UI.
• Document a short internal runbook: how to grant/revoke safely, how to clear the permission cache, how to recover from lockout, and how to review an upstream diff before upgrading.