Download the PHP package proside/file-manager without Composer

Proside File Manager (Livewire v4)

Gestor de ficheiros reutilizável para Laravel 10/11/12 construído integralmente em Livewire v4. Substitui o antigo File Manager em Next.js/React, mantendo paridade funcional e melhorando a arquitetura: sem iframe, sem JWT, sem serviço externo — corre dentro da própria aplicação Laravel e usa a autenticação/sessão existente.

Compatível com Laravel 10.49 e PHP 8.1+. Requer Livewire ^4.0.

Funcionalidades

• Árvore de diretórios lateral com lazy-load e expandir/colapsar
• Vistas em grelha e lista
• Filtros (Tudo / Pastas / Imagens / Vídeos) e ordenação (A–Z / Z–A)
• Breadcrumbs de navegação
• Seleção simples e múltipla (Shift)
• Menu de contexto: criar subpasta, renomear, eliminar, visualizar, descarregar, escolher
• Upload por botão flutuante (FAB) e por arrastar ficheiros do sistema
• Mover por drag & drop (incluindo múltiplos itens) para pastas ou para a árvore
• Lixo (apagados) com retenção configurável e expiração automática
• Restaurar itens do lixo (novo) e eliminação definitiva
• Pré-visualização (lightbox) de imagens e vídeos
• Pesquisa funcional por nome (o FM antigo não pesquisava)
• Pronto para picker de ficheiros em formulários (<x-file-manager::picker>)
• Multi-disco (local/public, S3, …) via Filesystem do Laravel
• Copiar URL de um ficheiro a partir do menu de contexto
• Traduções PT/EN, totalmente publicáveis

Instalação

O Service Provider, rotas, componente Livewire e componentes Blade são registados automaticamente (package discovery).

1. Garantir o disco e o symlink

Por omissão usa o disco public. Crie o symlink uma vez:

2. (Opcional) Publicar recursos

3. Tailwind (importante)

O package usa classes utilitárias Tailwind (paleta proximo, equivalente ao antigo proximo). Se a sua app compila Tailwind, adicione o caminho das vistas do package ao content do tailwind.config.js para que as classes sejam geradas:

Tailwind v4 não usa o content do tailwind.config.js e ignora por omissão tudo o que está no .gitignore — ou seja, o vendor/. No ficheiro CSS de entrada da app:

Recompile (npm run build) depois de cada composer update do package, senão as classes novas não entram no CSS e a UI aparece meio por estilizar.

4. Agendar a limpeza do lixo

Em app/Console/Kernel.php:

Utilização

Página inteira

Já existe a rota GET /file-manager (configurável). Ou embeba o componente onde quiser:

Picker em formulários (drop-in)

Substitui o antigo <x-file-manager-modal> com a mesma API de props:

O ficheiro escolhido fica num <input type="hidden" name="..."> — o submit do formulário funciona exatamente como antes. Ao escolher, o componente emite o evento Livewire file-manager-selected ({ paths: [...] }).

Permissões por utilizador (scoping)

O File Manager pode confinar cada utilizador a uma ou mais pastas-raiz próprias. Define um resolver que devolve a(s) raiz(es) efetiva(s) do utilizador atual (relativas ao disco), ou null para acesso total:

Regras aplicadas pelo package quando há resolver:

• devolve null, '', ou um valor igual à raiz da config → acesso total;
• devolve "conteudos/optivisao" → o utilizador só vê essa pasta para baixo (árvore, breadcrumbs, navegação e operações ficam confinadas; aceder acima é bloqueado por PathGuard).
• devolve um array (ex.: ['conteudos/a', 'conteudos/b']) → o utilizador vê várias raízes: cada uma aparece na sidebar com a sua árvore, abre-se na primeira, e a navegação fica confinada a qualquer uma delas. Caminhos fora da raiz da config são ignorados (não escalam privilégios).

O lixo espelha a árvore de origem

conteudos/optivisao/fotos/x.png é eliminado para apagados/conteudos/optivisao/fotos/x.png. Isto tem três consequências:

• Confinamento por prefixo. O lixo de cada raiz é um ramo próprio, validado pelo PathGuard como qualquer outro caminho. Um utilizador confinado não consegue ler, restaurar nem eliminar definitivamente o que outro apagou.
• Restauro sem metadados. O destino vem do próprio caminho, e é revalidado — um item não pode ser restaurado para fora das raízes do utilizador.
• Sem colisões. a/relatorio.txt e b/relatorio.txt deixam de disputar o mesmo nome no lixo.

