From 185a24f007dbd4516d44dcf1e30e386b0cd30d3c Mon Sep 17 00:00:00 2001 From: Yuri Kuznetsov Date: Tue, 20 Dec 2022 14:33:06 +0200 Subject: [PATCH] docs --- application/Espo/Core/Exceptions/BadRequest.php | 7 ++++++- application/Espo/Core/Exceptions/Conflict.php | 6 ++++++ application/Espo/Core/Exceptions/Error.php | 6 ++++++ application/Espo/Core/Exceptions/Error/Body.php | 12 ++++++------ application/Espo/Core/Exceptions/Forbidden.php | 11 +++++++---- application/Espo/Core/Exceptions/HasBody.php | 6 ++++++ application/Espo/Core/Exceptions/HasLogLevel.php | 6 ++++++ application/Espo/Core/Exceptions/HasLogMessage.php | 6 ++++++ .../Espo/Core/Exceptions/InternalServerError.php | 4 +--- application/Espo/Core/Exceptions/NotFound.php | 11 +++++++---- .../Espo/Core/Exceptions/ServiceUnavailable.php | 4 +--- application/Espo/Core/Exceptions/Unauthorized.php | 8 ++++---- 12 files changed, 62 insertions(+), 25 deletions(-) diff --git a/application/Espo/Core/Exceptions/BadRequest.php b/application/Espo/Core/Exceptions/BadRequest.php index 17d68f8c16..7da78f093b 100644 --- a/application/Espo/Core/Exceptions/BadRequest.php +++ b/application/Espo/Core/Exceptions/BadRequest.php @@ -32,6 +32,9 @@ namespace Espo\Core\Exceptions; use Throwable; use Exception; +/** + * A bad request exception. Main purpose is for the 400 Bad Request HTTP error. + */ class BadRequest extends Exception implements HasBody { /** @var int */ @@ -43,10 +46,12 @@ class BadRequest extends Exception implements HasBody parent::__construct($message, $code, $previous); } + /** + * Create with a body (supposed to be sent to the frontend). + */ public static function createWithBody(string $reason, string $body): self { $exception = new static($reason); - $exception->body = $body; return $exception; diff --git a/application/Espo/Core/Exceptions/Conflict.php b/application/Espo/Core/Exceptions/Conflict.php index 6be208a8c2..fdec095033 100644 --- a/application/Espo/Core/Exceptions/Conflict.php +++ b/application/Espo/Core/Exceptions/Conflict.php @@ -32,6 +32,9 @@ namespace Espo\Core\Exceptions; use Exception; use Throwable; +/** + * A conflict exception. Main purpose is for the 409 Conflict HTTP error. + */ class Conflict extends Exception implements HasBody { /** @var int */ @@ -43,6 +46,9 @@ class Conflict extends Exception implements HasBody parent::__construct($message, $code, $previous); } + /** + * Create with a body (supposed to be sent to the frontend). + */ public static function createWithBody(string $reason, string $body): self { $exception = new static($reason); diff --git a/application/Espo/Core/Exceptions/Error.php b/application/Espo/Core/Exceptions/Error.php index 17ed853211..50bd61baf3 100644 --- a/application/Espo/Core/Exceptions/Error.php +++ b/application/Espo/Core/Exceptions/Error.php @@ -31,6 +31,9 @@ namespace Espo\Core\Exceptions; use Throwable; +/** + * An exception for 500 Internal Server Error. + */ class Error extends InternalServerError implements HasBody { private ?string $body = null; @@ -40,6 +43,9 @@ class Error extends InternalServerError implements HasBody parent::__construct($message, $code, $previous); } + /** + * Create with a body (supposed to be sent to the frontend). + */ public static function createWithBody(string $message, string $body): self { $exception = new static($message); diff --git a/application/Espo/Core/Exceptions/Error/Body.php b/application/Espo/Core/Exceptions/Error/Body.php index cf8ed96d19..e053cdca2d 100644 --- a/application/Espo/Core/Exceptions/Error/Body.php +++ b/application/Espo/Core/Exceptions/Error/Body.php @@ -31,15 +31,15 @@ namespace Espo\Core\Exceptions\Error; use Espo\Core\Utils\Json; +/** + * A wrapper for error message data for the frontend. Supposed to be passed encoded to `createWithBody` + * methods of exceptions. + */ class Body { private ?string $messageTranslationLabel = null; - private ?string $messageTranslationScope = null; - - /** - * @var ?array - */ + /** @var ?array */ private ?array $messageTranslationData = null; public static function create(): self @@ -50,7 +50,7 @@ class Body /** * A translatable message to display in frontend. Labels should be in the `messages` category. * - * @param ?array $data + * @param ?array $data */ public function withMessageTranslation(string $label, ?string $scope = null, ?array $data = null): self { diff --git a/application/Espo/Core/Exceptions/Forbidden.php b/application/Espo/Core/Exceptions/Forbidden.php index 4cb64f1017..bd70db58f4 100644 --- a/application/Espo/Core/Exceptions/Forbidden.php +++ b/application/Espo/Core/Exceptions/Forbidden.php @@ -32,13 +32,13 @@ namespace Espo\Core\Exceptions; use Throwable; use Exception; +/** + * A forbidden exception. Main purpose is for the 403 Forbidden HTTP error. + */ class Forbidden extends Exception implements HasBody { - /** - * @var int - */ + /** @var int */ protected $code = 403; - private ?string $body = null; final public function __construct(string $message = '', int $code = 0, Throwable $previous = null) @@ -46,6 +46,9 @@ class Forbidden extends Exception implements HasBody parent::__construct($message, $code, $previous); } + /** + * Create with a body (supposed to be sent to the frontend). + */ public static function createWithBody(string $message, string $body): self { $exception = new static($message); diff --git a/application/Espo/Core/Exceptions/HasBody.php b/application/Espo/Core/Exceptions/HasBody.php index be3b940d05..c58ac38684 100644 --- a/application/Espo/Core/Exceptions/HasBody.php +++ b/application/Espo/Core/Exceptions/HasBody.php @@ -29,7 +29,13 @@ namespace Espo\Core\Exceptions; +/** + * Has a body supposed to be sent to the frontend. + */ interface HasBody { + /** + * Get a body (supposed to be sent to the frontend). + */ public function getBody(): ?string; } diff --git a/application/Espo/Core/Exceptions/HasLogLevel.php b/application/Espo/Core/Exceptions/HasLogLevel.php index 9a2da86ef9..4266cf399c 100644 --- a/application/Espo/Core/Exceptions/HasLogLevel.php +++ b/application/Espo/Core/Exceptions/HasLogLevel.php @@ -29,7 +29,13 @@ namespace Espo\Core\Exceptions; +/** + * Has a specific log level (for the logger). + */ interface HasLogLevel { + /** + * Get a log level. + */ public function getLogLevel(): string; } diff --git a/application/Espo/Core/Exceptions/HasLogMessage.php b/application/Espo/Core/Exceptions/HasLogMessage.php index e88f5db214..105fff508e 100644 --- a/application/Espo/Core/Exceptions/HasLogMessage.php +++ b/application/Espo/Core/Exceptions/HasLogMessage.php @@ -29,7 +29,13 @@ namespace Espo\Core\Exceptions; +/** + * Has a log message (for the logger). + */ interface HasLogMessage { + /** + * Get a log message. + */ public function getLogMessage(): string; } diff --git a/application/Espo/Core/Exceptions/InternalServerError.php b/application/Espo/Core/Exceptions/InternalServerError.php index 6b840ab63e..8af967354e 100644 --- a/application/Espo/Core/Exceptions/InternalServerError.php +++ b/application/Espo/Core/Exceptions/InternalServerError.php @@ -31,8 +31,6 @@ namespace Espo\Core\Exceptions; class InternalServerError extends \Exception { - /** - * @var int - */ + /** @var int */ protected $code = 500; } diff --git a/application/Espo/Core/Exceptions/NotFound.php b/application/Espo/Core/Exceptions/NotFound.php index f67210a49d..ce3c749b66 100644 --- a/application/Espo/Core/Exceptions/NotFound.php +++ b/application/Espo/Core/Exceptions/NotFound.php @@ -29,10 +29,13 @@ namespace Espo\Core\Exceptions; -class NotFound extends \Exception +use Exception; + +/** + * A not-found exception. Main purpose is for the 404 Not Found HTTP error. + */ +class NotFound extends Exception { - /** - * @var int - */ + /** @var int */ protected $code = 404; } diff --git a/application/Espo/Core/Exceptions/ServiceUnavailable.php b/application/Espo/Core/Exceptions/ServiceUnavailable.php index 7e1c94c3d2..62a65630fd 100644 --- a/application/Espo/Core/Exceptions/ServiceUnavailable.php +++ b/application/Espo/Core/Exceptions/ServiceUnavailable.php @@ -31,8 +31,6 @@ namespace Espo\Core\Exceptions; class ServiceUnavailable extends \Exception { - /** - * @var int - */ + /** @var int */ protected $code = 503; } diff --git a/application/Espo/Core/Exceptions/Unauthorized.php b/application/Espo/Core/Exceptions/Unauthorized.php index 681ddf48d9..f7258ddd65 100644 --- a/application/Espo/Core/Exceptions/Unauthorized.php +++ b/application/Espo/Core/Exceptions/Unauthorized.php @@ -29,10 +29,10 @@ namespace Espo\Core\Exceptions; -class Unauthorized extends \Exception +use Exception; + +class Unauthorized extends Exception { - /** - * @var int - */ + /** @var int */ protected $code = 401; }