Acl Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for object-level permissions. The bundle gives you a working ACL data model and REST surface (/permissions/aces, /permissions/ace) instead of a bespoke permissions table. The buy case is legitimate only if you're on Symfony (or willing to run it as a service) — see the stack caveat below.
• The "default policy + exception" permission model. Null objectId applies an ACE to every object of a type; null userId applies to everyone. That maps cleanly to product language users already understand: "all editors can view all publications, except this draft, which only the author can edit."
• Per-object sharing and delegation. Grants scoped to a single publication/asset for a user or group is the feature set behind "share this document," "give the agency access to their listing," "invite a reviewer to this draft." Each of these is normally a multi-sprint feature; here it's configuration plus a controller.
• Admin tooling as a roadmap item, not a blocker. Because permissions are managed over HTTP, a permission-management UI can be built later against the API without touching the backend. That lets you sequence: ship the enforcement, ship the UI when support tickets justify it.
• Multi-tenant / team isolation. Group principals (userType: group) let you model org-level access without a second system.
• What it does not decide for you: the permission vocabulary. mask: 7 is an integer with no shipped semantics — product must define what each bit means (view/edit/delete/share), document it, and enforce it consistently. That's a real design task, not a config line.
• Roadmap phasing this supports: (1) protect 1–2 high-value entities; (2) expose read-only ACE listing to an internal admin screen; (3) add write UI; (4) extend to teams/tenants.

When to Consider This Package

Consider it when:

• You need per-object permissions (record #42), not just role checks — this is the gap Laravel's Gate/Policy doesn't cover out of the box.
• Your stack is Symfony 7/8 with PHP 8.4+ (1.5.0 added Symfony 8), you have Redis for the accessToken.cache pool, and you're comfortable with a YAML-configured, code-deployed list of ACL-able entities.
• You want an API-first permission store you can drive from an admin panel, CLI, or internal service.
• You're comfortable owning the permission semantics (bitmask definitions) and the UI yourself.

Look elsewhere when:

• You're on Laravel. This is fundamentally a Symfony bundle — Doctrine entities, Symfony DI UserRepositoryInterface aliasing, Symfony cache pools. In Laravel you would be either (a) standing up a small Symfony service purely for ACL, or (b) porting the logic into Eloquent, at which point you've built it yourself. For a Laravel-native product, spatie/laravel-permission plus policies is the lower-risk path; note that spatie is role/permission-centric, not per-object, so per-object still needs custom work.
• You need ABAC — conditions on attributes (department AND clearance), policy languages, or inheritance hierarchies. This is ACE-based, not a policy engine.
• You need vendor assurance. 4 stars, 0 dependents, effectively one contributor, releases driven by framework bumps. That's fine for internal reuse; it is not a dependency to hang a compliance story on without a maintenance owner on your side.
• You need a permission UI out of the box — there isn't one, and adding entities to the ACL registry is a deploy, not a runtime action.
• Your needs are simple — one role field and a handful of if checks. Don't adopt an ACL system to solve a three-line problem.

How to Pitch It (Stakeholders)

Executives: "Object-level permissions — 'this editor can change this draft, not all drafts' — are normally a custom build. This package provides the data model and an API for it. Two honest caveats: it's a Symfony component, so the cost depends on whether we're a Symfony shop; and it's a small, thinly-adopted open-source project, so we'd be owning the risk. If we're Symfony, this is a weeks-not-months saving on the backend. If we're Laravel, the realistic version of this proposal is borrow the design, build the small piece — and I'd rather tell you that now than after a sprint of integration work."

Engineering: "Reusable ACL model: principals (user or group), targets (registered entities), ACEs with a numeric mask, plus global fallbacks via null IDs. Enforcement is a lookup; Redis caches tokens. Integration work if we're not on Symfony: replace the Doctrine user repository with our own, replace the cache pool, and define what the mask bits mean — that last one is ours to design regardless. Also note the entity registry is static YAML, so adding a permission-able model is a deploy. Recommendation: adopt as-is only on Symfony; otherwise treat the README as a spec and port ~200 lines into our own service, wired to Laravel policies. Either way, write the mask contract and test it."

Product managers: "This turns 'who can touch which record' into a managed, queryable thing instead of scattered checks in controllers. What you get: per-record sharing, group access, and an API that a future admin screen can use without backend changes. What you don't get: an admin screen, a permission vocabulary (we define the bits), or dynamic entity registration. Next steps — pick one entity, define the mask meanings in writing, ship enforcement behind a flag, and only build the management UI once support requests prove the need."