Services · PHP MVC Framework

Framework\Core\Service

Classe base leve com transaction(callable $fn) protegido, que executa a função na transação da conexão e fail($message,$errors=[]), que interrompe com exceção de domínio da base. Não há container/DI automático declarado: services são instanciados explicitamente nas classes atuais.

Service existente

App\Services\Auth\AuthService implementa login/registro/logout e delega busca a UserRepository/Auth. Integrações usam o padrão Service → gateway → ApiClient, exemplificado por CepService e ViaCepGateway.

Boas práticas

Mantenha controller focado em entrada/saída e mova regras reutilizáveis para service.
Injete interfaces explicitamente quando houver alternativa, como o gateway CEP.
Use ApiClient para HTTP de saída; não replique cURL na integração.
Não publique segredos em logs nem retorne exceções internas ao cliente.

Fila, jobs assíncronos, scheduler e container de serviços não fazem parte do código analisado.

Quando vale a pena criar um Service

Use uma classe Service quando uma operação combina etapas ou precisa ser reutilizada por mais de uma interface. O Service conhece regras da aplicação, mas não deve ler $_POST, iniciar redirect nem imprimir HTML/JSON. A action prepara entrada e traduz o resultado em HTTP.

$result = $this->authService->login(
    $data['email'],
    $data['password'],
    $remember
);

if (!$result['success']) {
    Session::flash('error', $result['message']);
    $this->redirect('auth/login');
}

$this->redirect('dashboard');

Esse é o padrão real de AuthController → AuthService. `login()` devolve array `success` e, quando falha, `message`; `register()` pode devolver `user_id`; `logout()` devolve void. A API não reutiliza AuthService para emitir tokens: ela tem seu fluxo explícito em AuthApiController.

Base Service: transação e falha

Método protegido	Parâmetro	Efeito
transaction(callable $fn)	Callback	Executa na transação PDO; retorna o valor do callback após commit e reverte se houver exceção.
fail(string $message, array $errors = [])	Mensagem e array opcional	Lança RuntimeException com código 422; não retorna um payload HTTP.

Na implementação atual, o argumento $errors de Service::fail() não é anexado à RuntimeException. Não conte com ele para transmitir mapa de erros; se a UI/API precisa desses detalhes, mantenha um contrato explícito de retorno no Service e trate-o no Controller.

Instanciação é explícita e construtores podem receber dependências. Não há container, fila, job assíncrono ou scheduler implementado. Para persistência, o padrão usado é Repository; para validação, FormRequest.