Entenda a hierarquia de papéis e o sistema de permissões no Mapas Culturais.

O Mapas Culturais usa um modelo de permissões em camadas. Cada usuário tem um ou mais papéis, e cada papel concede um conjunto cumulativo de capacidades. As checagens em nível de entidade são avaliadas em runtime, permitindo que módulos personalizados estendam as regras padrão sem alterar o código do núcleo.

Hierarquia de perfis de usuário

Cada nível herda todas as capacidades dos níveis abaixo.

$user->is('guest'); // true for unauthenticated users

$user->is('admin');

$user->is('superAdmin');

$user->is('saasAdmin');
$user->is('superSaasAdmin');

API de checagem de permissões

$entity->canUser($action)

Retorna true se o usuário atual, ou o usuário passado como segundo argumento, puder executar $action sobre a entidade. Use isso para renderização condicional ou lógica de desvio.

if ($agent->canUser('edit')) {
    // show edit button
}

if ($event->canUser('publish')) {
    // allow publishing
}

$entity->checkPermission($action)

Funciona como canUser, mas lança MapasCulturais\Exceptions\PermissionDenied em vez de retornar false. Use no início de operações de escrita para bloquear acesso não autorizado.

$entity->checkPermission('edit');
// execution continues only if allowed

$entity->checkPermission('view');

$user->is($role)

Verifica se o usuário possui um determinado papel. Funciona tanto para papéis nomeados quanto para o papel virtual guest.

$user->is('admin');      // has admin role
$user->is('superAdmin'); // has superAdmin role
$user->is('guest');      // not logged in

$user->can($action, $entity)

Convenience wrapper around $entity->canUser($action, $user). Useful when you have a user instance and want to check permission against an entity.

$canEdit = $user->can('edit', $space);

$app->getAuth()->getAuthenticatedUser()

Retorna a entidade User autenticada ou uma instância de GuestUser se ninguém estiver logado.

$user = $app->getAuth()->getAuthenticatedUser();

$controller->requireAuthentication()

Defined in the abstract Controller class. Redirects anonymous users to the login page and resumes the original request after successful authentication. Call it at the top of any controller action that requires a session.

public function GET_myAction() {
    $this->requireAuthentication();
    // rest of action — only reached by logged-in users
}

Generic permission rules

A classe base Entity aplica estas regras antes de qualquer lógica específica de entidade:

Custom permission methods

Entity classes can override specific permission checks by implementing protected methods named canUser{Action}. These are automatically discovered and invoked by the base canUser() dispatcher.

// Example from the User entity — only superAdmin can remove another admin's role
protected function canUserRemoveRoleAdmin(User $user): bool
{
    return $user->is('superAdmin') && $user->id !== $this->id;
}

// Example — restrict who can change entity status
protected function canUserModifyStatus(User $user): bool
{
    return $user->is('admin') || $this->getOwnerUser()->equals($user);
}

Temporarily disabling access control

Some internal operations — such as system-initiated status changes or data migrations — need to bypass the normal permission checks. Use disableAccessControl() / enableAccessControl() in a tightly scoped block.

$app->disableAccessControl();
try {
    $registration->status = Registration::STATUS_APPROVED;
    $registration->save(true);
} finally {
    $app->enableAccessControl();
}

You can also inspect the current state:

if ($app->isAccessControlEnabled()) {
    // normal flow
}

Role management

Papéis são atribuídos e revogados pelos métodos addRole e removeRole da entidade User. O nome do papel precisa estar registrado na aplicação antes de ser usado.

// Grant a role
$user->addRole('admin');

// Revoke a role
$user->removeRole('admin');

// Grant a role scoped to a specific subsite
$user->addRole('admin', $subsite_id);

Roles are stored in the role table and can also be assigned through the agent detail page in the administration panel via a role selector dropdown.

Procuration (delegating permissions)

A procuration allows one user (the grantor) to delegate a specific action to another user (the attorney), optionally with an expiry date. This is how Mapas Culturais implements agent-level delegation without changing roles.

// Grant user $attorney the right to perform 'edit' on behalf of $user
$attorney->makeAttorney('edit', validUntil: new \DateTime('+30 days'), user: $user);

// Check if the current user is an attorney for a given action
$isAttorney = $user->isAttorney('edit');

Procurations are stored in the Procuration entity. Expired procurations are automatically removed when encountered during an isAttorney check.