Download the PHP package tihloh/prefab-permissions without Composer

Prefab Permissions

Prefab Permissions provides framework-independent authorization for PHP applications with user overrides, group inheritance and configurable permission defaults.

Define what an action means once, then resolve whether a user or subject may perform it.

Prefab Permissions is standalone. It does not require Prefab Database, Users, Auth, Logs, Routes, Laravel, or another framework package.

Requirements

• PHP 8.1 or newer
• Composer when installed as a package

Installation

1. Core model

Prefab resolves an effective permission through three levels:

A user-level override has the highest priority. If there is no override, group settings are considered. If neither supplies a decision, the permission definition's default is used.

This naturally supports tri-state behavior:

INHERIT means there is no override at that level; resolution continues downward.

2. Permission definitions

Definitions describe the permissions known by the application.

They may come from an inline PHP array, PHP configuration file, or JSON file.

JSON is also supported:

A definition may contain a stable ID plus human-friendly information such as a name, description and default value.

Conceptually:

Stable machine IDs should be used in application code; friendly names are for humans and interfaces.

Definitions may also include an optional group value for presentation:

Grouping is metadata only. It does not change authorization, inheritance, or scope resolution. Interfaces can retrieve grouped definitions with:

3. Checking permission

The common authorization question is:

This keeps authorization logic out of controllers and business code.

Instead of repeatedly implementing:

application code asks one stable question:

4. User overrides

Explicitly allow an action for one user:

Explicitly deny it:

Restore inheritance:

Clearing is different from setting false: false is an explicit deny, while clearing removes the override and lets lower levels decide.

5. Group inheritance

A user can inherit permissions from one or more groups according to the subject/group information supplied to the permission system.

Conceptually:

A user-specific override still takes precedence over inherited group behavior.

This makes it possible to manage most access at group level while handling exceptions for individual users.

6. Subject integration

Projects keep ownership of their user and group models.

For object-based resolution, a subject implements PermissionSubjectInterface:

Then:

Prefab does not require your model to extend a particular base class.

7. Custom storage

A custom PermissionStoreInterface can be supplied directly:

This makes the permission engine independent of one database implementation.

Conceptually:

8. Built-in database storage

The built-in database store accepts plain PDO or Prefab's DatabaseInterface:

The historical PdoPermissionStore name remains for compatibility. Internally it consumes DatabaseInterface; plain PDO is adapted automatically.

9. Automatic database configuration

A common centralized configuration is:

Or select a named Prefab Database connection:

10. Configuration resolution

Permissions follows the standard Prefab hierarchy:

This allows explicit standalone usage and low-configuration modular usage to coexist.

11. Database abstraction

Built-in database storage uses:

Database-specific DDL/upsert differences are isolated inside the built-in store for MySQL/MariaDB, PostgreSQL, SQLite and SQL Server.

The shared database interface deliberately remains small rather than turning Permissions into a database framework.

12. Prefab Users integration

Users can supply the identity/group information needed for authorization while Permissions remains responsible for the decision.

The modules remain independently installable.

13. Prefab Auth integration

Auth and Permissions answer different questions:

Typical flow:

Authentication success does not automatically imply authorization.

14. Prefab Routes integration

Authorization can be attached to routes rather than repeated inside every controller.

Conceptually:

An integration layer or middleware can then use Prefab Permissions to enforce the route's requirement.

This keeps routing and authorization separate while allowing them to cooperate.

15. Prefab Logs integration

When a compatible logger is available, permission changes can produce structured audit records automatically.

A technical permission operation such as:

can be rendered in a human-friendly form such as:

Friendly permission definition names improve audit readability without changing the stable permission ID used by code.

16. Laravel and framework compatibility

Laravel's own user model, Auth system and Gate system do not need to be replaced.

An adapter/bridge can expose the contracts Prefab needs while Laravel remains the host framework.

The same principle applies to other frameworks:

Prefab consumes capabilities rather than demanding control of the application.

17. Diagnostics

Use:

Diagnostics describe how important resources were resolved, including definitions, storage, table and database resources.

This is particularly useful when module-specific configuration, common configuration and automatic capability discovery coexist.

18. Practical small application

No other Prefab module is required.

19. Practical modular application

The resulting responsibilities remain clear:

20. Common authorization pattern

A controller or service can remain simple:

With routing middleware, the same check can be moved outside the controller entirely.

21. API quick reference

Common operations:

Important concepts:

22. Design philosophy

Prefab Permissions keeps authorization policy independent from user storage, authentication, routing and presentation.

The important rule remains:

Authentication identifies the user. Permissions decides what that user may do.

Prefab makes those responsibilities cooperate without forcing them into one monolithic framework.

23. Scoped permissions

Permission definitions can declare where the same permission may be granted:

The permission ID remains the same. Scope only limits where the grant is effective.

Global grants continue to use the normal API:

An organization-scoped grant uses:

The built-in database store keeps scoped grants separately from global grants in:

A scoped row identifies:

Resolution for a scoped check is:

This means a global grant applies in every organization, while an organization grant applies only when the application checks that organization's scope.

Prefab Permissions does not decide whether a document, user, request, or other resource belongs to an organization. The host application supplies the resource's scope:

Important APIs:

Custom permission stores can opt into scoped authorization by implementing ScopedPermissionStoreInterface. Existing stores implementing only PermissionStoreInterface remain compatible for global permissions.