Armazenamento de ficheiros

O sistema de armazenamento de ficheiros do Doggy é construído sobre o League Flysystem, com suporte para armazenamento local e armazenamento compatível com S3, fornecendo capacidades de upload de ficheiros, otimização de imagens e geração de URLs.

Visão geral

O sistema de armazenamento localiza-se em src/Service/Storage/:

src/Service/Storage/
├── StorageManager.php          # Gestor de armazenamento (seleção de adaptadores)
├── FileUploadService.php       # Serviço de upload de ficheiros
├── FileUrlGenerator.php        # Geração/cache de URLs
├── ImageOptimizerService.php   # Otimização de imagens (biblioteca Imagine)
└── Adapter/
    ├── StorageAdapterInterface.php
    ├── LocalStorageAdapter.php
    └── S3StorageAdapter.php

As entidades relacionadas ficam em src/Entity/Storage/:

Entidade	Descrição
File.php	Registo de ficheiro
StorageConfig.php	Configuração de armazenamento (tipo de adaptador, parâmetros, domínio CDN)
UploadSession.php	Sessão de upload

Backends de armazenamento

Backend	Adaptador	Cenário de utilização
Local	LocalStorageAdapter	Ambiente de desenvolvimento, implementações de pequena escala
AWS S3	S3StorageAdapter	Implementações em cloud (suporta domínio CDN)

Armazenamento local

// Armazenamento local predefinido: public/uploads/
$adapter = new LocalStorageAdapter(
    rootPath: '/var/www/public/uploads',
    publicUrl: '/uploads'
);

Armazenamento S3

// Armazenamento compatível com S3 (suporta AWS, MinIO, Alibaba Cloud OSS, etc.)
$adapter = new S3StorageAdapter([
    'access_key' => '...',
    'secret_key' => '...',
    'region' => 'us-east-1',
    'bucket' => 'doggy-files',
    'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com',
    'cdn_domain' => 'https://cdn.example.com',
]);

Upload de ficheiros

FileUploadService fornece o fluxo de upload completo:

$file = $fileUploadService->upload($uploadedFile, [
    'disk' => 'default',
    'optimize' => true,
    'max_size' => 52428800,  // 50MB
]);

Fluxo de upload:

1. Dispara o evento FileUploadingEvent (permite interceptar e modificar opções)
2. Verificação de segurança do ficheiro (tipo, tamanho, extensão, MIME)
3. Deduplicação por hash SHA-256
4. Geração do caminho de armazenamento com estratégia por data (Y/m/uuid.ext ou uuid.ext)
5. Upload para o adaptador
6. Criação da entidade File
7. Dispara o evento FileUploadedEvent
8. Mensagem assíncrona de compressão de imagem (ImageCompressMessage)

Otimização de imagens

ImageOptimizerService baseia-se na biblioteca Imagine:

$optimizer->optimize($sourcePath, $targetPath, [
    'max_width' => 1920,
    'max_height' => 1080,
    'quality' => 80,
    'format' => 'webp',
]);

Geração de URLs

FileUrlGenerator suporta cache e URLs temporários:

$url = $urlGenerator->getUrl($file);                          // com cache
$tempUrl = $urlGenerator->getTemporaryUrl($file, $expiresAt); // URL assinado
$urlGenerator->invalidateUrl($file);                          // limpar cache

Interface de administração

Entrada: App\Controller\Admin\StorageConfigController

Template: templates/admin/storage/