Vendra Permission Laravel Package

Technical Evaluation

Evidence basis. Two artifacts inform this review: the v1.11.0...v1.12.3 changelog pointer (no release body, no migration guide) and the package's internal development skill (skills/vendra-permission-development/SKILL.md), which is unusually revealing — it documents namespace, boundary, tenancy, persistence, and Filament conventions. The scoring metadata (1 star, 16.96) should be read with care: this repo is an explicit read-only subtree split of the misaf/vendra monorepo, so stars and release history measure the split artifact, not the platform. Adoption signal must come from the monorepo, not here.

• Architecture fit. This is not a standalone ACL library — it is a module in a platform. It sits inside the permission domain, owns Misaf\VendraPermission namespace, ships domain models, factories, seeders, policies, observers, console commands, Filament admin UI, config, migrations, translations, and tests. It extends Spatie Permission models rather than replacing them, and derives tenancy exclusively from misaf/vendra-support abstractions (TenantAwareness, BelongsToTenant, TenantSchema, TenantResolver). Consequence for a TPM: the real decision is "do we adopt the Vendra platform's authorization module," not "do we install a Composer package." If we are not already on Vendra, this package is not independently adoptable, and that changes the entire business case.
• Integration feasibility. Mechanically clean for a Laravel team — Composer install, service-provider/plugin auto-registration, publish config and migrations, add trait, seed. The work concentrates in four places: (1) reconciling our existing Gate/Policy definitions with the module's role/permission resolution; (2) the TenantTableRegistry registration requirement — every table whose migration calls TenantSchema::addTenantColumn() must be registered in this package's service provider so vendra-tenant:enable {tenant} can retrofit schemas migrated before tenancy existed; (3) Filament v5 panel wiring through the module Plugin; (4) lockstep version alignment across the Vendra package graph. Feasible, but it is a platform integration, not a package install — scope it accordingly.
• Technical risk.
  • Lockstep versioning (high). The skill mandates self.version alignment across the Vendra package graph. Vendra modules cannot be upgraded independently — one permission-module bump implies a coordinated multi-package release wave. That is a recurring, structural cost, not a one-time one.
  • Dual upstream surface (medium-high). The module extends Spatie Permission models, so we inherit Spatie's API, caching, and CVE stream on top of Vendra's own. Two upstreams to track, and the transitive-API policy explicitly makes removing a Vendra-exposed dependency a breaking change.
  • Tenant retrofit / schema drift (high). The create migration conditionally includes tenant_id through TenantSchema. Schema output therefore depends on when and how the package is installed, and a missed TenantTableRegistry registration silently produces a table that the tenant-enable command cannot retrofit. Dev/prod schema parity and tenant-onboarding correctness are both at stake.
  • Opacity of releases (high). Zero descriptive release content across four versions. We cannot state what changed from 1.11.0 to 1.12.3; authorization packages are privilege-escalation targets and patch releases are a common vehicle for silent security fixes.
  • Ecosystem concentration (medium). Small org, single visible maintainer identity (misaf), MIT-licensed, small codebase. Forkability is genuinely good — but only if we plan for it before adoption, not after.
  • Engineering discipline (positive, differentiating). The skill mandates declare(strict_types=1), final classes, typed signatures, PHPDoc generics, Pest coverage, composer stan (static analysis), a dedicated test suite, and a hard module-boundary rule. For a 1-star package this is well above baseline and materially lowers maintenance risk.
• Key questions. Are we already committed to the Vendra platform (and misaf/vendra-support / vendra-tenant), or is this a new ecosystem bet? What is the monorepo's real release cadence, maintainer count, and bus factor? What is the declared PHP/Laravel/Spatie-Permission support matrix versus our targets, and does it force a Filament v5 upgrade? Which of 1.12.0–1.12.3 addressed security — is there a CVE/GHSA? Are the migrations reversible, and is the conditional tenant_id column handled in our existing environments? Is our tenant story actually vendra-tenant, and who verifies registry completeness? Do we use Pennant (feature scoping flows through the resolver's model class)? Do we need en/de/fa translations, and are JSON columns and their indexes acceptable in our schema? What is the CI status of the monorepo, and does the split repo publish it?

Integration Approach

