63 lines
2.6 KiB
Markdown
Executable File
63 lines
2.6 KiB
Markdown
Executable File
# 📁 Regra de Armazenamento de Arquivos e Uploads (51_UPLOADS_STORAGE.md)
|
|
|
|
## ❗ Regra Fundamental
|
|
**Nenhum módulo do SysCMS deve gravar arquivos diretamente no diretório `public/`.**
|
|
|
|
Todos os uploads, arquivos gerados pelo sistema ou mídias de usuários devem ser obrigatoriamente armazenados no diretório `storage/uploads/{nome-do-modulo}/`.
|
|
|
|
---
|
|
|
|
## 🏗️ Estrutura de Armazenamento (Padrão Único e Definitivo)
|
|
- **Localização Física**: `storage/uploads/{nome-do-modulo}/`
|
|
- **URL de Acesso**: `url('storage/uploads/{nome-do-modulo}/' ~ nome_arquivo)`
|
|
- **Funciona em**: Windows e Linux (Docker)
|
|
- **OBRIGATÓRIO**: Subpastas por módulo (ex: `storage/uploads/erpcarriers/`, `storage/uploads/blog/`)
|
|
- **PROIBIDO**: Uso de Links Simbólicos (Symlinks), Junctions ou Atalhos.
|
|
- **Este padrão é definitivo e imutável** - NUNCA deve ser alterado
|
|
---
|
|
|
|
## 🌐 Acesso via Web
|
|
Os arquivos em `storage/uploads/{nome-do-modulo}/` são acessíveis via rota do sistema.
|
|
|
|
### Geração de URLs
|
|
Para acessar um arquivo via navegador, utilize o helper `url()` apontando para `storage/uploads/{nome-do-modulo}/`:
|
|
- **Correto**: `url('storage/uploads/blog/imagem.jpg')`
|
|
- **Incorreto**: `url('public/uploads/imagem.jpg')`
|
|
- **Incorreto**: `url('storage/imagem.jpg')` (sem módulo)
|
|
|
|
---
|
|
|
|
## 🛠️ Implementação no Código (PHP)
|
|
|
|
### 1. Definindo o Diretório de Upload
|
|
Sempre utilize caminhos absolutos baseados na raiz do projeto e inclua o nome do módulo:
|
|
```php
|
|
$moduleName = 'erpcarriers'; // Exemplo
|
|
$uploadDir = dirname(__DIR__, 4) . '/storage/uploads/' . $moduleName . '/';
|
|
if (!is_dir($uploadDir)) {
|
|
mkdir($uploadDir, 0755, true);
|
|
}
|
|
```
|
|
|
|
### 2. Salvando o Caminho no Banco de Dados
|
|
Grave apenas o nome do arquivo:
|
|
- **BD**: `imagem.jpg`
|
|
- **NÃO**: `blog/imagem.jpg` (redundante se a pasta for padrão)
|
|
|
|
### 3. Exibindo no Frontend (Twig)
|
|
```twig
|
|
<img src="{{ url('storage/uploads/erpcarriers/' ~ registro.imagem) }}" alt="...">
|
|
```
|
|
|
|
---
|
|
|
|
## 🛡️ Segurança e Manutenção
|
|
1. **Proteção de Diretório**: O diretório `storage/` contém um arquivo `.htaccess` que impede a execução de scripts PHP, garantindo que arquivos maliciosos enviados por upload não sejam executados.
|
|
2. **Limpeza**: Ao remover um registro que possui arquivos associados, o arquivo físico deve ser removido utilizando `unlink()`.
|
|
3. **Nomes de Arquivos**: Use nomes únicos (ex: `TRA` + random_bytes + timestamp + extensão) para evitar conflitos.
|
|
|
|
---
|
|
|
|
## ⚠️ Importante
|
|
Este padrão está definido como definitivo e imutável no [DECISIONS.md](../../DECISIONS.md). Em caso de dúvida, consulte sempre o DECISIONS.md antes de implementar funcionalidades de upload.
|