← All changes | vendor/wp-php-toolkit/reprint-server/src/class-push-exception.php +87 -0 16.2-beta → 16.3 View file →

		@@ -1,0 +1,87 @@
	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	+}