Sistema de Traits

Macroable

Implementa o padrão Macro, permitindo adicionar métodos a classes dinamicamente em runtime.

// Extensão dinâmica em runtime
Request::macro('isApiRequest', function(): bool {
    return $this->wantsJson() || $this->expectsJson();
});

Request::macro('tenantId', function(): ?int {
    return $this->header('X-Tenant-ID') ?: session('tenant_id');
});

// Uso posterior
$request = Request::capture();
if ($request->isApiRequest()) {
    // Lógica específica para API
}

Dumpable

Sistema avançado de debugging com rastreamento automático de origem (ficheiro + linha).

class CustomerService
{
    use Dumpable;

    private int $id;
    private string $name;

    public function process(): void
    {
        // Debug completo com contexto
        $this->dumpWith('Processing customer');
        // Output: "Processing customer"
        //         🔍 Called from: /path/to/file.php:42

        // Debug apenas propriedades específicas
        $this->dumpOnly('id', 'name');

        // Chaining para debug durante desenvolvimento
        $this->dumpWith('Before save')->save()->dumpWith('After save');
    }
}

EnumCaseToArray

Trait especializado para enums PHP 8.1+ com conversões para arrays, SQL CASE statements e formatos específicos.

enum CustomerType: string
{
    use EnumCaseToArray;

    case COMPANY = 'E';
    case PRIVATE = 'P';

    public function label(): string
    {
        return match($this) {
            self::COMPANY => 'Empresa',
            self::PRIVATE => 'Particular',
        };
    }
}

// Array de valores
CustomerType::valuesToArray();
// ['E', 'P']

// Labels para UI
CustomerType::labels();
// ['COMPANY' => 'Empresa', ...]

// Formato Select2
CustomerType::toArraySelect2();
// [['value' => 'E', 'text' => 'Empresa'], ...]

// SQL CASE
CustomerType::toSqlCase('type', '= ?');

ErrorHandlingTrait

Sistema robusto de handling de erros para jobs críticos. Categoriza erros, notifica via Mattermost e fornece logging estruturado.

class SaftExportJob extends Job
{
    use ErrorHandlingTrait;

    public function handle(): void
    {
        $this->withLenientErrorHandling(function () {
            // Erros menores (array offset, undefined key) são ignorados
            // Erros críticos (connection refused, API error) param o job
            // Notificações Mattermost enviadas automaticamente

            $result = app('saftpt.export')->execute($this->data);

            if (!$result['success']) {
                throw new \Exception(json_encode($result['errors']));
            }
        });
    }
}

MemoryOptimizedTrait

Processamento usando Generators para grandes datasets. Processa milhões de registos sem esgotar memória.

class LargeReportGenerator
{
    use MemoryOptimizedTrait;

    public function generateOrdersReport(): array
    {
        // Processa 100k+ orders sem esgotar memória
        $generator = $this->processRecordsInChunks(
            table: 'orders',
            select: ['id', 'customer_id', 'total'],
            conditions: ['status' => 'completed'],
            chunkSize: 1000
        );

        // Escreve para ficheiro CSV
        return $this->writeDataToFile(
            dataGenerator: $generator,
            filePath: '/tmp/orders_report.csv',
            format: 'csv'
        );
        // Retorna: ['records_written' => 150000, 'file_size_bytes' => 8500000]
    }
}

MemoryManagementTrait

Gestão completa de memória com monitoring, thresholds (75% warning, 90% critical) e optimização automática.

$this->configureMemoryLimits('2G');
$this->logMemoryUsage('Start');

$this->processInBatches(
    data: $records,
    processor: fn($record) => $this->migrate($record),
    batchSize: 100
);

$stats = $this->getMemoryStats();
// ['current_mb' => 245.5, 'peak_mb' => 512.3]