---
id: KB-INFRA-002
title: Icone de plugin GLPI 11 requer logo.png PNG na raiz do diretorio
domain: infrastructure
tags:
  - glpi
  - glpi11
  - plugin
  - icon
  - logo
  - marketplace
status: active
severity: low
created_at: 2026-05-02
updated_at: 2026-05-02
applies_to:
  - GLPI 11.x lista de plugins e marketplace
  - qualquer plugin local instalado manualmente
related_records:
  - KB-INFRA-001
  - KB-PLUGIN-006
---

# Contexto
Ao instalar um plugin localmente, o GLPI exibe um avatar gerado com as iniciais do nome
do plugin no lugar de um ícone real. Isso ocorre quando nenhum arquivo de logo está presente.

# Sintoma observável
- Lista de plugins exibe um quadrado colorido com 1-2 letras (ex.: "SI" para "Split ITIL").
- Mesmo com `<logo>` definido no XML do plugin, o ícone remoto pode não carregar.

# Como o GLPI resolve o ícone (ordem de prioridade)

1. **Arquivo local `logo.png`** na raiz do diretório do plugin → servido via `LogoController`
2. URL remota definida em `<logo>` no arquivo `{plugin_key}.xml`
3. **Fallback**: avatar gerado com iniciais das palavras do nome do plugin

Código relevante (`Marketplace/View.php`):
```php
if (Document::isImage(sprintf('%s/logo.png', Plugin::getPhpDir($key)))) {
    $logo_url = sprintf('%s/Plugin/%s/Logo', $CFG_GLPI['root_doc'], $key);
}
```

# Especificação do arquivo

| Atributo     | Valor                                          |
|-------------|------------------------------------------------|
| Nome         | `logo.png` (fixo — hardcoded no LogoController)|
| Localização  | raiz do diretório do plugin                    |
| Formato      | **PNG** obrigatório                            |
| SVG          | Não funciona — `Document::isImage()` rejeita   |
| Tamanho rec. | 128×128 px ou 256×256 px (quadrado)            |

# Rota do LogoController

```
GET /Plugin/{plugin_key}/Logo
```
- Requer autenticação admin (`STRATEGY_ADMIN_ACCESS`)
- Serve `BinaryFileResponse` do arquivo `logo.png`
- Se não existir: retorna 1×1 PNG transparente com HTTP 404

# Verificar se o GLPI aceita o PNG

```bash
docker exec glpi-app php -r "
  require '/var/www/glpi/vendor/autoload.php';
  echo Document::isImage('/var/www/glpi/plugins/myplugin/logo.png') ? 'VALID' : 'INVALID';
"
```

# Gerar PNG placeholder sem dependências externas

Com Python stdlib (sem Pillow ou ImageMagick):
```python
import struct, zlib
# Gerar array de pixels RGBA, encodar com struct.pack e zlib.compress
# Ver: knowledge-base/samples/generate_plugin_logo.py (a criar)
```

# Regra para agentes
Para qualquer plugin, sempre criar `plugins/{key}/logo.png` (PNG, 128×128).
O arquivo tem prioridade sobre o `<logo>` do XML e elimina o fallback de iniciais.
Não usar SVG — o GLPI não reconhece SVG como imagem válida neste contexto.

# Classificação
- Tipo: Configuração de apresentação do plugin.
- Reutilização: aplicável a qualquer plugin GLPI 11 com presença na lista de plugins.