System

Filesystem System

Abstração poderosa para gestão de ficheiros, oferecendo métodos seguros e normalizados para I/O, gestão de diretórios e downloads.

Introdução

O OfficeGest possui uma camada de abstração localizada em Modules/Common/Filesystem/. A interação principal é feita através da Facade File, que simplifica operações comuns e garante segurança.

Arquitetura do Sistema

Recuperar e Guardar Ficheiros

File::get($path)

Recupera o conteúdo de um ficheiro. Lança exceção se não existir.

try {
    $conteudo = File::get('/caminho/para/arquivo.txt');
} catch (\Exception $e) {
    // Ficheiro não existe
}

File::put($path, $contents, $permissions)

Grava conteúdo. Cria diretórios automaticamente se não existirem.

// Cria pasta 'logs/2024/' automaticamente
File::put('logs/2024/erro.log', 'Conteúdo do log');

// Com permissões específicas (0755)
File::put('scripts/executavel.sh', '#!/bin/bash...', 0755);

File::delete($path)

Remove ficheiro do sistema.

File::fileExists($path)

Verifica se existe (bool).

File::copy($from, $to)

Copia criando pastas destino.

Gestão de Diretórios

File::ensureDirectoryExists($path)

Garante existência, cria se necessário.

File::ensureDirectoryExists('storage/uploads/2024');

File::makeDirectory($path, $mode, $recursive)

Criação com controlo total.

File::makeDirectory('a/b/c', 0755, true);

Streams e Downloads

Métodos otimizados para evitar carregar ficheiros grandes para a memória RAM.

// 1. Escrever Stream em Disco (útil para uploads grandes)
$stream = fopen('php://temp', 'r+');
// ... escrever no stream ...
rewind($stream);
File::writeStream($stream, 'storage/big_file.dat');

// 2. Download para Browser via Stream (sem carregar tudo em memória)
public function export() {
    $stream = fopen('php://memory', 'r+');
    fputcsv($stream, ['ID', 'Nome']);
    rewind($stream);
    
    File::streamDownload('export.csv', $stream, 'text/csv');
}

Facade API

Método	Retorno	Descrição
get($path)	string	Conteúdo do ficheiro
put($path, $content)	bool	Grava conteúdo (cria dirs auto)
delete($path)	bool	Apaga ficheiro
ensureDirectoryExists	void	Cria diretório se não existir

Exemplos Práticos

1. Cache de Rotas (JSON)

Leitura e escrita segura de JSON.

public function saveRouteCache(array $routes): void
{
    // Grava e subscreve o ficheiro de cache
    File::put('bootstrap/cache/routes.json', json_encode($routes));
}

2. Geração de Código (Stubs)

Uso extensivo em comandos CLI.

if (File::fileExists($path)) {
    throw new \Exception("Action já existe!");
}

File::ensureDirectoryExists(dirname($path));
$stub = File::get(__DIR__.'/stubs/action.stub');
File::put($path, str_replace('{{class}}', $name, $stub));

3. QueueMaster Crash Recovery

Escrita de dumps de emergência.

// O método put encarrega-se de criar a pasta 'storage/crash_dumps/'
File::put('storage/crash_dumps/' . date('Y-m-d') . '.json', $json);

Cache Routing