# Guia de Integração: Otimização de Imagens no CMS (V2)

Este guia orienta como implementar o fluxo de otimização de imagens em novos módulos e seeders.

## 1. Fluxo Recomendado

### Para uploads administrativos (Controllers)

Use o `GalleryService` que já encapsula o pipeline completo:

```php
use V2\Services\Gallery\Services\GalleryService;
use V2\Services\Gallery\DTOs\GalleryConfig;

public function store(Request $request, GalleryService $gallery)
{
    $config = new GalleryConfig('meu-modulo', ['image/*'], 10240, false);

    if ($request->hasFile('cover')) {
        $result = $gallery->upload(
            $request->file('cover'),
            $config,
            'Texto alternativo',
            'Descrição opcional',
            false,          // is_shared
            'nome-fixo'     // customFilename (opcional, sem extensão)
        );

        $model->update([
            'file_path' => $result['file_path'],
            'variants'  => $result['variants'], // string JSON
        ]);
    }
}
```

### Para seeders (deploy/população)

Use `seedFromPath()` que cria um `UploadedFile` em modo test:

```php
$result = $gallery->seedFromPath(
    public_path('assets/modulo/imagem.png'),
    $config,
    'nome-arquivo',
    'Texto alternativo'
);

// Extraia SEMPRE as variantes para usar no picture component
$variants = isset($result['variants'])
    ? (is_string($result['variants']) ? json_decode($result['variants'], true) : $result['variants'])
    : [];

// Verifique se foram geradas (warning se vazio)
if (empty($variants)) {
    Log::warning("Nenhuma variante WebP gerada para {$path}");
}
```

## 2. Tratamento de SVGs

SVGs (`image/svg+xml`) são automaticamente detectados e **pulados** da otimização WebP no `MediaInputer`. O arquivo original é armazenado e servido como SVG.

## 3. Imagens < 360px

O `ImageOptimizer::generateVariants()` agora gera uma variante WebP na largura original mesmo para imagens menores que 360px (todas as larguras padrão seriam puladas). A chave retornada é `'original'`.

```php
// Para uma imagem de 200px de largura:
[
    'original' => 'gallery/module/variants/nome.webp'
]
```

## 4. Propagação de Erros

Diferente da V1, o `ImageOptimizer` agora **lança exceções** em vez de retornar `[]` silenciosamente. Isso significa que seu código DEVE capturar `\Exception` ao chamar o pipeline:

```php
try {
    $result = $gallery->seedFromPath($path, $config, $filename, $alt);
} catch (\Exception $e) {
    Log::error("Falha ao processar imagem: " . $e->getMessage());
    // Trate o fallback adequadamente
}
```

## 5. Visualização no Formulário

```blade
@if(isset($item) && $item->file_path)
    @include('v2-service-media::components.picture', [
        'originalPath' => $item->file_path,
        'variants'     => is_string($item->variants) ? json_decode($item->variants, true) : ($item->variants ?? []),
        'alt'          => $item->alt_text ?? 'Prévia',
        'class'        => 'img-thumbnail shadow-sm',
        'style'        => 'max-height: 200px;'
    ])
@endif
```

## 6. Acessibilidade

- Sempre forneça `alt` descritivo.
- O componente já inclui `role="img"` e `loading="lazy"` (quando variantes existem).
- Para imagens decorativas, passe `alt=""` para leitores de tela ignorarem.

## 7. Cache e OpCache

Após modificar seeders ou o pipeline de imagens:

```bash
php artisan view:clear
php artisan cache:clear
php artisan config:clear
php -r 'opcache_reset();'
```

---

*Atualizado em Julho de 2026.*