SetupResult.php 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-only
  6. */
  7. namespace OCP\SetupCheck;
  8. use OCP\RichObjectStrings\IValidator;
  9. /**
  10. * @brief This class is used for storing the result of a setup check
  11. *
  12. * @since 28.0.0
  13. */
  14. class SetupResult implements \JsonSerializable {
  15. /**
  16. * @since 28.0.0
  17. */
  18. public const SUCCESS = 'success';
  19. /**
  20. * @since 28.0.0
  21. */
  22. public const INFO = 'info';
  23. /**
  24. * @since 28.0.0
  25. */
  26. public const WARNING = 'warning';
  27. /**
  28. * @since 28.0.0
  29. */
  30. public const ERROR = 'error';
  31. /**
  32. * @param string $name Translated name to display to the user
  33. */
  34. private ?string $name = null;
  35. /**
  36. * @brief Private constructor, use success()/info()/warning()/error() instead
  37. * @param self::SUCCESS|self::INFO|self::WARNING|self::ERROR $severity
  38. * @throws \OCP\RichObjectStrings\InvalidObjectExeption
  39. * @since 28.0.0
  40. * @since 28.0.2 Optional parameter ?array $descriptionParameters
  41. * @since 28.0.2 throws \OCP\RichObjectStrings\InvalidObjectExeption
  42. */
  43. private function __construct(
  44. private string $severity,
  45. private ?string $description = null,
  46. private ?array $descriptionParameters = null,
  47. private ?string $linkToDoc = null,
  48. ) {
  49. if ($description !== null && $descriptionParameters !== null) {
  50. \OCP\Server::get(IValidator::class)->validate($description, $descriptionParameters);
  51. }
  52. }
  53. /**
  54. * @brief Create a success result object
  55. * @param ?string $description Translated detailed description to display to the user
  56. * @param ?string $linkToDoc URI of related relevent documentation, be it from Nextcloud or another project
  57. * @throws \OCP\RichObjectStrings\InvalidObjectExeption
  58. * @since 28.0.0
  59. * @since 28.0.2 Optional parameter ?array $descriptionParameters
  60. * @since 28.0.2 throws \OCP\RichObjectStrings\InvalidObjectExeption
  61. */
  62. public static function success(?string $description = null, ?string $linkToDoc = null, ?array $descriptionParameters = null): self {
  63. return new self(self::SUCCESS, $description, $descriptionParameters, $linkToDoc);
  64. }
  65. /**
  66. * @brief Create an info result object
  67. * @param ?string $description Translated detailed description to display to the user
  68. * @param ?string $linkToDoc URI of related relevent documentation, be it from Nextcloud or another project
  69. * @throws \OCP\RichObjectStrings\InvalidObjectExeption
  70. * @since 28.0.0
  71. * @since 28.0.2 Optional parameter ?array $descriptionParameters
  72. * @since 28.0.2 throws \OCP\RichObjectStrings\InvalidObjectExeption
  73. */
  74. public static function info(?string $description = null, ?string $linkToDoc = null, ?array $descriptionParameters = null): self {
  75. return new self(self::INFO, $description, $descriptionParameters, $linkToDoc);
  76. }
  77. /**
  78. * @brief Create a warning result object
  79. * @param ?string $description Translated detailed description to display to the user
  80. * @param ?string $linkToDoc URI of related relevent documentation, be it from Nextcloud or another project
  81. * @throws \OCP\RichObjectStrings\InvalidObjectExeption
  82. * @since 28.0.0
  83. * @since 28.0.2 Optional parameter ?array $descriptionParameters
  84. * @since 28.0.2 throws \OCP\RichObjectStrings\InvalidObjectExeption
  85. */
  86. public static function warning(?string $description = null, ?string $linkToDoc = null, ?array $descriptionParameters = null): self {
  87. return new self(self::WARNING, $description, $descriptionParameters, $linkToDoc);
  88. }
  89. /**
  90. * @brief Create an error result object
  91. * @param ?string $description Translated detailed description to display to the user
  92. * @param ?string $linkToDoc URI of related relevent documentation, be it from Nextcloud or another project
  93. * @throws \OCP\RichObjectStrings\InvalidObjectExeption
  94. * @since 28.0.0
  95. * @since 28.0.2 Optional parameter ?array $descriptionParameters
  96. * @since 28.0.2 throws \OCP\RichObjectStrings\InvalidObjectExeption
  97. */
  98. public static function error(?string $description = null, ?string $linkToDoc = null, ?array $descriptionParameters = null): self {
  99. return new self(self::ERROR, $description, $descriptionParameters, $linkToDoc);
  100. }
  101. /**
  102. * @brief Get the severity for the setup check result
  103. *
  104. * @return self::SUCCESS|self::INFO|self::WARNING|self::ERROR
  105. * @since 28.0.0
  106. */
  107. public function getSeverity(): string {
  108. return $this->severity;
  109. }
  110. /**
  111. * @brief Get the description for the setup check result
  112. *
  113. * @since 28.0.0
  114. */
  115. public function getDescription(): ?string {
  116. return $this->description;
  117. }
  118. /**
  119. * @brief Get the description parameters for the setup check result
  120. *
  121. * If this returns null, description must not be treated as rich text
  122. *
  123. * @since 28.0.2
  124. */
  125. public function getDescriptionParameters(): ?array {
  126. return $this->descriptionParameters;
  127. }
  128. /**
  129. * @brief Get the name for the setup check
  130. *
  131. * @since 28.0.0
  132. */
  133. public function getName(): ?string {
  134. return $this->name;
  135. }
  136. /**
  137. * @brief Set the name from the setup check
  138. *
  139. * @since 28.0.0
  140. */
  141. public function setName(string $name): void {
  142. $this->name = $name;
  143. }
  144. /**
  145. * @brief Get a link to the doc for the explanation.
  146. *
  147. * @since 28.0.0
  148. */
  149. public function getLinkToDoc(): ?string {
  150. return $this->linkToDoc;
  151. }
  152. /**
  153. * @brief Get an array representation of the result for API responses
  154. *
  155. * @since 28.0.0
  156. */
  157. public function jsonSerialize(): array {
  158. return [
  159. 'name' => $this->name,
  160. 'severity' => $this->severity,
  161. 'description' => $this->description,
  162. 'descriptionParameters' => $this->descriptionParameters,
  163. 'linkToDoc' => $this->linkToDoc,
  164. ];
  165. }
  166. }