# Facade `Utils` — `convertToUtf8` compartilhado

`EloquentLancamentoMenuRepository` e `EloquentAtestadoAlunoRepository` duplicavam o mesmo
método privado `convertToUtf8()` (conversão manual de Latin-1 para UTF-8 de linhas cruas
vindas de `DB::select()`, já que essas consultas não passam pelo evento `eloquent.retrieved`
usado por `App\Listeners\ConvertEloquentAttributesToUtf8`). Esse helper foi extraído para uma
classe de suporte com facade própria, para reaproveitar em qualquer Repository futuro que
precise do mesmo tratamento.

## 1. Arquivos criados

| Arquivo | Camada | O que faz |
|---|---|---|
| `app/Support/Utils.php` | Classe de suporte | Implementa `convertToUtf8(object $row): object` — percorre os atributos do objeto e converte cada string de ISO-8859-1 para UTF-8 |
| `app/Facades/Utils.php` | Facade | `App\Facades\Utils`, aponta (`getFacadeAccessor()`) para `App\Support\Utils::class` |
| `docs/00007 - Facade Utils (convertToUtf8).md` | Documentação | Este arquivo |
| `tests/Unit/Support/UtilsTest.php` | Teste (Unit) | Confirma a conversão Latin-1 → UTF-8 e que strings já em UTF-8 não são alteradas |

## 2. Arquivos modificados

| Arquivo | Mudança | Motivo |
|---|---|---|
| `app/Providers/AppServiceProvider.php` | `$this->app->singleton(App\Support\Utils::class)` em `register()` | Classe sem estado/dependências — singleton evita reinstanciar a cada resolução da facade |
| `app/Repositories/EloquentLancamentoMenuRepository.php` | Remove o método privado `convertToUtf8()`; usa `Utils::convertToUtf8($row)` | Elimina a duplicação |
| `app/Repositories/EloquentAtestadoAlunoRepository.php` | Idem | Idem |

## 3. Uso

```php
use App\Facades\Utils;

$linhaConvertida = Utils::convertToUtf8($linhaCrua); // $linhaCrua é um stdClass de DB::select()
```

Qualquer novo Repository que consulte a conexão `tenant`/`central` via `DB::select()` bruto
(fora do Eloquent) deve chamar `Utils::convertToUtf8()` em cada linha antes de devolver a
Collection, do mesmo jeito que `EloquentLancamentoMenuRepository` e
`EloquentAtestadoAlunoRepository` já fazem.

## 4. Testes

```
composer test
# ou
php artisan test tests/Unit/Support/UtilsTest.php
```