README

Paquete Laravel 12+ (incluye Laravel 13) para formatear respuestas JSON de forma estandarizada.

Este paquete proporciona una forma consistente de estructurar las respuestas JSON para APIs Laravel, siguiendo un formato uniforme para respuestas exitosas y de error.

✅ Compatibilidad

• PHP 8.2+
• Laravel 12+ (incluye 13)

📦 Instalación

Instalar el paquete

En consola:

composer require hardcodear/api-response-service

Laravel detectará automáticamente el ServiceProvider y registrará el alias del facade apiresponse gracias al archivo composer.json del paquete.

⚡ Quick Start

<?php

use Illuminate\Http\Request;

class UserController
{
  public function index()
  {
    return apiresponse()->success('Listado de usuarios', [
      ['id' => 1, 'name' => 'Ana'],
      ['id' => 2, 'name' => 'Luis'],
    ]);
  }

  public function store(Request $request)
  {
    $errors = [];

    if (! $request->input('email')) {
      $errors['email'][] = 'El campo email es obligatorio.';
    }

    if ($errors !== []) {
      return apiresponse()->validation('Datos inválidos', $errors);
    }

    return apiresponse()->success('Usuario creado', ['id' => 123]);
  }
}

🧰 Funcionalidades disponibles

El paquete expone los siguientes métodos a través del helper apiresponse() (o facade ApiResponse):

✅ Respuestas exitosas

apiresponse()->success(string $mensaje = null, mixed $data = null)

return apiresponse()->success('Operación realizada con éxito', ['id' => 123]);

📭 Not Found (404)

apiresponse()->notFound(string $mensaje = null, mixed $errores = null)

return apiresponse()->notFound('Recurso no encontrado');

🛑 Validación fallida (422)

apiresponse()->validation(string $mensaje = null, mixed $errores = null)

return apiresponse()->validation('Datos inválidos', $validator->errors());

🔐 No autorizado (401)

apiresponse()->unauthorized(string $mensaje = null, mixed $errores = null)

return apiresponse()->unauthorized('Token inválido');

🚫 Prohibido (403)

apiresponse()->forbidden(string $mensaje = null, mixed $errores = null)

return apiresponse()->forbidden('Acceso denegado');

💥 Error del servidor (500)

apiresponse()->serverError(string $mensaje = null, mixed $errores = null)

return apiresponse()->serverError('Error inesperado');

❌ Errores personalizados

apiresponse()->error(string $mensaje = null, mixed $errores = null)

return apiresponse()->error('Error inesperado', ['detalle' => '...']);

🧪 Estructura del JSON resultante

Éxito

{
  "status": 200,
  "message": "Mensaje opcional",
  "data": {
    // contenido devuelto
  }
}

Error

{
  "status": 500,
  "message": "Mensaje de error",
  "errors": [
    // array de errores
  ]
}

El campo errors puede ser un array plano o un array asociativo (por ejemplo, errores de validación).

Cuando data o errors son null, esas claves se omiten automáticamente del JSON.

📌 Manejo global de excepciones (opcional)

Si querés que tu API devuelva respuestas JSON uniformes ante errores comunes como rutas no encontradas, permisos o límites de peticiones, podés usar el registrador de excepciones incluido en este paquete.

Esto te permite centralizar el manejo de errores en bootstrap/app.php, sin repetir lógica en cada controlador.

🧱 Editar bootstrap/app.php

Agregá el binding dentro de withExceptions(...) en bootstrap/app.php:

use Hardcodear\ApiResponseService\ExceptionApiRegistrar;
use Illuminate\Foundation\Configuration\Exceptions;

$app->withExceptions(function (Exceptions $exceptions) {
    ExceptionApiRegistrar::bind($exceptions);
});

⚙️ ¿Qué hace esto?

Intercepta excepciones comunes y devuelve respuestas formateadas como:

{
  "status": 404,
  "message": "URL no encontrada"
}

Las excepciones manejadas por defecto son:

• AccessDeniedHttpException → 401 Unauthorized
• NotFoundHttpException → 404 Not Found
• TooManyRequestsHttpException → 429 Too Many Requests
• RouteNotFoundException → 401 Unauthorized
• AuthenticationException → 401 Unauthorized
• AuthorizationException → 403 Forbidden
• MethodNotAllowedHttpException → 405 Method Not Allowed
• ValidationException → 422 Unprocessable Entity
• HttpExceptionInterface (fallback) → respeta el status HTTP en rutas API

⚙️ Configuracion opcional (v1.1)

Si queres personalizar patrones de rutas y mensajes, publica la configuracion:

php artisan vendor:publish --tag=apiresponse-config

Archivo publicado: config/apiresponse.php

• api_patterns: patrones de ruta a interceptar (default: ['api', 'api/*'])
• messages: mensajes por tipo de excepcion

🧪 Testing

Ejecutar la suite localmente:

composer test

El repositorio también ejecuta tests automáticamente en GitHub Actions para push y pull_request con PHP 8.2 y 8.3, validando Laravel 12 y 13 en combinaciones compatibles.

Matriz de CI actual:

🧑 Autor

Ricardo Bazán
Argentina, 2026
Repositorio interno: https://github.com/hardcodear/api-response-service

📄 Licencia

Este paquete está licenciado bajo la MIT License.