|
| 1 | +<?php |
| 2 | + |
| 3 | +declare(strict_types=1); |
| 4 | + |
| 5 | +namespace PhpMcp\Schema; |
| 6 | + |
| 7 | +use PhpMcp\Schema\Enum\Role; |
| 8 | +use JsonSerializable; |
| 9 | + |
| 10 | +/** |
| 11 | + * Optional annotations for the client. The client can use annotations |
| 12 | + * to inform how objects are used or displayed. |
| 13 | + */ |
| 14 | +class Annotations implements JsonSerializable |
| 15 | +{ |
| 16 | + /** |
| 17 | + * @param Role[]|null $audience Describes who the intended customer of this object or data is. |
| 18 | + * |
| 19 | + * It can include multiple entries to indicate content useful for multiple audiences (e.g., `[Role::User, Role::Assistant]`). |
| 20 | + * |
| 21 | + * @param float|null $priority Describes how important this data is for operating the server. |
| 22 | + * |
| 23 | + * A value of 1 means "most important," and indicates that the data is |
| 24 | + * effectively required, while 0 means "least important," and indicates that |
| 25 | + * the data is entirely optional. |
| 26 | + */ |
| 27 | + public function __construct( |
| 28 | + public readonly ?array $audience = null, |
| 29 | + public readonly ?float $priority = null |
| 30 | + ) { |
| 31 | + if ($this->priority !== null && ($this->priority < 0 || $this->priority > 1)) { |
| 32 | + throw new \InvalidArgumentException("Annotation priority must be between 0 and 1."); |
| 33 | + } |
| 34 | + if ($this->audience !== null) { |
| 35 | + foreach ($this->audience as $role) { |
| 36 | + if (!($role instanceof Role)) { |
| 37 | + throw new \InvalidArgumentException("All audience members must be instances of Role enum."); |
| 38 | + } |
| 39 | + } |
| 40 | + } |
| 41 | + } |
| 42 | + |
| 43 | + /** |
| 44 | + * @param Role[]|null $audience Describes who the intended customer of this object or data is. |
| 45 | + * |
| 46 | + * It can include multiple entries to indicate content useful for multiple audiences (e.g., `[Role::User, Role::Assistant]`). |
| 47 | + * |
| 48 | + * @param float|null $priority Describes how important this data is for operating the server. |
| 49 | + * |
| 50 | + * A value of 1 means "most important," and indicates that the data is |
| 51 | + * effectively required, while 0 means "least important," and indicates that |
| 52 | + * the data is entirely optional. |
| 53 | + */ |
| 54 | + public static function make(array $audience = null, float $priority = null): static |
| 55 | + { |
| 56 | + return new static($audience, $priority); |
| 57 | + } |
| 58 | + |
| 59 | + public function toArray(): array |
| 60 | + { |
| 61 | + $data = []; |
| 62 | + if ($this->audience !== null) { |
| 63 | + $data['audience'] = array_map(fn (Role $r) => $r->value, $this->audience); |
| 64 | + } |
| 65 | + if ($this->priority !== null) { |
| 66 | + $data['priority'] = $this->priority; |
| 67 | + } |
| 68 | + return $data; |
| 69 | + } |
| 70 | + |
| 71 | + public static function fromArray(array $data): static |
| 72 | + { |
| 73 | + $audience = null; |
| 74 | + if (isset($data['audience']) && is_array($data['audience'])) { |
| 75 | + $audience = array_map(fn (string $r) => Role::from($r), $data['audience']); |
| 76 | + } |
| 77 | + return new static( |
| 78 | + $audience, |
| 79 | + isset($data['priority']) ? (float)$data['priority'] : null |
| 80 | + ); |
| 81 | + } |
| 82 | + |
| 83 | + public function jsonSerialize(): array |
| 84 | + { |
| 85 | + return $this->toArray(); |
| 86 | + } |
| 87 | +} |
0 commit comments