Magento 2: Como criar um controller no backend e um novo ACL

Nesse tutorial, você vai aprender a criar um novo controller no backend do Magento 2 e um novo ACL.

O backend do Magento é o lugar onde o proprietário da loja consegue administrar tudo o que é relacionado ao seu negócio online. No backend é possível extender todas as funcionalidades – podemos criar novas configurações, níveis de acesso, páginas, menus, componentes, e outros. Ao criar uma nova funcionalidade, é importante sempre seguir as melhores práticas do Magento para manter nossa loja segura de acessos não autorizados.

Nesse tutorial, você vai aprender a:

  1. Criar e instalar um novo módulo
  2. Registrar um novo controller no backend
  3. Criar um novo ACL
  4. Limitar o acesso a um controller usando um ACL
  5. Baixe o código

1. Criando e instalando um novo módulo

Antes de adicionarmos um novo controller ao nosso admin do Magento, primeiro precisamos criar um novo módulo. No Magento 2, um módulo só precisa de 2 arquivos básicos: registration.php e etc/module.xml . Em nosso caso, estes arquivos serão criados no caminho app/code/Examples/Acl , onde “Examples” é o nome do vendor para nosso módulo e “Acl” é o nome do próprio módulo. Você provavelmente não tem nenhum dos dois diretórios na sua instalação do Magento, portanto precisará criá-los.

Este é o conteúdo dos dois arquivos:

Agora que o módulo já foi criado, vamos instalar ele com o comando php bin/magento setup:upgrade e então ativá-lo usando php bin/magento module:enable Examples_Acl.

2. Registrando um novo controller no backend (admin)

Apesar de os controles do backend serem muito parecidos com os do frontend, eles vão extender a classe \Magento\Backend\App\Action , que gerencia todos os procedimentos de seguranças necessários para fazer o admin do Magento ser acessível somente para usuários autenticados. Registrar um novo controller de backend requer a criação de dois arquivos:

etc/adminhtml/routes.xml – Como o nome sugere, esse arquivo inicializa a rota para a área adminhtml. Nós usaremos este arquivo para configurar o nome da rota para o nosso módulo.

Controler/Adminhtml/Index/Index.php – Aqui vamos processar a ação do controller.

O código para ambos os arquivos é:

Antes de testar nosso código, precisamos remover a Secret Key das nossas URLs, do contrário não seremos capazes de acessar diretamente o nosso controller via URL. O Magento adiciona automaticamente uma secret key (chave de segurança) ao final de cada URL do backend para previnir contra ataques CSRF. Enquanto esta opção estiver ativada, nós não poderemos acessar um controller apenas digitando a URL dele na barra de endereços do navegador.

Faça login no admin do seu Magento e vá para Stores > Configuration > Advanced > Admin > Security . Mude a opção Add security keys to URLs para  no e salve as alterações.

Agora execute o comando php bin/magento cache:clean para limar o cache e nosso novo controller já deve estar acessível. É assim que o Magento cria as URLs para os controllers no backend:

<store_path>/<backend_path>/<route_name>/<controller_name>/<action_name>

Nota: se o nome da sua ação for index index, você não é obrigado a adicionar ela na URL.

Nossa rota foi definida como exampleacl no arquivo routes.xml. O nome do nosso controller é  Index , que também é o nome da ação, então a URL do controller deverá ser a seguinte:

http://your-magento-site.com/admin-folder/exampleacl/index/index

Ao acesar essa URL você deverá ver uma página em branco com a seguinte mensagem:

Também é possível modificar a função execute() do controller para exibir a interface do backend do Magento com uma página em branco:

Sua página vai ser exibida desta forma:

3. Adicionando um novo ACL

Criando um novo ACL (Access Control List), nós podemos limitar o acesso ao nosso novo controller, permitindo que somente certos grupos de usuários (roles) possam ter acesso aos seus conteúdos. Por padrão, o Magento 2 tem somente um grupo de usuário — Administradores. Todos os usuários que fazem parte deste grupo possuem acesso a todas as funcionalidades, portanto, antes de criar nosso novo ACL, vamos criar um novo grupo e adicionar um novo usuário (nós  usaremos esse usuário mais tarde para testar se nosso novo ACL está funcionando).

Navegue até  System > Permissions > User Roles e clique em Add New Role. O novo grupo será nomeado como Example. Agora, dentro da aba Role Resources, ative acesso a todos os resources:

Salve as alterações.

Vá até  System > Permissions > All Users e adicione um novo usuário. Na aba User Role , selecione o novo grupo Example que acabamos de criar na etapa anterior.

Agora que acabamos de criar o novo usuário, vamos adicionar o arquivo acl.xml ao nosso módulo:

Note que neste arquivo temos um monte de resources aninhados. O resource Magento_Backend::admin deve sempre ser o nó principal por padrão, enquanto Magento_Backend::dashboard já existe (ele foi inicialmente definido em vendor/magento/module-backend/etc/acl.xml), então nós criamos apenas dois novos resources: Examples_Acl::exampleparent e Examples_Acl::examplechild.

Após limpar o cache usando php bin/magento cache:clean, nosso novo ACL vai aparecer em System > Permissions > User Roles > Example > Role Resources > Dashboard :

4. Limitando o acesso ao controller usando o ACL

Nesta última etapa do tutorial, iremos adicionar a função abaixo ao arquivo app/code/Examples/Controllers/Adminhtml/Index/Index.php :

A função  _isAllowed() deve sempre retornar um valor booleano indicando se este controller pode ou não ser acessado.
$this->_authorization é uma instância de \Magento\Framework\AuthorizationInterface e é usado para verificar se um determinado ACL está ativado/desativado para o grupo ao qual pertence o usuário que está logado atualmente.

Agora que temos tudo pronto, faça login no admin do Magento usando o usuário que criamos anteriormente. Se você tentar acessar o controller Index usando a URL http://your-magento-site.com/admin-folder/exampleacl/index/index , você verá a página sem nenhum problema. Isso acontece porque os ACLs são aninhados, portanto, se um ACL pai está ativado, todos os demais que estão abaixo dele também estarão ativados por padrão. Quando nós criamos nosso novo ACL, ele estava abaixo de  Dashboard , portanto se nós queremos desativar o acesso ao nosso controller, nós precisamos desativar o ACL Dashboard primeiro.

Nota: da mesma forma, se um ACL filho está ativado, todos os seus pais também estarão ativados.

Se você desativar o ACL  Dashboard para o grupo atual e tentar acessar o controller index novamente, a seguinte mensagem de erro será exibida:

5. Baixe o código

Você pode baixar todo o código deste tutorial diretamente do repositório na minha conta do GitHub: