wordpress-seo / src / myyoast-client / domain / resource-indicator.php

resource-indicator.php in Yoast SEO – Advanced SEO with real-time guidance and built-in AI 28.4, at src/myyoast-client/domain/resource-indicator.php

185 lines 6.1 KB

Raw Download Zip

1	<?php
2
3	namespace Yoast\WP\SEO\MyYoast_Client\Domain;
4
5	use Yoast\WP\SEO\MyYoast_Client\Domain\Exceptions\Invalid_Resource_Exception;
6
7	/**
8	* Immutable value object representing an RFC 8707 resource indicator.
9	*
10	* A resource indicator is an absolute URI (RFC 3986 §4.3) without a fragment
11	* that identifies a target resource server. RFC 8707 does not restrict the
12	* scheme — http, https, urn, did, etc. are all valid. The authorization
13	* server decides which specific values it accepts via the OAuth
14	* `invalid_target` error.
15	*
16	* Per the spec's trust model (RFC 8707 §2 and §4), the client is the source
17	* of truth for the canonical form. Every value we put on the wire — including
18	* on refresh — must satisfy §2. The constructor enforces this, and there is
19	* no path that wraps an unvalidated string in this class.
20	*
21	* Null-object pattern: passing null (or calling ::default()) yields an
22	* instance representing "the default resource" — no `resource` parameter
23	* goes on the wire, and storage uses the default bucket. Callers don't
24	* need to null-check; ask is_default() instead.
25	*/
26	class Resource_Indicator {
27
28	/**
29	* RFC 3986 §3.1 scheme: ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ).
30	*
31	* @var string
32	*/
33	private const SCHEME_PATTERN = '[A-Za-z][A-Za-z0-9+.\-]*';
34
35	/**
36	* RFC 3986 character set permitted in the rest of a URI, excluding the
37	* fragment delimiter "#" — RFC 8707 §2 forbids fragments and we reject
38	* them explicitly with a more specific error.
39	*
40	* Includes: unreserved / pct-encoded / sub-delims / ":" / "/" / "?" / "[" / "]" / "@".
41	*
42	* @var string
43	*/
44	private const URI_TAIL_PATTERN = '[A-Za-z0-9\-._~:\/?\[\]@!$&\'()*+,;=%]+';
45
46	/**
47	* The canonical string form, or null when this instance represents the default resource.
48	*
49	* @var string\|null
50	*/
51	private $value;
52
53	/**
54	* Resource_Indicator constructor.
55	*
56	* Null yields the default-resource instance — no validation, no wire
57	* parameter, default storage bucket. Non-null is validated per RFC 8707 §2
58	* (absolute URI per RFC 3986 §4.3, no fragment) and has its trailing slash
59	* canonicalized for storage-key stability.
60	*
61	* @param string\|null $value The resource indicator string, or null for the default resource.
62	*
63	* @throws Invalid_Resource_Exception When the value is non-null but malformed.
64	*/
65	public function __construct( ?string $value ) {
66	if ( $value === null ) {
67	$this->value = null;
68	return;
69	}
70
71	$trimmed = \trim( $value );
72	if ( $trimmed === '' ) {
73	throw new Invalid_Resource_Exception( 'Resource indicator must not be empty.' );
74	}
75
76	// Fragment forbidden by RFC 8707 §2. Checked before the absolute-URI
77	// regex so the caller gets a more specific error message.
78	if ( \strpos( $trimmed, '#' ) !== false ) {
79	throw new Invalid_Resource_Exception( 'Resource indicator must not contain a fragment (RFC 8707 §2).' );
80	}
81
82	// RFC 3986 §4.3 absolute-URI: scheme ":" hier-part [ "?" query ].
83	// We don't deeply validate hier-part — the authorization server will
84	// reject unrecognized formats via OAuth `invalid_target`.
85	//
86	// Anchors are \A (start-of-string) and \z (end-of-string), NOT ^ and $.
87	// ^/$ are line-aware: $ matches before a trailing \n by default, and
88	// with /m both match at every line boundary. That lets a two-line
89	// input smuggle a second URI past the check while still appearing to
90	// "match the whole string". \A and \z always mean literal start/end of
91	// the entire input regardless of newlines or regex flags, which is
92	// what we need when validating untrusted input that goes on the wire.
93	$absolute_uri_pattern = '/\A' . self::SCHEME_PATTERN . ':' . self::URI_TAIL_PATTERN . '\z/';
94	if ( \preg_match( $absolute_uri_pattern, $trimmed ) !== 1 ) {
95	throw new Invalid_Resource_Exception( 'Resource indicator must be an absolute URI (RFC 3986 §4.3, RFC 8707 §2).' );
96	}
97
98	$this->value = self::normalize_trailing_slash( $trimmed );
99	}
100
101	/**
102	* Returns an instance representing the default resource.
103	*
104	* Equivalent to `new Resource_Indicator( null )` — provided for readability
105	* at call sites that want to express the intent explicitly.
106	*
107	* @return self
108	*/
109	public static function default(): self {
110	return new self( null );
111	}
112
113	/**
114	* Returns the canonical string form, or null when this is the default resource.
115	*
116	* @return string\|null
117	*/
118	public function value(): ?string {
119	return $this->value;
120	}
121
122	/**
123	* Whether this instance represents the default resource.
124	*
125	* @return bool
126	*/
127	public function is_default(): bool {
128	return $this->value === null;
129	}
130
131	/**
132	* Returns the canonical string form, or empty string for the default resource.
133	*
134	* @return string
135	*/
136	public function __toString(): string {
137	return ( $this->value ?? '' );
138	}
139
140	/**
141	* Returns true when the other indicator has the same canonical value.
142	*
143	* @param self $other The other indicator.
144	*
145	* @return bool
146	*/
147	public function equals( self $other ): bool {
148	return $this->value === $other->value;
149	}
150
151	/**
152	* Strips a single trailing slash from URIs that have an authority and a
153	* root-only path, so "https://host/" and "https://host" map to the same
154	* canonical form. URIs without an authority (urn:, did:, etc.) are left
155	* alone.
156	*
157	* @param string $uri A validated absolute URI.
158	*
159	* @return string The URI, with the root-path trailing slash trimmed when applicable.
160	*/
161	private static function normalize_trailing_slash( string $uri ): string {
162	if ( \strpos( $uri, '://' ) === false ) {
163	return $uri;
164	}
165
166	$after_authority = \substr( $uri, ( \strpos( $uri, '://' ) + 3 ) );
167	$query_pos = \strpos( $after_authority, '?' );
168	$path_segment = ( $query_pos === false ) ? $after_authority : \substr( $after_authority, 0, $query_pos );
169
170	$slash_pos = \strpos( $path_segment, '/' );
171	if ( $slash_pos === false ) {
172	return $uri;
173	}
174
175	$path = \substr( $path_segment, $slash_pos );
176	if ( $path === '/' ) {
177	$prefix_end = \strpos( $uri, '/', ( \strpos( $uri, '://' ) + 3 ) );
178
179	return \substr( $uri, 0, $prefix_end ) . ( ( $query_pos === false ) ? '' : \substr( $after_authority, $query_pos ) );
180	}
181
182	return $uri;
183	}
184	}
185