zip-ai / lib / php-mcp-schema / src / Server / Resources / DTO / ResourceTemplate.php

ResourceTemplate.php in ZIP AI – AI Website Builder & AI Agent (Beta) 0.0.8, at lib/php-mcp-schema/src/Server/Resources/DTO/ResourceTemplate.php

245 lines 7.0 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace WP\McpSchema\Server\Resources\DTO;
6
7	use WP\McpSchema\Common\Core\DTO\Icon;
8	use WP\McpSchema\Common\Protocol\DTO\Annotations;
9	use WP\McpSchema\Common\Protocol\DTO\BaseMetadata;
10	use WP\McpSchema\Common\Traits\ValidatesRequiredFields;
11
12	/**
13	* A template description for resources available on the server.
14	*
15	* @since 2024-11-05
16	* @last-updated 2025-11-25 (added properties: icons; modified property: annotations)
17	*
18	* @mcp-domain Server
19	* @mcp-subdomain Resources
20	* @mcp-version 2025-11-25
21	*/
22	class ResourceTemplate extends BaseMetadata
23	{
24	use ValidatesRequiredFields;
25
26	/**
27	* A URI template (according to RFC 6570) that can be used to construct resource URIs.
28	*
29	* @since 2024-11-05
30	*
31	* @var string
32	*/
33	protected string $uriTemplate;
34
35	/**
36	* A description of what this template is for.
37	*
38	* This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model.
39	*
40	* @since 2024-11-05
41	*
42	* @var string\|null
43	*/
44	protected ?string $description;
45
46	/**
47	* The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type.
48	*
49	* @since 2024-11-05
50	*
51	* @var string\|null
52	*/
53	protected ?string $mimeType;
54
55	/**
56	* Optional annotations for the client.
57	*
58	* @since 2024-11-05
59	*
60	* @var \WP\McpSchema\Common\Protocol\DTO\Annotations\|null
61	*/
62	protected ?Annotations $annotations;
63
64	/**
65	* See [General fields: `_meta`](/specification/2025-11-25/basic/index#meta) for notes on `_meta` usage.
66	*
67	* @since 2025-06-18
68	*
69	* @var array<string, mixed>\|null
70	*/
71	protected ?array $_meta;
72
73	/**
74	* Optional set of sized icons that the client can display in a user interface.
75	*
76	* Clients that support rendering icons MUST support at least the following MIME types:
77	* - `image/png` - PNG images (safe, universal compatibility)
78	* - `image/jpeg` (and `image/jpg`) - JPEG images (safe, universal compatibility)
79	*
80	* Clients that support rendering icons SHOULD also support:
81	* - `image/svg+xml` - SVG images (scalable but requires security precautions)
82	* - `image/webp` - WebP images (modern, efficient format)
83	*
84	* @since 2025-11-25
85	*
86	* @var array<\WP\McpSchema\Common\Core\DTO\Icon>\|null
87	*/
88	protected ?array $icons;
89
90	/**
91	* @param string $name @since 2024-11-05
92	* @param string $uriTemplate @since 2024-11-05
93	* @param string\|null $title @since 2025-06-18
94	* @param string\|null $description @since 2024-11-05
95	* @param string\|null $mimeType @since 2024-11-05
96	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations @since 2024-11-05
97	* @param array<string, mixed>\|null $_meta @since 2025-06-18
98	* @param array<\WP\McpSchema\Common\Core\DTO\Icon>\|null $icons @since 2025-11-25
99	*/
100	public function __construct(
101	string $name,
102	string $uriTemplate,
103	?string $title = null,
104	?string $description = null,
105	?string $mimeType = null,
106	?Annotations $annotations = null,
107	?array $_meta = null,
108	?array $icons = null
109	) {
110	parent::__construct($name, $title);
111	$this->uriTemplate = $uriTemplate;
112	$this->description = $description;
113	$this->mimeType = $mimeType;
114	$this->annotations = $annotations;
115	$this->_meta = $_meta;
116	$this->icons = $icons;
117	}
118
119	/**
120	* Creates an instance from an array.
121	*
122	* @param array{
123	* name: string,
124	* title?: string\|null,
125	* uriTemplate: string,
126	* description?: string\|null,
127	* mimeType?: string\|null,
128	* annotations?: array<string, mixed>\|\WP\McpSchema\Common\Protocol\DTO\Annotations\|null,
129	* _meta?: array<string, mixed>\|null,
130	* icons?: array<array<string, mixed>\|\WP\McpSchema\Common\Core\DTO\Icon>\|null
131	* } $data
132	* @phpstan-param array<string, mixed> $data
133	* @return self
134	*/
135	public static function fromArray(array $data): self
136	{
137	self::assertRequired($data, ['name', 'uriTemplate']);
138
139	/** @var \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations */
140	$annotations = isset($data['annotations'])
141	? (is_array($data['annotations'])
142	? Annotations::fromArray(self::asArray($data['annotations']))
143	: $data['annotations'])
144	: null;
145
146	/** @var array<\WP\McpSchema\Common\Core\DTO\Icon>\|null $icons */
147	$icons = isset($data['icons'])
148	? array_map(
149	static fn($item) => is_array($item)
150	? Icon::fromArray($item)
151	: $item,
152	self::asArray($data['icons'])
153	)
154	: null;
155
156	return new self(
157	self::asString($data['name']),
158	self::asString($data['uriTemplate']),
159	self::asStringOrNull($data['title'] ?? null),
160	self::asStringOrNull($data['description'] ?? null),
161	self::asStringOrNull($data['mimeType'] ?? null),
162	$annotations,
163	self::asArrayOrNull($data['_meta'] ?? null),
164	$icons
165	);
166	}
167
168	/**
169	* Converts the instance to an array.
170	*
171	* @return array<string, mixed>
172	*/
173	public function toArray(): array
174	{
175	$result = parent::toArray();
176
177	$result['uriTemplate'] = $this->uriTemplate;
178	if ($this->description !== null) {
179	$result['description'] = $this->description;
180	}
181	if ($this->mimeType !== null) {
182	$result['mimeType'] = $this->mimeType;
183	}
184	if ($this->annotations !== null) {
185	$result['annotations'] = $this->annotations->toArray();
186	}
187	if ($this->_meta !== null) {
188	$result['_meta'] = $this->_meta;
189	}
190	if ($this->icons !== null) {
191	$result['icons'] = array_map(static fn($item) => $item->toArray(), $this->icons);
192	}
193
194	return $result;
195	}
196
197	/**
198	* @return string
199	*/
200	public function getUriTemplate(): string
201	{
202	return $this->uriTemplate;
203	}
204
205	/**
206	* @return string\|null
207	*/
208	public function getDescription(): ?string
209	{
210	return $this->description;
211	}
212
213	/**
214	* @return string\|null
215	*/
216	public function getMimeType(): ?string
217	{
218	return $this->mimeType;
219	}
220
221	/**
222	* @return \WP\McpSchema\Common\Protocol\DTO\Annotations\|null
223	*/
224	public function getAnnotations(): ?Annotations
225	{
226	return $this->annotations;
227	}
228
229	/**
230	* @return array<string, mixed>\|null
231	*/
232	public function get_meta(): ?array
233	{
234	return $this->_meta;
235	}
236
237	/**
238	* @return array<\WP\McpSchema\Common\Core\DTO\Icon>\|null
239	*/
240	public function getIcons(): ?array
241	{
242	return $this->icons;
243	}
244	}
245