jetpack / vendor / wp-php-toolkit / reprint-server / src / class-push-exception.php

class-push-exception.php in Jetpack – WP Security, Backup, Speed, & Growth 16.3-a.1, at vendor/wp-php-toolkit/reprint-server/src/class-push-exception.php

88 lines 3.5 KB

Raw Download Zip

1	<?php
2
3	/**
4	* Reports a classified push-session failure.
5	*
6	* PHP reserves Throwable::getCode() for an integer. Push and commit failures use
7	* stable, descriptive strings because the endpoint returns the same value in
8	* its JSON `reason` field. Keeping that classification in a separate property
9	* also prevents an unrelated RuntimeException with a coincidentally equal
10	* native code from being presented as a recoverable protocol condition.
11	*
12	* Only failures which have a deliberate push or commit classification use this
13	* exception. An ordinary RuntimeException remains unclassified and follows the
14	* endpoint's `invalid_request` handling rather than leaking an accidental code.
15	*/
16	final class Site_Export_Push_Exception extends RuntimeException {
17
18	/**
19	* Stable machine-readable classification selected by the throwing class.
20	*
21	* This is distinct from the human-readable exception message. Endpoint
22	* code uses it to select an HTTP status and copies it unchanged into the
23	* authenticated response's `reason` field.
24	*
25	* @var string
26	*/
27	private $error_code;
28
29	/**
30	* Structured observations which describe the failure.
31	*
32	* These values are deliberately separate from the message so commit can
33	* persist non-recoverable failure details and callers can inspect them
34	* without parsing prose. An HTTP endpoint must choose its public fields
35	* explicitly; exception context is not a response schema.
36	*
37	* @var array<string,mixed>
38	*/
39	private $context;
40
41	/**
42	* Creates a push or commit failure with separate machine and human context.
43	*
44	* The machine-readable value comes first so a throw site names its recovery
45	* class before giving instance-specific detail. It is retrieved with
46	* get_error_code(), never Throwable::getCode().
47	*
48	* @param string $error_code Stable machine-readable push or commit reason.
49	* @param string $message Human-readable statement of the violated condition.
50	* @param array<string,mixed> $context Structured observations. Common keys
51	* are operation, path_b64, conflict_path_b64,
52	* expected_docroot_types, observed_docroot_identity, work_device,
53	* docroot_device, work_type, blocking_push_session_id, and
54	* observed_request_body_bytes.
55	*/
56	public function __construct(string $error_code, string $message, array $context = []) {
57	parent::__construct($message);
58	$this->error_code = $error_code;
59	$this->context = $context;
60	}
61
62	/**
63	* Returns the stable reason used to classify this push or commit failure.
64	*
65	* @return string Machine-readable error code suitable for a JSON `reason`.
66	*/
67	public function get_error_code(): string {
68	return $this->error_code;
69	}
70
71	/**
72	* Returns structured observations recorded by the throw site.
73	*
74	* The array contains only values supplied by push or commit throw sites. It
75	* may be empty for simple classified failures, but when present it names
76	* the exact observed condition that made the request non-recoverable or
77	* recoverable.
78	*
79	* @return array<string,mixed> Structured observations. Common keys are
80	* operation, path_b64, conflict_path_b64, expected_docroot_types,
81	* observed_docroot_identity, work_device, docroot_device, work_type,
82	* blocking_push_session_id, and observed_request_body_bytes.
83	*/
84	public function get_context(): array {
85	return $this->context;
86	}
87	}
88