O sidecar .meta.json mantém-se, mas só guarda o prazo de expiração.

Migração. Instalações que já tenham itens no lixo antigo (plano, em apagados/<ficheiro>) deixam de os ver — o acesso falha fechado, nada é perdido. Para os recuperar, mova cada ficheiro para o caminho indicado no respetivo originalPath prefixado por apagados/, ou esvazie o lixo antes de atualizar.

Copiar URL

O menu de contexto de um ficheiro tem Copiar URL, que copia o endereço de media (…/file-manager/media/conteudos/…) para a área de transferência.

A cópia é feita inteiramente no cliente: o URL já vem em cada item da listagem, por isso não há pedido ao servidor. É um endereço público e permanente — vale o que a rota de media valer (ver a nota mais abaixo).

Auditoria

As operações que alteram ficheiros (upload, mover, copiar, duplicar, renomear, criar pasta, eliminar, restaurar, eliminar definitivamente, partilhar, prune) são registadas via o logger do Laravel, com utilizador e IP. Para as separar do log da aplicação, defina um canal em config/logging.php e aponte file-manager.audit.channel para ele.

Exemplo de resolver (Backoffice Proside — perfil gflevel ligado por gfleveluser, campo gflevel_ctvdir): ver docs/BACKOFFICE-INTEGRATION.md. O resolver pode ser um class-string invocável (compatível com config:cache) ou um callable.

Configuração (config/file-manager.php)

Variáveis .env: FILE_MANAGER_DISK, FILE_MANAGER_ROOT, FILE_MANAGER_TRASH, FILE_MANAGER_TRASH_DAYS, FILE_MANAGER_MAX_UPLOAD, FILE_MANAGER_MEDIA_URL, FILE_MANAGER_ROUTE, FILE_MANAGER_ROUTE_PREFIX, FILE_MANAGER_SEARCH_CACHE, FILE_MANAGER_AUDIT, FILE_MANAGER_AUDIT_CHANNEL.

Nota sobre a rota de media

A rota de media é pública por omissão (route.media_middleware): quem tiver o URL vê o ficheiro, sem autenticação. Isso é deliberado — permite embeber imagens em páginas públicas — mas implica que o URL é a única barreira. O lixo e os sidecars .meta.json nunca são servidos por esta rota. Para conteúdo que não deva ser público, proteja a rota acrescentando auth a media_middleware. É esse o endereço que a ação Copiar URL coloca na área de transferência.

Funcionalidades

• Ações em massa (seleção múltipla + checkboxes): mover, copiar, duplicar, eliminar, restaurar, descarregar.
• Multi-raiz: o root_resolver pode devolver um array de caminhos; cada raiz aparece na sidebar com a sua árvore.
• Ordenar por nome (A–Z/Z–A), data (recentes/antigos) e tamanho (maiores/menores); filtrar por pastas/imagens/vídeos/ocultar pastas.
• Pesquisa recursiva em toda a raiz efetiva (não só na pasta atual).
• Download: individual (GET media|download/<caminho>) e ZIP de seleção/pastas (POST download-zip).
• Media com caminho direto no URL (…/media/pasta/ficheiro.ext), pública por omissão (configurável via route.media_middleware).
• Upload por drag & drop direto na dropzone do picker (POST upload).
• Picker (<x-file-manager::picker />): prop size (small | large dropzone), pré-visualização com lightbox, e envio da duração do vídeo por postMessage ao escolher ({ source:'file-manager', type:'video-duration', path, url, duration }).
• Loader enquanto qualquer media carrega (grelha, picker, lightbox).

Correspondência Next.js → Livewire

Melhorias face à versão anterior

• Sem serviço externo: deixa de ser preciso FILE_MANAGER_URL, proxy HTTP, JWT RS256 e chaves .pem.
• Segurança: auth nativa do Laravel + PathGuard contra path traversal.
• Retenção do lixo correta: era 60s no código (texto dizia 30 dias); agora é configurável (30 por omissão).
• Restaurar itens do lixo (não existia).
• Pesquisa funcional (não existia).
• Multi-disco via Filesystem (S3-ready), em vez de fs direto no public/.
• Navegação preservada ao filtrar por imagens/vídeos (pastas continuam visíveis).
• Limpeza do lixo por comando agendado em vez de polling no cliente.

Integração no Backoffice Proside: ver docs/BACKOFFICE-INTEGRATION.md.