[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   8  use WordPress\AiClient\Providers\Enums\ProviderTypeEnum;
   9  use WordPress\AiClient\Providers\Http\Enums\RequestAuthenticationMethod;
  10  /**
  11   * Represents metadata about an AI provider.
  12   *
  13   * This class contains information about an AI provider, including its
  14   * unique identifier, display name, and type (cloud, server, or client).
  15   *
  16   * @since 0.1.0
  17   * @since 1.2.0 Added optional description property.
  18   * @since 1.3.0 Added optional logoPath property.
  19   *
  20   * @phpstan-type ProviderMetadataArrayShape array{
  21   *     id: string,
  22   *     name: string,
  23   *     description?: ?string,
  24   *     type: string,
  25   *     credentialsUrl?: ?string,
  26   *     authenticationMethod?: ?string,
  27   *     logoPath?: ?string
  28   * }
  29   *
  30   * @extends AbstractDataTransferObject<ProviderMetadataArrayShape>
  31   */
  32  class ProviderMetadata extends AbstractDataTransferObject
  33  {
  34      public const KEY_ID = 'id';
  35      public const KEY_NAME = 'name';
  36      public const KEY_DESCRIPTION = 'description';
  37      public const KEY_TYPE = 'type';
  38      public const KEY_CREDENTIALS_URL = 'credentialsUrl';
  39      public const KEY_AUTHENTICATION_METHOD = 'authenticationMethod';
  40      public const KEY_LOGO_PATH = 'logoPath';
  41      /**
  42       * @var string The provider's unique identifier.
  43       */
  44      protected string $id;
  45      /**
  46       * @var string The provider's display name.
  47       */
  48      protected string $name;
  49      /**
  50       * @var string|null The provider's description.
  51       */
  52      protected ?string $description;
  53      /**
  54       * @var ProviderTypeEnum The provider type.
  55       */
  56      protected ProviderTypeEnum $type;
  57      /**
  58       * @var string|null The URL where users can get credentials.
  59       */
  60      protected ?string $credentialsUrl;
  61      /**
  62       * @var RequestAuthenticationMethod|null The authentication method.
  63       */
  64      protected ?RequestAuthenticationMethod $authenticationMethod;
  65      /**
  66       * @var string|null The full path to the provider's logo image file.
  67       */
  68      protected ?string $logoPath;
  69      /**
  70       * Constructor.
  71       *
  72       * @since 0.1.0
  73       * @since 1.2.0 Added optional $description parameter.
  74       * @since 1.3.0 Added optional $logoPath parameter.
  75       *
  76       * @param string $id The provider's unique identifier.
  77       * @param string $name The provider's display name.
  78       * @param ProviderTypeEnum $type The provider type.
  79       * @param string|null $credentialsUrl The URL where users can get credentials.
  80       * @param RequestAuthenticationMethod|null $authenticationMethod The authentication method.
  81       * @param string|null $description The provider's description.
  82       * @param string|null $logoPath The full path to the provider's logo image file.
  83       * @throws InvalidArgumentException If the provider ID contains invalid characters.
  84       */
  85      public function __construct(string $id, string $name, ProviderTypeEnum $type, ?string $credentialsUrl = null, ?RequestAuthenticationMethod $authenticationMethod = null, ?string $description = null, ?string $logoPath = null)
  86      {
  87          if (!preg_match('/^[a-z0-9\-_]+$/', $id)) {
  88              throw new InvalidArgumentException(sprintf(
  89                  // phpcs:ignore Generic.Files.LineLength.TooLong
  90                  'Invalid provider ID "%s". Only lowercase alphanumeric characters, hyphens, and underscores are allowed.',
  91                  $id
  92              ));
  93          }
  94          $this->id = $id;
  95          $this->name = $name;
  96          $this->description = $description;
  97          $this->type = $type;
  98          $this->credentialsUrl = $credentialsUrl;
  99          $this->authenticationMethod = $authenticationMethod;
 100          $this->logoPath = $logoPath;
 101      }
 102      /**
 103       * Gets the provider's unique identifier.
 104       *
 105       * @since 0.1.0
 106       *
 107       * @return string The provider ID.
 108       */
 109      public function getId(): string
 110      {
 111          return $this->id;
 112      }
 113      /**
 114       * Gets the provider's display name.
 115       *
 116       * @since 0.1.0
 117       *
 118       * @return string The provider name.
 119       */
 120      public function getName(): string
 121      {
 122          return $this->name;
 123      }
 124      /**
 125       * Gets the provider's description.
 126       *
 127       * @since 1.2.0
 128       *
 129       * @return string|null The provider description.
 130       */
 131      public function getDescription(): ?string
 132      {
 133          return $this->description;
 134      }
 135      /**
 136       * Gets the provider type.
 137       *
 138       * @since 0.1.0
 139       *
 140       * @return ProviderTypeEnum The provider type.
 141       */
 142      public function getType(): ProviderTypeEnum
 143      {
 144          return $this->type;
 145      }
 146      /**
 147       * Gets the credentials URL.
 148       *
 149       * @since 0.1.0
 150       *
 151       * @return string|null The credentials URL.
 152       */
 153      public function getCredentialsUrl(): ?string
 154      {
 155          return $this->credentialsUrl;
 156      }
 157      /**
 158       * Gets the authentication method.
 159       *
 160       * @since 0.4.0
 161       *
 162       * @return RequestAuthenticationMethod|null The authentication method.
 163       */
 164      public function getAuthenticationMethod(): ?RequestAuthenticationMethod
 165      {
 166          return $this->authenticationMethod;
 167      }
 168      /**
 169       * Gets the full path to the provider's logo image file.
 170       *
 171       * @since 1.3.0
 172       *
 173       * @return string|null The full path to the logo image file.
 174       */
 175      public function getLogoPath(): ?string
 176      {
 177          return $this->logoPath;
 178      }
 179      /**
 180       * {@inheritDoc}
 181       *
 182       * @since 0.1.0
 183       * @since 1.2.0 Added description to schema.
 184       * @since 1.3.0 Added logoPath to schema.
 185       */
 186      public static function getJsonSchema(): array
 187      {
 188          return ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'The provider\'s unique identifier.'], self::KEY_NAME => ['type' => 'string', 'description' => 'The provider\'s display name.'], self::KEY_DESCRIPTION => ['type' => 'string', 'description' => 'The provider\'s description.'], self::KEY_TYPE => ['type' => 'string', 'enum' => ProviderTypeEnum::getValues(), 'description' => 'The provider type (cloud, server, or client).'], self::KEY_CREDENTIALS_URL => ['type' => 'string', 'description' => 'The URL where users can get credentials.'], self::KEY_AUTHENTICATION_METHOD => ['type' => ['string', 'null'], 'enum' => array_merge(RequestAuthenticationMethod::getValues(), [null]), 'description' => 'The authentication method.'], self::KEY_LOGO_PATH => ['type' => 'string', 'description' => 'The full path to the provider\'s logo image file.']], 'required' => [self::KEY_ID, self::KEY_NAME, self::KEY_TYPE]];
 189      }
 190      /**
 191       * {@inheritDoc}
 192       *
 193       * @since 0.1.0
 194       * @since 1.2.0 Added description to output.
 195       * @since 1.3.0 Added logoPath to output.
 196       *
 197       * @return ProviderMetadataArrayShape
 198       */
 199      public function toArray(): array
 200      {
 201          return [self::KEY_ID => $this->id, self::KEY_NAME => $this->name, self::KEY_DESCRIPTION => $this->description, self::KEY_TYPE => $this->type->value, self::KEY_CREDENTIALS_URL => $this->credentialsUrl, self::KEY_AUTHENTICATION_METHOD => $this->authenticationMethod ? $this->authenticationMethod->value : null, self::KEY_LOGO_PATH => $this->logoPath];
 202      }
 203      /**
 204       * {@inheritDoc}
 205       *
 206       * @since 0.1.0
 207       * @since 1.2.0 Added description support.
 208       * @since 1.3.0 Added logoPath support.
 209       */
 210      public static function fromArray(array $array): self
 211      {
 212          static::validateFromArrayData($array, [self::KEY_ID, self::KEY_NAME, self::KEY_TYPE]);
 213          return new self($array[self::KEY_ID], $array[self::KEY_NAME], ProviderTypeEnum::from($array[self::KEY_TYPE]), $array[self::KEY_CREDENTIALS_URL] ?? null, isset($array[self::KEY_AUTHENTICATION_METHOD]) ? RequestAuthenticationMethod::from($array[self::KEY_AUTHENTICATION_METHOD]) : null, $array[self::KEY_DESCRIPTION] ?? null, $array[self::KEY_LOGO_PATH] ?? null);
 214      }
 215  }