filefill para TYPO3

filefill poupa dias de sincronização para desenvolvedores e agências, a extensão carrega arquivos ausentes do fileadmin automaticamente do servidor de produção quando eles são realmente necessários

Quem trabalha em um projeto TYPO3 existente conhece o ritual: o setup local está pronto, o dump do banco foi importado, mas em metade das páginas aparecem placeholders no lugar de imagens. A razão é banal: o diretório fileadmin do sistema live contém gigabytes de assets que localmente faltam. A solução clássica era rsync ou scp por horas. O filefill elimina esse passo por completo. Em vez de copiar todos os arquivos antes, a extensão carrega no primeiro acesso exatamente o arquivo necessário do servidor remoto configurado, on demand, de forma transparente, com caching. Para agências que trabalham em vários projetos permanentemente, isso economiza não só espaço, mas horas por setup.

O ganho de produtividade é maior do que parece à primeira vista. Um novo desenvolvedor não fica operacional apenas após uma hora de download, mas em poucos minutos. Um code review em um feature branch esquecido não precisa de um file sync atual. Uma reprodução rápida de um bug report não se arrasta pela metade do dia. A pequena extensão atende assim um gargalo real do dia a dia dos desenvolvedores.

Cenários típicos de uso

O caso mais frequente é o setup local de desenvolvimento. Um desenvolvedor clona o projeto TYPO3, configura DDEV ou Docker e importa o dump de banco atual. Em vez de baixar adicionalmente 30 GB de dados do fileadmin, ele configura o filefill com a URL base do sistema live. A cada carregamento de página que pede uma imagem ou documento, a extensão verifica se o arquivo existe localmente e o carrega quando necessário. Depois de alguns dias de trabalho, só os arquivos realmente usados estão locais, o resto permanece no servidor.

O segundo caso são ambientes de staging. Uma agência mantém para cada projeto um sistema de staging onde redatores testam conteúdos antes do go live. Esses sistemas de staging não precisam guardar todas as imagens, apenas as dos releases atuais. O filefill garante que conteúdos mais antigos continuem funcionando, porque os arquivos são puxados do sistema live quando necessários.

Terceiro uso: disaster recovery e cenários de hotfix. Quando um sistema TYPO3 precisa ser subido rapidamente em uma máquina nova, após uma queda de servidor ou em uma migração urgente de ambiente, o filefill pode cobrir a provisão de assets nas primeiras horas, até o restore completo do backup estar pronto.

Arquitetura técnica

O filefill se conecta ao sistema FAL do TYPO3, mais precisamente ao mecanismo de retrieval de recursos. Assim que o TYPO3 solicita um arquivo do storage local e descobre que ele não existe, um event listener do filefill age. A extensão verifica uma lista de “sources” configuradas na ordem da prioridade e tenta carregar o arquivo de lá. Arquivos carregados com sucesso são salvos localmente, de forma que o próximo acesso dispensa requisição remota.

A configuração é feita via extension settings no Install Tool. Tipicamente uma remote source com URL base e, opcionalmente, credenciais HTTP Basic Auth é registrada. Para setups com CDN ou S3, esse caminho também pode servir como fonte. A extensão suporta várias sources, útil em cenários mais complexos com servidores de asset separados.

É importante que o filefill trabalha apenas de forma passiva. A extensão não baixa nada antes, reage exclusivamente a requisições concretas de arquivo. Isso a torna modesta no consumo de recursos e discreta na operação. A integração com DDEV, Docker Compose ou Lando é trivial, porque a extensão não precisa de serviços adicionais.

Problemas frequentes e soluções

O primeiro problema são restrições de acesso. Quando o servidor live só entrega imagens a usuários logados ou certos paths são protegidos por htaccess, o filefill não consegue carregar. A solução está na configuração correta da autenticação HTTP e, se preciso, em uma regra de whitelist no servidor live que dê ao ambiente de desenvolvimento acesso ao path fileadmin.

Segundo problema: uso acidental em produção. Se o filefill está ativo em um ambiente live e a remote source é o próprio ambiente, surge uma recursão perigosa. A extensão não deve rodar em produção nunca. A solução pragmática é manter o filefill apenas no bloco Composer “require-dev” e ativar via variáveis de ambiente, não pelo Install Tool.

Terceiro problema: estados inconsistentes de arquivo. Quando o sistema live troca um arquivo, mas a cópia local já está cacheada, o desenvolvedor continua vendo a versão antiga. A solução é limpar o fileadmin local ocasionalmente ou fazer cache busting via remote source. No trabalho diário, isso raramente é problema, porque nomes de arquivo na troca costumam ser novos.

Migração e compatibilidade de versões

O filefill é compatível com TYPO3 v11, v12 e v13 e é desenvolvido ativamente. Em upgrades, a versão da extensão deve corresponder à versão TYPO3, porque o sistema de eventos FAL teve pequenas mudanças entre v11 e v12. Quem usa a extensão em processos de desenvolvimento existentes deve testar rapidamente em upgrades maiores se todas as sources ainda estão acessíveis.

Uma solução relacionada é o EXT:aus_driver_amazon_s3, que mantém o fileadmin diretamente em um bucket S3. A diferença: o aus_driver_amazon_s3 é uma solução de produção, o filefill é um auxiliar de desenvolvimento. Os dois se complementam, um projeto com storage S3 em produção pode usar filefill localmente para puxar do bucket apenas os arquivos em edição atual.

Para agências que usam filefill de forma padronizada, vale uma documentação no wiki do projeto explicando como a extensão é ativada, quais credenciais são necessárias e como proceder em problemas. Isso reduz o esforço de suporte no time e torna o onboarding de novos desenvolvedores confiável. Complementarmente, vale um script curto que, no setup de um novo ambiente local, insira a configuração correta automaticamente.

A Gosign instala e configura filefill em ambientes de desenvolvimento e integra a extensão em setups DDEV e Docker, de forma que novos membros do projeto estejam operacionais em poucos minutos.