drago-ex / project-permission

v1.4.0 2026-10-18 05:46 UTC

Requires

• php: >=8.3 <9
• drago-ex/application: ^3.0
• drago-ex/component: ^2.0
• drago-ex/database: ^3.0
• drago-ex/datagrid: ^1.0
• drago-ex/form: ^2.0
• drago-ex/migration: ^2.3
• drago-ex/permission: ^2.0
• drago-ex/project-auth: ^2.0
• drago-ex/project-backend: ^2.0
• drago-ex/translator: ^4.0
• drago-ex/utils: ^2.0
• nette/application: ^3.1
• nette/di: ^3.1
• nette/security: ^3.1

Requires (Dev)

• drago-ex/project-tools: ^1.1
• nette/tester: ^2.5
• phpstan/phpstan-nette: ^2

MIT

Published on Packagist.org on 2026-10-18 05:46 UTC

README

English | Čeština

Component for ACL and permission management in a Drago / Nette project.

Requirements

• PHP >= 8.3, < 9
• Nette Framework
• Composer
• Bootstrap
• Naja
• Node.js
• Drago Project core packages

Installation

composer require drago-ex/project-permission

Project files

File copying is handled automatically by drago-ex/project-tools, which must be installed in your project. Without it, copy the files manually according to the copy section in this package's composer.json. To skip this package, set "skip": true under extra.drago-tools.packages.<package-name> in your root composer.json.

After installation, run the package migrations, load the provided service configuration from app/Presentation/Backend/Permission/conf.neon, register the Naja extension from assets/naja/permission-toggle.js and include styles from assets/naja/permission-toggle.scss.

The configuration replaces the one of drago-ex/permission (src/Permission/conf.neon): if you included it for static permissions, remove that include, otherwise two authorizators are registered.

Roles come from the database, so give the first administrator the admin role (the web installer of drago-ex/project-install does it for you):

INSERT INTO users_roles (user_id, role_id) SELECT 1, id FROM roles WHERE name = 'admin';

Example:

import naja from 'naja';
import PermissionToggle from './naja/permission-toggle.js';
import './naja/permission-toggle.scss';

naja.registerExtension(new PermissionToggle());

What it does

• manages roles
• assigns multiple roles to users
• manages resource + privilege records
• allows role permissions to be toggled in the admin UI
• builds a Nette Permission ACL from registered providers and database data

The package ships with an admin section for:

• Users - assign roles to existing users
• Roles - create, edit and delete custom roles
• Permissions - allow or deny access for a selected role

The backend module is installed under App\Presentation\Backend\Permission and uses the Backend:Permission ACL resource. Module permissions are registered by PermissionProvider classes found in the presentation layer. With drago-ex/project-backend-ui, the item "Permissions" appears in the sidebar (Backend/Permission/3.menu.neon).

System roles such as admin, user and guest are handled as protected base roles. Custom roles inherit user, so their users can always sign out and see what a signed-in user sees.

Security

• System roles (admin, user, guest) cannot be renamed or deleted.
• Signals and forms are checked by the ACL ({component}-read / {component}-write on Backend:Permission).
• Whoever may assign roles can assign any role, including admin; give users-write only to administrators.
• Without the permission tables, only the rules of the PermissionProvider classes apply.

Database

The package works with these tables:

• roles
• users_roles
• resources
• authorization

Seed migrations also add default roles and backend permission resources.

Roles of users

The roles assigned here are loaded at sign-in by getRolesByUser() of drago-ex/project-auth; its README shows the code.

Privileges of other packages

Packages with their own administration (e.g. project-blog, project-static-page) ship their privileges in migrations-permission/. Import them by hand, so roles can be given them here:

php vendor/bin/migration db:migrate vendor/drago-ex/project-blog/migrations-permission

project-backend-ui ships the dashboard (Backend:Admin, default-read) the same way: give it to a role that should enter the administration; without it the role goes to the front page after signing in.

The web installer of project-install imports all of them itself.

The add, edit and delete buttons follow the {component}-write privilege by the WriteAccess trait of drago-ex/permission.

Database migration

php vendor/bin/migration db:migrate --packages

The package has migration-priority 20, so it runs after drago-ex/project-auth, whose users table it uses.