# Права (Permission)

← [Назад к разделу «Ядро»](README.md)

`App\Common\Permission` — гранулярные разрешения на действия в админке. Каждый
модуль объявляет свои права; роли получают набор прав; контроллер проверяет право
перед действием.

```php
use App\Common\Permission;
```

---

## Проверка права

### `check($perm): bool`
Есть ли у текущего пользователя разрешение.
```php
if (!Permission::check('view_notes')) { Response::forbidden(); return ''; }

$canManage = Permission::check('manage_notes');   // передать во view для кнопок
```

### `checkAcp($perm)` — проверка в контексте ACP (панели).
### `perm($perm)` — низкоуровневый доступ к разрешению.

Права — это строковые коды (`view_notes`, `manage_notes`, `execute_document_jobs`),
по конвенции: `view_*` — просмотр, `manage_*` — изменение, специальные (`execute_*`).

Исполняемый контент отделяется от обычного редактирования. Например,
`manage_blocks` разрешает работать с визуальными блоками, а
`manage_php_blocks` отдельно открывает PHP-режим. Для операций с документами
`manage_document_jobs` отвечает за код задания, а `execute_document_jobs` — за
его запуск. Эти права не следует выдавать обычной роли контент-менеджера.

---

## Объявление прав модулем

Модуль перечисляет права в своём `Permissions::items()` и в `module.php`
(`'permissions' => [...]`), а также заводит их SQL-миграцией. Пример из модуля:

```php
class Permissions
{
    public static function items()
    {
        return array(
            array('code' => 'view_notes',   'group_code' => 'navigation',
                  'name' => 'Заметки: просмотр', 'sort_order' => 10),
            array('code' => 'manage_notes', 'group_code' => 'content',
                  'name' => 'Заметки: управление', 'sort_order' => 20),
        );
    }
}
```

Динамическая регистрация (реже):
```php
Permission::add('notes', $permissionArray, 'ti ti-notes', 46);
```

---

## Роли

| Метод | Назначение |
| --- | --- |
| `forRole($roleCode)` | Права, назначенные роли. |
| `setForRole($roleCode)` | Назначить права роли. |
| `all()` / `get()` | Все зарегистрированные права / текущий набор. |
| `set($permissions)` / `setArray($permissions)` | Установить набор (строкой/массивом). |
| `syncRegistryToDb()` | Синхронизировать реестр прав в БД. |

---

## Как это связано

```
module.php (permissions) + миграция → права появляются в системе
        │
        ▼
роль (в разделе «Роли и права») получает набор прав
        │
        ▼
Permission::check('view_notes') в контроллере/шаблоне → доступ разрешён/запрещён
```

---

## Практика

- **Каждое** действие контроллера защищайте `Permission::check()` — не полагайтесь
  только на скрытые кнопки в UI.
- В шаблон передавайте `can_manage = Permission::check('manage_x')` и по нему
  показывайте/прячьте элементы управления.
- Разрешение на **чтение** и на **изменение** разносите (`view_*` / `manage_*`) —
  так роль «только смотреть» настраивается без костылей.
- Право проверяет **разрешение**, а `Auth::is($role)` — **роль**; предпочитайте
  проверку права (гибче и переживает изменение ролей).