Permissions Contract Sample

Permission declarations bridge addon-owned operations and the shared permissions system.

Preferred File

Use:

addons/example_notes/src/permissions_contract.php

The manifest and install contract should point here. They should not copy the full permission catalog.

Copyable Contract

<?php
declare(strict_types=1);

if (!defined('HC_ACCESS')) {
    exit;
}

function amv_example_notes_permissions_contract(): array
{
    return [
        'addon_key' => 'example_notes',
        'permissions' => [
            'example_notes.view' => [
                'label' => 'View Example Notes',
                'description' => 'View notes in the Example Notes addon.',
            ],
            'example_notes.manage' => [
                'label' => 'Manage Example Notes',
                'description' => 'Create, edit, publish, and archive notes.',
            ],
            'example_notes.note.submit' => [
                'label' => 'Submit Example Notes',
                'description' => 'Submit frontend notes when allowed by site policy.',
            ],
        ],
        'recommended_roles' => [
            'administrator' => ['example_notes.view', 'example_notes.manage', 'example_notes.note.submit'],
            'editor' => ['example_notes.view', 'example_notes.manage'],
            'member' => ['example_notes.note.submit'],
        ],
    ];
}

return amv_example_notes_permissions_contract();

Manifest Pointer

'contract_providers' => [
    'permissions_contract' => [
        'path' => 'addons/example_notes/src/permissions_contract.php',
        'function' => 'amv_example_notes_permissions_contract',
        'trusted_by' => 'installer_aem',
    ],
],

Install Contract Pointer

'permissions_contract_present' => true,
'permissions_contract' => [
    'provider' => 'addons/example_notes/src/permissions_contract.php',
    'registration_function' => 'amv_example_notes_permissions_contract',
],

Common Breakage

• Route checks use a key that was never registered.
• Manifest, install contract, and external permission file each carry their own copied permission list.
• Permission keys use slugs in one place and underscores in another.
• Generic permission names collide with another addon.
• A rename is shipped without a role/user assignment migration.

See Addon Development/Permissions Contract Basics and Reference Samples/Sample Manifest.