knowledge-base/records/plugin-dev/KB-PLUGIN-023-mcprotocol-inputvalidation-extracted.md

id	title	domain	tags	status	severity	created_at	updated_at	applies_to	related_records
KB-PLUGIN-023	mcprotocol — InputValidation extraída como classe utilitária compartilhada	plugin-dev	mcp tools validation refactor patterns	active	medium	2026-05-26	2026-05-26	glpi-11 mcprotocol-plugin	KB-PLUGIN-022 KB-PLUGIN-019

mcprotocol — InputValidation extraída como classe utilitária compartilhada

Contexto

KB-PLUGIN-022 documentou os padrões resolveReference, normalizeDate, validação agregada e response com applied como métodos privados em ProjectTools. Esse KB previu que na introdução do segundo handler os helpers seriam extraídos para uma classe utilitária. Esse momento chegou ao implementar glpi_projecttask_create.

Decisão

Extraído src/InputValidation.php (namespace GlpiPlugin\Mcprotocol) com métodos estáticos públicos reutilizáveis em qualquer handler de tool:

Método	Responsabilidade
resolveReference($table, $value, $field, &$errors, $nameCol='name')	Aceita int ou string e devolve ID validado. Suporta coluna de busca customizada (ex: name em glpi_users).
normalizeDate($value, $field, &$errors)	Aceita YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS, normaliza pro formato GLPI.
validateDateRange($start, $end, $startField, $endField, &$errors)	Garante end >= start quando ambos informados.
validateIntRange($value, $field, $min, $max, &$errors)	Valida inteiro em intervalo (ex: percent_done 0-100).

Mudanças realizadas

• Novo arquivo: src/InputValidation.php
• Refatorado: src/ProjectTools.php — removeu helpers privados, agora chama InputValidation::*. Também ganhou método buildInputFromArgs($args, $isUpdate) que centraliza a montagem do input para create/update (DRY).
• Estendido: glpi_project_update agora aceita os mesmos campos do create (datas, estado, tipo) — antes só aceitava name/content/percent_done.
• Novo arquivo: src/ProjectTaskTools.php — usa InputValidation desde o início, com 2 tools: glpi_projecttask_create e glpi_projecttask_get.
• Atualizado: src/ToolRegistry.php — registra ProjectTaskTools::getTools() no merge.

Convenções de uso

1. Acumular erros — qualquer handler que valida múltiplos campos deve usar a assinatura &$errors e lançar UMA exception ao final. Nunca múltiplas.

2. Coluna de busca por nome — resolveReference aceita $nameCol. Para tabelas onde o campo descritivo não se chama name, passar explicitamente:

   InputValidation::resolveReference('glpi_users', $args['users_id'], 'users_id', $errors, 'name');
   

3. Validação prévia ao ORM — todos os helpers rodam ANTES de $obj->add() ou $obj->update(). Se houver erro, exception é lançada e o ORM nunca é chamado. Evita erros de SQL/ORM crípticos.

4. Response com applied — handlers devem sempre retornar o input efetivamente aplicado:

   return ['status'=>'success', 'id'=>$newId, 'message'=>'...', 'applied'=>$input];
   

Tabelas comuns para resolveReference

Tabela	Coluna de nome	Uso típico
glpi_projectstates	name	Estado de projeto/tarefa
glpi_projecttypes	name	Tipo de projeto
glpi_projecttasktypes	name	Tipo de tarefa
glpi_users	name (login)	Responsável
glpi_groups	name	Grupo
glpi_entities	name	Entidade
glpi_itilcategories	name	Categoria de chamado
glpi_locations	name	Localização

Próximos handlers candidatos a usar InputValidation

• glpi_ticket_create — users_id_recipient, users_id_lastupdater, itilcategories_id, datas
• glpi_ticket_update — idem + estados (1=New, 2=Processing, etc. já são enums numéricos GLPI)
• Futuras tools de Computer/Asset (glpi_computer_create, etc.)

Validação end-to-end

Padrão validado em produção criando o projeto VALGROUP (28 tarefas em hierarquia) através das tools. Erros de validação retornados claramente, datas normalizadas, estados resolvidos por nome ("New" → 1, "Processing" → 2). Aplicado conforme esperado.