knowledge-base/records/plugin-dev/KB-PLUGIN-001-install-hooks-required.md

id	title	domain	tags	status	severity	created_at	updated_at	applies_to	related_records
KB-PLUGIN-001	Instalacao de plugin GLPI requer callbacks install/uninstall	plugin-dev	glpi plugin install setup.php hooks	active	high	2026-05-01	2026-05-01	plugins locais GLPI 11.x estrutura setup.php	KB-INFRA-001

Contexto

O plugin GLPI Matrix aparecia na lista de plugins, mas falhava ao instalar pela interface.

Sintoma observavel

• Notificacao generica de falha na instalacao.
• Plugin permanecia em status "Nao instalado".

Causa raiz

Ausencia dos callbacks de ciclo de vida no setup.php:

• plugin_<chave>_install(): bool
• plugin_<chave>_uninstall(): bool

Sem esses callbacks, o GLPI nao consegue concluir o fluxo de instalacao/desinstalacao.

Correcao aplicada

Adicionar no setup.php:

• plugin_glpimatrix_install(): bool { return true; }
• plugin_glpimatrix_uninstall(): bool { return true; }

Validacao padrao

Executar:

1. php /var/www/glpi/bin/console plugin:install glpimatrix -n
2. php /var/www/glpi/bin/console plugin:activate glpimatrix -n
3. php /var/www/glpi/bin/console plugin:list

Esperado:

• instalacao concluida;
• ativacao concluida;
• status final "Habilitado".

Regra para agentes

Ao criar plugin base, sempre incluir no setup.php:

1. plugin_<chave>_check_prerequisites
2. plugin_<chave>_check_config
3. plugin_<chave>_install
4. plugin_<chave>_uninstall