1	<?php
2
3	declare(strict_types=1);
4
5	namespace App\Domain\Exception;
6
7	use Throwable;
8
9	/**
10	* Marker interface for exceptions that map to a specific HTTP status code.
11	*
12	* Exceptions implementing this interface declare their own HTTP status code
13	* and a human-readable title. The {@see \App\Middleware\ExceptionMiddleware}
14	* uses this information to build the API response automatically — there is
15	* no central mapping table to keep in sync. Adding a new exception class
16	* means implementing this interface; the middleware does not need to be
17	* updated.
18	*
19	* Any exception that should result in a non-500 HTTP response MUST implement
20	* this interface. Exceptions that do not implement it (e.g., the built-in
21	* \RuntimeException, \PDOException, or any unhandled error) are treated as
22	* server failures and return HTTP 500.
23	*
24	* Status code reference (per RFC 9110):
25	*
26	*   400 Bad Request           — request structure invalid (missing fields,
27	*                               wrong types, malformed JSON)
28	*   401 Unauthorized          — authentication missing or invalid
29	*   403 Forbidden             — authenticated but not allowed
30	*   404 Not Found             — resource does not exist
31	*   409 Conflict              — request conflicts with the current state of
32	*                               the resource (e.g. "already approved")
33	*   422 Unprocessable Entity  — values violate semantic or business rules
34	*                               (e.g. "amount must be > 0")
35	*   500 Internal Server Error — server failure not caused by the client
36	*/
37	interface HttpStatusException extends Throwable
38	{
39	/**
40	* The HTTP status code this exception should produce in the API response.
41	*/
42	public function getStatusCode(): int;
43
44	/**
45	* Short human-readable title for the error response (e.g. "Not Found",
46	* "Validation Error"). This is the user-facing label, separate from
47	* {@see Throwable::getMessage()} which contains the specific detail.
48	*/
49	public function getTitle(): string;
50	}