Adds 503 maintenance error handling

Ensures API requests return a consistent maintenance response when the service is unavailable instead of falling back to generic HTTP error handling.

Adds a dedicated default message for maintenance mode and covers the new behavior with a feature test.

Author: Ricardo Bazan

.phpunit.cache/test-results

@@ -1 +1 @@
-{"version":2,"defects":[],"times":{"Hardcodear\\ApiResponseService\\Tests\\Contract\\ResponseShapeTest::test_success_contract_shape_is_stable":0.057,"Hardcodear\\ApiResponseService\\Tests\\Contract\\ResponseShapeTest::test_error_contract_shape_is_stable":0,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_registers_renderer_and_maps_known_api_exceptions":0.014,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_does_not_intercept_non_api_routes":0,"Hardcodear\\ApiResponseService\\Tests\\Regression\\NullOmissionTest::test_data_key_is_omitted_when_null":0.001,"Hardcodear\\ApiResponseService\\Tests\\Regression\\NullOmissionTest::test_errors_key_is_omitted_when_null":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_success_response_includes_data_when_present":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_success_response_omits_data_when_null":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_wraps_object_errors_in_array":0.001,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_wraps_associative_array_errors_in_array":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_keeps_indexed_array_errors_as_is":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_omits_errors_when_null":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_success_method_uses_200_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_method_uses_500_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_not_found_method_uses_404_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_validation_method_uses_422_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_forbidden_method_uses_403_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_unauthorized_method_uses_401_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_server_error_method_uses_500_status":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\FacadeTest::test_facade_resolves_accessor_and_returns_json_response":0.001,"Hardcodear\\ApiResponseService\\Tests\\Unit\\HelperTest::test_apiresponse_helper_exists_and_resolves_service":0,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ServiceProviderTest::test_service_is_registered_in_container_as_singleton":0,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_validation_exception_to_422_with_errors":0.006,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_authorization_exception_to_403":0.001,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_generic_http_exception_status_for_api_routes":0}}
+{"version":2,"defects":[],"times":{"Hardcodear\\ApiResponseService\\Tests\\Contract\\ResponseShapeTest::test_success_contract_shape_is_stable":0.113,"Hardcodear\\ApiResponseService\\Tests\\Contract\\ResponseShapeTest::test_error_contract_shape_is_stable":0.002,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_registers_renderer_and_maps_known_api_exceptions":0.01,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_does_not_intercept_non_api_routes":0.002,"Hardcodear\\ApiResponseService\\Tests\\Regression\\NullOmissionTest::test_data_key_is_omitted_when_null":0.002,"Hardcodear\\ApiResponseService\\Tests\\Regression\\NullOmissionTest::test_errors_key_is_omitted_when_null":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_success_response_includes_data_when_present":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_success_response_omits_data_when_null":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_wraps_object_errors_in_array":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_wraps_associative_array_errors_in_array":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_keeps_indexed_array_errors_as_is":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_response_omits_errors_when_null":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_success_method_uses_200_status":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_error_method_uses_500_status":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_not_found_method_uses_404_status":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_validation_method_uses_422_status":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_forbidden_method_uses_403_status":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_unauthorized_method_uses_401_status":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ApiResponseServiceTest::test_server_error_method_uses_500_status":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\FacadeTest::test_facade_resolves_accessor_and_returns_json_response":0.003,"Hardcodear\\ApiResponseService\\Tests\\Unit\\HelperTest::test_apiresponse_helper_exists_and_resolves_service":0.002,"Hardcodear\\ApiResponseService\\Tests\\Unit\\ServiceProviderTest::test_service_is_registered_in_container_as_singleton":0.002,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_validation_exception_to_422_with_errors":0.014,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_authorization_exception_to_403":0.003,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_generic_http_exception_status_for_api_routes":0.003,"Hardcodear\\ApiResponseService\\Tests\\Feature\\ExceptionApiRegistrarTest::test_bind_maps_service_unavailable_exception_to_503":0.003}}

config/apiresponse.php

@@ -16,5 +16,6 @@
         'authorization' => 'No autorizado para este recurso',
         'client_error' => 'Error en la solicitud',
         'server_error' => 'Error interno del servidor',
+        'service_unavailable' => 'El sistema se encuentra en mantenimiento',
     ],
 ];

src/ApiResponseService.php

@@ -16,6 +16,7 @@ class ApiResponseService
     public const HTTP_INTERNAL_SERVER_ERROR = 500;
     public const HTTP_TOO_MANY_REQUESTS = 429;
     public const HTTP_METHOD_NOT_ALLOWED = 405;
+    public const HTTP_SERVICE_UNAVAILABLE = 503;
 
     public function successResponse(int $status = self::HTTP_OK, ?string $message = null, mixed $data = null): JsonResponse
     {

src/ExceptionApiRegistrar.php

@@ -12,6 +12,7 @@
 use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
 use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException;
 use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
 use Symfony\Component\Routing\Exception\RouteNotFoundException;
 
@@ -53,6 +54,10 @@ public static function bind(Exceptions $exceptions): void
                     return apiresponse()->errorResponse(ApiResponseService::HTTP_METHOD_NOT_ALLOWED, self::message('method_not_allowed', 'Metodo HTTP no permitido para esta ruta'));
                 }
 
+                if ($e instanceof ServiceUnavailableHttpException) {
+                    return apiresponse()->errorResponse(ApiResponseService::HTTP_SERVICE_UNAVAILABLE, self::message('service_unavailable', 'El sistema se encuentra en mantenimiento'));
+                }
+
                 if ($e instanceof HttpExceptionInterface) {
                     $status = $e->getStatusCode();
                     $message = $e->getMessage();

tests/Feature/ExceptionApiRegistrarTest.php

@@ -15,6 +15,7 @@
 use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
 use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException;
 use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
 use Symfony\Component\Routing\Exception\RouteNotFoundException;
 use Throwable;
@@ -148,6 +149,33 @@ public function test_bind_maps_authorization_exception_to_403(): void
         $this->assertSame(ApiResponseService::HTTP_FORBIDDEN, $response->getStatusCode());
     }
 
+    public function test_bind_maps_service_unavailable_exception_to_503(): void
+    {
+        $renderer = null;
+
+        $exceptions = $this->getMockBuilder(Exceptions::class)
+            ->disableOriginalConstructor()
+            ->onlyMethods(['render'])
+            ->getMock();
+
+        $exceptions->expects($this->once())
+            ->method('render')
+            ->willReturnCallback(function (callable $callback) use (&$renderer) {
+                $renderer = $callback;
+
+                return null;
+            });
+
+        ExceptionApiRegistrar::bind($exceptions);
+
+        $request = Request::create('/api/status', 'GET');
+        $response = $renderer(new ServiceUnavailableHttpException(null, 'maintenance'), $request);
+
+        $this->assertInstanceOf(JsonResponse::class, $response);
+        $this->assertSame(ApiResponseService::HTTP_SERVICE_UNAVAILABLE, $response->getStatusCode());
+        $this->assertSame(ApiResponseService::HTTP_SERVICE_UNAVAILABLE, $response->getData(true)['status']);
+    }
+
     public function test_bind_maps_generic_http_exception_status_for_api_routes(): void
     {
         $renderer = null;