• Stack fit. Laravel-native, Composer-managed, module-oriented; appropriate for a modular monolith or a platform built on the Vendra module set. The binding constraints are Filament v5 and the Vendra support/tenancy layer — confirm both before design work. Tenancy is derived purely from the bound TenantResolver; there is no tenant_aware toggle, and the module must build and run whether or not a tenant provider is installed. That design is correct but means our environment must match the platform's assumptions precisely.
• Migration path. Treat this as an ecosystem upgrade, not a package swap:
  • Greenfield on Vendra: pin the whole package graph to aligned self.version values after reading the diff; no upgrade exposure.
  • Vendra already in production: upgrade in one coordinated wave across every Vendra package, never one module at a time. Branch, run migrations forward and back on a production-shaped snapshot (both tenant-enabled and tenant-less variants to expose the conditional tenant_id drift), and stage behavior behind a config flag so authorization can revert without a redeploy.
  • Non-Vendra host: do not proceed. The dependency on misaf/vendra-support primitives and the tenant-agnostic-but-platform-shaped model would force a vendor fork, which is a different decision with a different cost profile.
  • In all viable paths, run new checks in shadow mode alongside existing Gate logic and diff decisions rather than assuming equivalence.
• Compatibility. Run composer why/composer outdated across the full graph — the lockstep rule makes any Vendra-version misalignment a silent-failure source. Verify Spatie Permission version constraints, Filament v5 availability on our panel, PHPStan/Pest tooling versions if we intend to contribute upstream, and cache-store behavior: permission caching semantics differ materially between Redis and array/file drivers, and cache-key cardinality scales with tenant count.
• Sequencing. (1) Read the diff and per-release notes for 1.12.0–1.12.3 plus the monorepo CHANGELOG.md/UPGRADING.md — the gate for everything else. (2) Advisory/CVE check on the package and on Spatie Permission. (3) Confirm the platform decision (Vendra in/out). (4) Spike on a branch, including Filament plugin registration and TenantTableRegistry entries. (5) Migration dry-run against production-shaped data, tenant-enabled and tenant-less, with timing. (6) Build an authorization regression suite covering allow and deny cases; run shadow mode. (7) Staged rollout with a kill switch. (8) Adopt and pin the entire graph.

Operational Impact

• Maintenance. A tracked Composer dependency with a named internal owner and a standing quarterly review — but budget for coordinated multi-package upgrades, which is the dominant recurring cost. Watch the Filament major and Spatie Permission majors specifically: those are where a small auth module most often forces emergency work. Contributions go to the monorepo, not the split repo; document that in the runbook so engineers don't open PRs against a read-only mirror.
• Support. Open source, MIT, no vendor SLA. Two escalation surfaces: the Vendra monorepo (GitHub issues) and Spatie upstream. Mitigate by designating an internal SME, confirming fork viability up front (MIT, small codebase — realistic), and recording the vendor-and-patch procedure as a documented fallback before adoption. Also note the transitive-API rule: Vendra-exposed dependencies are part of the public contract, so "just swap the type out" is a breaking change.
• Scaling. Three axes, not two. Data: role/permission tables are join-heavy — verify indexes, and verify that the JSON columns implied by $translatable choices are indexed appropriately if we use translations. Request path: authorize-dense endpoints add latency and invite N+1 if permissions resolve lazily; the skill explicitly warns about N+1 in Filament tables and relation managers, which is a useful signal that the admin UI is a real query surface at tenant scale. Tenancy: cache-key cardinality, table growth, and Pennant scoping all scale with tenant count — load-test with realistic tenant parity, not a single tenant.
• Failure modes. Each needs a detection signal and a runbook entry, not just awareness: stale permission cache after a role revocation (user retains access — a security incident, not a bug); missed TenantTableRegistry registration leaving a table that vendra-tenant:enable cannot retrofit; self.version drift across the package graph producing subtle, hard-to-reproduce authorization behavior; conditional tenant_id schema drift between environments installed at different times; migration locking on large user tables; plugin/provider not registered so the admin UI silently disappears; misconfigured super-admin/bypass logic resolving to an unintended allow; and ecosystem abandonment leaving an unpatchable authz layer.
• Ramp-up. The skill doubles as an onboarding document and is genuinely good, which compresses ramp. A Laravel-fluent engineer is productive on the API in about a day; trustworthy in production on authorization changes in about a week, with learning concentrated in tenant resolution, cache invalidation semantics, and the conditional migration schema — the three places where mistakes are silent. Require a second reviewer on any change touching permission resolution, and front-load the regression suite; it is the artifact that makes every subsequent lockstep upgrade cheap.