---
id: KB-PLUGIN-006
title: Procedimento completo de renomeacao de plugin GLPI
domain: plugin-dev
tags:
  - glpi
  - glpi11
  - plugin
  - rename
  - refactor
  - namespace
  - database
status: active
severity: medium
created_at: 2026-05-02
updated_at: 2026-05-02
applies_to:
  - GLPI 11.x
  - qualquer plugin sendo renomeado ou criado como fork
related_records:
  - KB-PLUGIN-001
  - KB-INFRA-001
---

# Contexto
Renomear um plugin GLPI envolve muito mais do que trocar o nome do diretório.
O plugin key permeia namespace PHP, hooks, tabelas de banco, URLs de ajax, classes JS/CSS
e o registro na tabela `glpi_plugins`. Uma renomeação incompleta causa falhas silenciosas.

# Mapa completo de substituições (do mais específico para o mais geral)

Execute na seguinte ordem para evitar substituições duplas:

```
GlpiPlugin\OldName   → GlpiPlugin\NewName   (namespace)
PluginOldName        → PluginNewName         (prefixo de classe legado)
PLUGIN_OLDNAME       → PLUGIN_NEWNAME        (constantes)
plugin_oldname       → plugin_newname        (funções e hook keys)
glpi_plugin_oldname  → glpi_plugin_newname   (tabelas de banco)
QuestionTypeOldName  → QuestionTypeNewName   (classes src/)
data-oldname-        → data-newname-         (atributos JS)
oldname-group        → newname-group         (classes CSS)
oldname_container    → newname_container     (classes CSS)
@oldname/            → @newname/             (namespace Twig)
"oldname"            → "newname"             (string literal entre aspas)
OldName              → NewName              (PascalCase restante)
oldname              → newname              (lowercase restante)
"Old Display Name"   → "New Display Name"   (nome de exibição)
"Old Author"         → "New Author"          (autor)
```

Comando com perl (mais confiável que sed no macOS):
```bash
find ./plugins/oldname -type f ! -path "*/vendor/*" ! -name "*.png" \
  | xargs perl -i -pe 's/GlpiPlugin\\\\OldName/GlpiPlugin\\\\NewName/g; ...'
```

# Arquivos a renomear (após substituir conteúdo)

```bash
mv ajax/oldname.php          ajax/newname.php
mv ajax/oldname_data.php     ajax/newname_data.php
mv public/css/oldname.css    public/css/newname.css
mv public/js/oldname-form.js public/js/newname-form.js
mv public/js/oldname.js.php  public/js/newname.js.php
mv oldname.xml               newname.xml
mv src/QuestionTypeOldName.php src/QuestionTypeNewName.php
# ... demais arquivos src/
mv plugins/oldname           plugins/newname   # por último
```

# Pós-renomeação: atualizar o GLPI

```bash
# Remover registro órfão do nome antigo (diretório não existe mais)
mysql -u glpi -p glpi -e "DELETE FROM glpi_plugins WHERE directory='oldname';"

# Instalar e ativar com o novo key
docker exec glpi-app php /var/www/glpi/bin/console plugin:install newname
docker exec glpi-app php /var/www/glpi/bin/console plugin:activate newname
docker exec glpi-app php /var/www/glpi/bin/console plugin:list
```

# Verificação final
```bash
# Zero referências ao nome antigo (exceto menções históricas intencionais)
grep -rn "oldname\|OldName\|OLDNAME" ./plugins/newname \
  --exclude-dir=vendor --exclude="*.png" | grep -v "vendor"

# Sintaxe PHP OK
find ./plugins/newname -name "*.php" ! -path "*/vendor/*" \
  | xargs php -l | grep -v "No syntax errors"
```

# Regra para agentes
Ao renomear um plugin:
1. Substituir conteúdo (ordem do específico para o geral)
2. Renomear arquivos individuais
3. Renomear o diretório
4. Limpar registro órfão no banco
5. Reinstalar via console

Nunca renomear o diretório antes de substituir o conteúdo — o container pode perder a referência.

# Classificação
- Tipo: Procedimento operacional de refatoração.
- Reutilização: aplicável a qualquer renomeação ou fork de plugin GLPI.