Filament Core Contracts

Propósito

Repositório base que concentra contratos PHP (interfaces), enums, Data objects e eventos reutilizados por todo o ecossistema. Não contém implementação concreta; define o contrato que cada módulo deve respeitar para se integrar por meio de mensagens consistentes.

Interfaces Principais

ProcessPaymentInterface: fluxo orquestrador que dispara cálculos e confirmações de pagamento.
PaymentGatewayInterface: contrato para gateways externos (InfinityPay, Stripe, etc).
TaxCalculatorInterface: abstrai cálculo de impostos e arredondamentos com suporte a múltiplas jurisdições.
PdfGeneratorInterface: contrato para serviços de geração de PDFs assinados.
NotificationChannelInterface: base para e-mail, SMS, WhatsApp e integrações futuras.

Data Objects

Todos os Data objects do ecossistema usam Spatie Laravel Data como base.

Por quê?

✅ Type-safe com PHP 8.3+
✅ Validação automática via attributes
✅ Transformações array/JSON/Eloquent sem boilerplate
✅ Imutabilidade garantida com readonly
✅ Nomenclatura simples: *Data ao invés de *DTO

Exemplos:

php

use Spatie\LaravelData\Data;

// Data object básico
readonly class PaymentData extends Data
{
    public function __construct(
        public string $id,
        public float $amount,
        public string $currency,
    ) {}
}

// Com validação
use Spatie\LaravelData\Attributes\Validation\Min;

readonly class InvoiceData extends Data
{
    public function __construct(
        public string $number,
        #[Min(0)]
        public float $total,
    ) {}
}

Padrões:

Sempre sufixo Data: PersonData, InvoiceData, PaymentData
Use readonly para garantir imutabilidade
Namespace: FilamentCore\Contracts\{Module}\Data\

Veja ADR-007: Spatie Laravel Data para detalhes completos.

Eventos Globais

PersonCreated / PersonUpdated: sincronizam informações cadastrais em Invoices e Communications.
InvoiceCreated / PaymentCompleted: disparam geração de PDF e notificações.
CommunicationSent: registra histórico da mensagem e encaminha para auditoria.

Boas Práticas

Versone contratos com @deprecated e changelog dedicado; nunca faça breaking changes silenciosos.
Documente payloads no README do pacote e linke para as páginas correspondentes em docs/.

Filament Core Contracts ​

Propósito ​

Interfaces Principais ​

Data Objects ​

Eventos Globais ​

Boas Práticas ​