learnpress / inc / MCP / Support / Errors.php

Errors.php in LearnPress – WordPress LMS Plugin for Create and Sell Online Courses 4.4.4, at inc/MCP/Support/Errors.php

180 lines 4.4 KB

Raw Download Zip

1	<?php
2
3	namespace LearnPress\MCP\Support;
4
5	use Throwable;
6	use WP_Error;
7
8	defined( 'ABSPATH' ) \|\| exit;
9
10	/**
11	* Single MCP error factory.
12	*
13	* The only place LearnPress MCP builds WP_Error responses. Transport auth
14	* (ApiKeyAuthenticator), the ability permission gate (Abilities), the Phase 1
15	* Concerns executors, and the Phase 2 domain executors all call these builders
16	* so error codes, statuses, and messages have one source of truth
17	* (400/401/403/404/500).
18	*/
19	class Errors {
20
21	/**
22	* Build a WP_Error with an HTTP-style status code.
23	*
24	* @param string $code Error code.
25	* @param string $message Human-readable message.
26	* @param int $status HTTP status.
27	*
28	* @return WP_Error
29	*/
30	public static function make( string $code, string $message, int $status ): WP_Error {
31	return new WP_Error( $code, $message, array( 'status' => $status ) );
32	}
33
34	/**
35	* 400 invalid input / invalid state transition.
36	*
37	* @param string $message Error message.
38	*
39	* @return WP_Error
40	*/
41	public static function invalid( string $message ): WP_Error {
42	return self::make( 'lp_mcp_invalid_input', $message, 400 );
43	}
44
45	/**
46	* 404 missing target entity.
47	*
48	* @param string $message Error message.
49	*
50	* @return WP_Error
51	*/
52	public static function not_found( string $message ): WP_Error {
53	return self::make( 'lp_mcp_not_found', $message, 404 );
54	}
55
56	/**
57	* 403 insufficient capability for a specific entity/action.
58	*
59	* @param string $message Optional message.
60	*
61	* @return WP_Error
62	*/
63	public static function forbidden( string $message = '' ): WP_Error {
64	if ( '' === $message ) {
65	$message = __( 'You do not have permission to perform this action.', 'learnpress' );
66	}
67
68	return self::make( 'lp_mcp_forbidden', $message, 403 );
69	}
70
71	/**
72	* 500 generic LearnPress MCP failure.
73	*
74	* @return WP_Error
75	*/
76	public static function internal(): WP_Error {
77	return self::make(
78	'lp_mcp_internal_error',
79	__( 'An internal LearnPress MCP error occurred.', 'learnpress' ),
80	500
81	);
82	}
83
84	/**
85	* Convert a caught throwable into a generic MCP 500 error.
86	*
87	* Logs the original message for debugging but never leaks it to clients.
88	*
89	* @param Throwable $e Caught throwable.
90	*
91	* @return WP_Error
92	*/
93	public static function from_throwable( Throwable $e ): WP_Error {
94	error_log( 'LearnPress MCP: ' . $e->getMessage() );
95
96	return self::internal();
97	}
98
99	/**
100	* 401 missing/invalid MCP authentication (ability permission gate).
101	*
102	* @param string $message Optional message.
103	*
104	* @return WP_Error
105	*/
106	public static function missing_auth( string $message = '' ): WP_Error {
107	if ( '' === $message ) {
108	$message = __( 'Missing or invalid MCP authentication.', 'learnpress' );
109	}
110
111	return self::make( 'learnpress_mcp_missing_auth', $message, 401 );
112	}
113
114	/**
115	* 403 current user lacks the required base capability.
116	*
117	* @param string $capability Required capability name.
118	*
119	* @return WP_Error
120	*/
121	public static function missing_capability( string $capability ): WP_Error {
122	return self::make(
123	'learnpress_mcp_missing_base_capability',
124	sprintf(
125	/* translators: %s: capability. */
126	__( 'Current user does not have required base capability: %s.', 'learnpress' ),
127	$capability
128	),
129	403
130	);
131	}
132
133	/**
134	* 403 API key scope is insufficient for the ability.
135	*
136	* @param string $required_scope Required scope for the ability.
137	* @param string $granted_scope Scope granted by the authenticated API key.
138	*
139	* @return WP_Error
140	*/
141	public static function insufficient_scope( string $required_scope, string $granted_scope ): WP_Error {
142	return self::make(
143	'learnpress_mcp_insufficient_scope',
144	sprintf(
145	/* translators: 1: required scope, 2: granted scope. */
146	__( 'API key scope is insufficient. Required: %1$s. Granted: %2$s.', 'learnpress' ),
147	$required_scope,
148	$granted_scope
149	),
150	403
151	);
152	}
153
154	/**
155	* 401 MCP API key authentication is required (transport layer).
156	*
157	* @return WP_Error
158	*/
159	public static function api_key_required(): WP_Error {
160	return self::make(
161	'learnpress_mcp_api_key_required',
162	__( 'MCP API key authentication is required.', 'learnpress' ),
163	401
164	);
165	}
166
167	/**
168	* 401 invalid MCP API key credentials (transport layer).
169	*
170	* @return WP_Error
171	*/
172	public static function invalid_api_credentials(): WP_Error {
173	return self::make(
174	'learnpress_mcp_invalid_api_key_credentials',
175	__( 'Invalid MCP API credentials.', 'learnpress' ),
176	401
177	);
178	}
179	}
180