Rotas, permissões e telas de administração

Ligando um módulo ao front end, à matriz de grupo e à navegação de administração.

Rotas#

Dois arquivos, carregados a partir do boot():

PHP

$this->loadRoutesFrom(__DIR__.'/../routes/web.php');
$this->loadRoutesFrom(__DIR__.'/../routes/admin.php');

Nomeie toda rota com o seu slug como prefixo (directory.index, admin.directory.settings). É isso que torna Route::has() uma guarda confiável para outros módulos, e o que permite ao painel apontar para a sua tela de configurações.

Rotas de administração ficam atrás do middleware do painel, exatamente como as do core. Nunca crie sua própria autenticação de administração.

Permissões#

Declare-as no manifesto:

JSON

"provides": { "permissions": ["directory.view", "directory.manage"] }

Elas são registradas na matriz de grupo na instalação e aparecem em Members > Member groups ao lado das permissões de todo outro módulo. Verifique-as do jeito de sempre:

PHP

Gate::allows('directory.manage');

Três regras:

Nunca invente um sistema de permissões paralelo. A matriz de grupo é a única resposta a "quem pode fazer isso", e os compradores já a entendem.
Verifique no servidor, sempre. Esconder um botão é apresentação, não segurança.
Delimite onde faz sentido. Uma permissão por área do seu módulo vale mais que um único interruptor liga/desliga.

Navegação de administração#

A navegação do painel é construída a partir de um registry, não é hardcoded. Você contribui através do slot admin.menu no boot():

PHP

Hooks::on('admin.menu', fn (HookContext $ctx) => [
    'label' => __('directory::admin.title'),
    'url'   => route('admin.directory.settings'),
    'order' => 40,
]);

Só adicione entradas que o administrador atual realmente consiga alcançar. Um item de menu que leva a um 403 é ruído.

Slots de interface#

O core declara estes, e um módulo pode declarar os próprios:

admin.menu, admin.dashboard.widgets, profile.tabs, profile.sidebar, settings.pages, search.sources, editor.toolbar, member.actions, head.meta, body.end.

Registrando:

PHP

Hooks::on('profile.tabs', fn (HookContext $ctx) => [
    'label' => __('directory::labels.items'),
    'url'   => route('directory.member', $ctx->get('member')),
    'order' => 20,
]);

Consumindo, numa view Blade:

Blade

@hook('profile.tabs', ['member' => $member])

As contribuições são coletadas, ordenadas por order e renderizadas.

Busca#

Contribua para a busca do site através de search.sources. Sua fonte é responsável por aplicar as próprias regras de visibilidade: um resultado nunca deve aparecer para alguém que não pudesse abrir a página para a qual ele aponta.

Telas#

Telas de administração usam os componentes do painel para que o seu módulo pareça o produto em vez de parecer um plugin. Em particular:

botões-ícone quadrados de tamanho uniforme, com um dropdown de chevron para as ações secundárias, em toda lista;
o modal do produto para confirmação, nunca window.confirm;
selects com o chevron customizado, nunca o nativo puro;
zero violações de axe em toda tela que você adicionar, tanto no claro quanto no escuro.