From a5d8769176fc0f20b8abf4dd2754959a35c64910 Mon Sep 17 00:00:00 2001
From: Mohammad Alavi <mohammad.alavi1990@gmail.com>
Date: Fri, 8 Apr 2022 18:34:27 +0430
Subject: [PATCH] refactor: update php docblocks

---
 .../Actions/ApiLoginProxyForWebClientAction.php            | 4 ++++
 .../Actions/ApiRefreshProxyForWebClientAction.php          | 6 +++++-
 .../Authentication/Actions/ForgotPasswordAction.php        | 6 ++++++
 .../Authentication/Actions/RegisterUserAction.php          | 4 ++++
 .../Authentication/Actions/ResetPasswordAction.php         | 6 +++++-
 .../AppSection/Authentication/Actions/WebLoginAction.php   | 4 ++++
 .../UI/API/Controllers/ForgotPasswordController.php        | 6 ++++--
 .../API/Controllers/LoginProxyForWebClientController.php   | 3 ++-
 .../API/Controllers/RefreshProxyForWebClientController.php | 7 ++++++-
 .../UI/API/Controllers/RegisterUserController.php          | 6 +++++-
 .../UI/API/Controllers/ResetPasswordController.php         | 4 ++++
 .../UI/API/Controllers/SendVerificationEmailController.php | 4 ++--
 .../AppSection/Authorization/Actions/DeleteRoleAction.php  | 3 +++
 .../Actions/GiveAllPermissionsToRoleAction.php             | 6 ++++++
 .../UI/API/Controllers/DeleteRoleController.php            | 4 ++++
 .../AppSection/User/Actions/UpdateUserAction.php           | 7 ++++++-
 .../User/UI/API/Controllers/UpdateUserController.php       | 6 +++++-
 17 files changed, 75 insertions(+), 11 deletions(-)

diff --git a/app/Containers/AppSection/Authentication/Actions/ApiLoginProxyForWebClientAction.php b/app/Containers/AppSection/Authentication/Actions/ApiLoginProxyForWebClientAction.php
index 9cce9fe57..4ef42efae 100644
--- a/app/Containers/AppSection/Authentication/Actions/ApiLoginProxyForWebClientAction.php
+++ b/app/Containers/AppSection/Authentication/Actions/ApiLoginProxyForWebClientAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Exceptions\LoginFailedException;
 use App\Containers\AppSection\Authentication\Tasks\CallOAuthServerTask;
 use App\Containers\AppSection\Authentication\Tasks\ExtractLoginCustomAttributeTask;
@@ -12,7 +13,10 @@
 class ApiLoginProxyForWebClientAction extends Action
 {
     /**
+     * @param LoginProxyPasswordGrantRequest $request
+     * @return array
      * @throws LoginFailedException
+     * @throws IncorrectIdException
      */
     public function run(LoginProxyPasswordGrantRequest $request): array
     {
diff --git a/app/Containers/AppSection/Authentication/Actions/ApiRefreshProxyForWebClientAction.php b/app/Containers/AppSection/Authentication/Actions/ApiRefreshProxyForWebClientAction.php
index f69bfd331..faecaccfe 100644
--- a/app/Containers/AppSection/Authentication/Actions/ApiRefreshProxyForWebClientAction.php
+++ b/app/Containers/AppSection/Authentication/Actions/ApiRefreshProxyForWebClientAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Exceptions\LoginFailedException;
 use App\Containers\AppSection\Authentication\Exceptions\RefreshTokenMissedException;
 use App\Containers\AppSection\Authentication\Tasks\CallOAuthServerTask;
@@ -13,8 +14,11 @@
 class ApiRefreshProxyForWebClientAction extends Action
 {
     /**
-     * @throws RefreshTokenMissedException
+     * @param RefreshProxyRequest $request
+     * @return array
      * @throws LoginFailedException
+     * @throws RefreshTokenMissedException
+     * @throws IncorrectIdException
      */
     public function run(RefreshProxyRequest $request): array
     {
diff --git a/app/Containers/AppSection/Authentication/Actions/ForgotPasswordAction.php b/app/Containers/AppSection/Authentication/Actions/ForgotPasswordAction.php
index 0195272fb..a53ef8fbc 100644
--- a/app/Containers/AppSection/Authentication/Actions/ForgotPasswordAction.php
+++ b/app/Containers/AppSection/Authentication/Actions/ForgotPasswordAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Mails\ForgotPassword;
 use App\Containers\AppSection\Authentication\Tasks\CreatePasswordResetTokenTask;
 use App\Containers\AppSection\Authentication\UI\API\Requests\ForgotPasswordRequest;
@@ -12,6 +13,11 @@
 
 class ForgotPasswordAction extends Action
 {
+    /**
+     * @param ForgotPasswordRequest $request
+     * @return bool
+     * @throws IncorrectIdException
+     */
     public function run(ForgotPasswordRequest $request): bool
     {
         $sanitizedData = $request->sanitizeInput([
diff --git a/app/Containers/AppSection/Authentication/Actions/RegisterUserAction.php b/app/Containers/AppSection/Authentication/Actions/RegisterUserAction.php
index 4a119e1a0..9685d6037 100644
--- a/app/Containers/AppSection/Authentication/Actions/RegisterUserAction.php
+++ b/app/Containers/AppSection/Authentication/Actions/RegisterUserAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Notifications\Welcome;
 use App\Containers\AppSection\Authentication\Tasks\CreateUserByCredentialsTask;
 use App\Containers\AppSection\Authentication\Tasks\SendVerificationEmailTask;
@@ -13,7 +14,10 @@
 class RegisterUserAction extends Action
 {
     /**
+     * @param RegisterUserRequest $request
+     * @return User
      * @throws CreateResourceFailedException
+     * @throws IncorrectIdException
      */
     public function run(RegisterUserRequest $request): User
     {
diff --git a/app/Containers/AppSection/Authentication/Actions/ResetPasswordAction.php b/app/Containers/AppSection/Authentication/Actions/ResetPasswordAction.php
index e026b64a7..66a801b6f 100644
--- a/app/Containers/AppSection/Authentication/Actions/ResetPasswordAction.php
+++ b/app/Containers/AppSection/Authentication/Actions/ResetPasswordAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Exceptions\InvalidResetPasswordTokenException;
 use App\Containers\AppSection\Authentication\Notifications\PasswordReset;
 use App\Containers\AppSection\Authentication\UI\API\Requests\ResetPasswordRequest;
@@ -16,9 +17,12 @@
 class ResetPasswordAction extends Action
 {
     /**
-     * @throws NotFoundException
+     * @param ResetPasswordRequest $request
+     * @return mixed
      * @throws InvalidResetPasswordTokenException
+     * @throws NotFoundException
      * @throws UpdateResourceFailedException
+     * @throws IncorrectIdException
      */
     public function run(ResetPasswordRequest $request): mixed
     {
diff --git a/app/Containers/AppSection/Authentication/Actions/WebLoginAction.php b/app/Containers/AppSection/Authentication/Actions/WebLoginAction.php
index 46143f2b2..5ffdc41ac 100644
--- a/app/Containers/AppSection/Authentication/Actions/WebLoginAction.php
+++ b/app/Containers/AppSection/Authentication/Actions/WebLoginAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Exceptions\LoginFailedException;
 use App\Containers\AppSection\Authentication\Tasks\ExtractLoginCustomAttributeTask;
 use App\Containers\AppSection\Authentication\Tasks\LoginTask;
@@ -14,7 +15,10 @@
 class WebLoginAction extends Action
 {
     /**
+     * @param LoginRequest $request
+     * @return User|Authenticatable|null
      * @throws LoginFailedException
+     * @throws IncorrectIdException
      */
     public function run(LoginRequest $request): User|Authenticatable|null
     {
diff --git a/app/Containers/AppSection/Authentication/UI/API/Controllers/ForgotPasswordController.php b/app/Containers/AppSection/Authentication/UI/API/Controllers/ForgotPasswordController.php
index e2b38838a..48d9e7655 100644
--- a/app/Containers/AppSection/Authentication/UI/API/Controllers/ForgotPasswordController.php
+++ b/app/Containers/AppSection/Authentication/UI/API/Controllers/ForgotPasswordController.php
@@ -2,16 +2,18 @@
 
 namespace App\Containers\AppSection\Authentication\UI\API\Controllers;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Actions\ForgotPasswordAction;
 use App\Containers\AppSection\Authentication\UI\API\Requests\ForgotPasswordRequest;
-use App\Ship\Exceptions\NotFoundException;
 use App\Ship\Parents\Controllers\ApiController;
 use Illuminate\Http\JsonResponse;
 
 class ForgotPasswordController extends ApiController
 {
     /**
-     * @throws NotFoundException
+     * @param ForgotPasswordRequest $request
+     * @return JsonResponse
+     * @throws IncorrectIdException
      */
     public function forgotPassword(ForgotPasswordRequest $request): JsonResponse
     {
diff --git a/app/Containers/AppSection/Authentication/UI/API/Controllers/LoginProxyForWebClientController.php b/app/Containers/AppSection/Authentication/UI/API/Controllers/LoginProxyForWebClientController.php
index 49fd47da6..01f3d486c 100644
--- a/app/Containers/AppSection/Authentication/UI/API/Controllers/LoginProxyForWebClientController.php
+++ b/app/Containers/AppSection/Authentication/UI/API/Controllers/LoginProxyForWebClientController.php
@@ -2,9 +2,9 @@
 
 namespace App\Containers\AppSection\Authentication\UI\API\Controllers;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Actions\ApiLoginProxyForWebClientAction;
 use App\Containers\AppSection\Authentication\Exceptions\LoginFailedException;
-use App\Containers\AppSection\Authentication\Exceptions\EmailNotVerifiedException;
 use App\Containers\AppSection\Authentication\UI\API\Requests\LoginProxyPasswordGrantRequest;
 use App\Ship\Parents\Controllers\ApiController;
 use Illuminate\Http\JsonResponse;
@@ -22,6 +22,7 @@ class LoginProxyForWebClientController extends ApiController
      * @param LoginProxyPasswordGrantRequest $request
      * @return JsonResponse
      * @throws LoginFailedException
+     * @throws IncorrectIdException
      */
     public function loginProxyForWebClient(LoginProxyPasswordGrantRequest $request): JsonResponse
     {
diff --git a/app/Containers/AppSection/Authentication/UI/API/Controllers/RefreshProxyForWebClientController.php b/app/Containers/AppSection/Authentication/UI/API/Controllers/RefreshProxyForWebClientController.php
index e3b9c0ffb..a2fd0ed7c 100644
--- a/app/Containers/AppSection/Authentication/UI/API/Controllers/RefreshProxyForWebClientController.php
+++ b/app/Containers/AppSection/Authentication/UI/API/Controllers/RefreshProxyForWebClientController.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\UI\API\Controllers;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Actions\ApiRefreshProxyForWebClientAction;
 use App\Containers\AppSection\Authentication\Exceptions\LoginFailedException;
 use App\Containers\AppSection\Authentication\Exceptions\RefreshTokenMissedException;
@@ -19,7 +20,11 @@ class RefreshProxyForWebClientController extends ApiController
      * This is only to help the Web Apps (JavaScript clients) hide
      * their ID's and Secrets when contacting the OAuth server and obtain Tokens.
      *
-     * @throws RefreshTokenMissedException|LoginFailedException
+     * @param RefreshProxyRequest $request
+     * @return JsonResponse
+     * @throws LoginFailedException
+     * @throws RefreshTokenMissedException
+     * @throws IncorrectIdException
      */
     public function refreshProxyForWebClient(RefreshProxyRequest $request): JsonResponse
     {
diff --git a/app/Containers/AppSection/Authentication/UI/API/Controllers/RegisterUserController.php b/app/Containers/AppSection/Authentication/UI/API/Controllers/RegisterUserController.php
index 847d65687..88de4a905 100644
--- a/app/Containers/AppSection/Authentication/UI/API/Controllers/RegisterUserController.php
+++ b/app/Containers/AppSection/Authentication/UI/API/Controllers/RegisterUserController.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\UI\API\Controllers;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use Apiato\Core\Exceptions\InvalidTransformerException;
 use App\Containers\AppSection\Authentication\Actions\RegisterUserAction;
 use App\Containers\AppSection\Authentication\UI\API\Requests\RegisterUserRequest;
@@ -12,8 +13,11 @@
 class RegisterUserController extends ApiController
 {
     /**
-     * @throws InvalidTransformerException
+     * @param RegisterUserRequest $request
+     * @return array
      * @throws CreateResourceFailedException
+     * @throws InvalidTransformerException
+     * @throws IncorrectIdException
      */
     public function registerUser(RegisterUserRequest $request): array
     {
diff --git a/app/Containers/AppSection/Authentication/UI/API/Controllers/ResetPasswordController.php b/app/Containers/AppSection/Authentication/UI/API/Controllers/ResetPasswordController.php
index b356b4a62..35ea92bb6 100644
--- a/app/Containers/AppSection/Authentication/UI/API/Controllers/ResetPasswordController.php
+++ b/app/Containers/AppSection/Authentication/UI/API/Controllers/ResetPasswordController.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\Authentication\UI\API\Controllers;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\Authentication\Actions\ResetPasswordAction;
 use App\Containers\AppSection\Authentication\Exceptions\InvalidResetPasswordTokenException;
 use App\Containers\AppSection\Authentication\UI\API\Requests\ResetPasswordRequest;
@@ -13,9 +14,12 @@
 class ResetPasswordController extends ApiController
 {
     /**
+     * @param ResetPasswordRequest $request
+     * @return JsonResponse
      * @throws InvalidResetPasswordTokenException
      * @throws NotFoundException
      * @throws UpdateResourceFailedException
+     * @throws IncorrectIdException
      */
     public function resetPassword(ResetPasswordRequest $request): JsonResponse
     {
diff --git a/app/Containers/AppSection/Authentication/UI/API/Controllers/SendVerificationEmailController.php b/app/Containers/AppSection/Authentication/UI/API/Controllers/SendVerificationEmailController.php
index dd9cc18cb..34ecf721c 100644
--- a/app/Containers/AppSection/Authentication/UI/API/Controllers/SendVerificationEmailController.php
+++ b/app/Containers/AppSection/Authentication/UI/API/Controllers/SendVerificationEmailController.php
@@ -4,14 +4,14 @@
 
 use App\Containers\AppSection\Authentication\Actions\SendVerificationEmailAction;
 use App\Containers\AppSection\Authentication\UI\API\Requests\SendVerificationEmailRequest;
-use App\Ship\Exceptions\NotFoundException;
 use App\Ship\Parents\Controllers\ApiController;
 use Illuminate\Http\JsonResponse;
 
 class SendVerificationEmailController extends ApiController
 {
     /**
-     * @throws NotFoundException
+     * @param SendVerificationEmailRequest $request
+     * @return JsonResponse
      */
     public function sendVerificationEmail(SendVerificationEmailRequest $request): JsonResponse
     {
diff --git a/app/Containers/AppSection/Authorization/Actions/DeleteRoleAction.php b/app/Containers/AppSection/Authorization/Actions/DeleteRoleAction.php
index 40814e863..3e8e0f599 100644
--- a/app/Containers/AppSection/Authorization/Actions/DeleteRoleAction.php
+++ b/app/Containers/AppSection/Authorization/Actions/DeleteRoleAction.php
@@ -5,12 +5,15 @@
 use App\Containers\AppSection\Authorization\Tasks\DeleteRoleTask;
 use App\Containers\AppSection\Authorization\UI\API\Requests\DeleteRoleRequest;
 use App\Ship\Exceptions\DeleteResourceFailedException;
+use App\Ship\Exceptions\NotFoundException;
 use App\Ship\Parents\Actions\Action;
 
 class DeleteRoleAction extends Action
 {
     /**
+     * @param DeleteRoleRequest $request
      * @throws DeleteResourceFailedException
+     * @throws NotFoundException
      */
     public function run(DeleteRoleRequest $request): void
     {
diff --git a/app/Containers/AppSection/Authorization/Actions/GiveAllPermissionsToRoleAction.php b/app/Containers/AppSection/Authorization/Actions/GiveAllPermissionsToRoleAction.php
index b7a820cfb..bc1f865d6 100644
--- a/app/Containers/AppSection/Authorization/Actions/GiveAllPermissionsToRoleAction.php
+++ b/app/Containers/AppSection/Authorization/Actions/GiveAllPermissionsToRoleAction.php
@@ -2,15 +2,21 @@
 
 namespace App\Containers\AppSection\Authorization\Actions;
 
+use Apiato\Core\Exceptions\CoreInternalErrorException;
 use App\Containers\AppSection\Authorization\Tasks\FindRoleTask;
 use App\Containers\AppSection\Authorization\Tasks\GetAllPermissionsTask;
 use App\Ship\Exceptions\NotFoundException;
 use App\Ship\Parents\Actions\Action;
+use Prettus\Repository\Exceptions\RepositoryException;
 
 class GiveAllPermissionsToRoleAction extends Action
 {
     /**
+     * @param string $roleName
+     * @return array
      * @throws NotFoundException
+     * @throws CoreInternalErrorException
+     * @throws RepositoryException
      */
     public function run(string $roleName): array
     {
diff --git a/app/Containers/AppSection/Authorization/UI/API/Controllers/DeleteRoleController.php b/app/Containers/AppSection/Authorization/UI/API/Controllers/DeleteRoleController.php
index b418dcb28..468f5f48b 100644
--- a/app/Containers/AppSection/Authorization/UI/API/Controllers/DeleteRoleController.php
+++ b/app/Containers/AppSection/Authorization/UI/API/Controllers/DeleteRoleController.php
@@ -5,13 +5,17 @@
 use App\Containers\AppSection\Authorization\Actions\DeleteRoleAction;
 use App\Containers\AppSection\Authorization\UI\API\Requests\DeleteRoleRequest;
 use App\Ship\Exceptions\DeleteResourceFailedException;
+use App\Ship\Exceptions\NotFoundException;
 use App\Ship\Parents\Controllers\ApiController;
 use Illuminate\Http\JsonResponse;
 
 class DeleteRoleController extends ApiController
 {
     /**
+     * @param DeleteRoleRequest $request
+     * @return JsonResponse
      * @throws DeleteResourceFailedException
+     * @throws NotFoundException
      */
     public function deleteRole(DeleteRoleRequest $request): JsonResponse
     {
diff --git a/app/Containers/AppSection/User/Actions/UpdateUserAction.php b/app/Containers/AppSection/User/Actions/UpdateUserAction.php
index a24b27a62..0544554cb 100644
--- a/app/Containers/AppSection/User/Actions/UpdateUserAction.php
+++ b/app/Containers/AppSection/User/Actions/UpdateUserAction.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\User\Actions;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use App\Containers\AppSection\User\Models\User;
 use App\Containers\AppSection\User\Tasks\UpdateUserTask;
 use App\Containers\AppSection\User\UI\API\Requests\UpdateUserRequest;
@@ -12,7 +13,11 @@
 class UpdateUserAction extends Action
 {
     /**
-     * @throws UpdateResourceFailedException|NotFoundException
+     * @param UpdateUserRequest $request
+     * @return User
+     * @throws NotFoundException
+     * @throws UpdateResourceFailedException
+     * @throws IncorrectIdException
      */
     public function run(UpdateUserRequest $request): User
     {
diff --git a/app/Containers/AppSection/User/UI/API/Controllers/UpdateUserController.php b/app/Containers/AppSection/User/UI/API/Controllers/UpdateUserController.php
index 8ec026632..76f865f21 100644
--- a/app/Containers/AppSection/User/UI/API/Controllers/UpdateUserController.php
+++ b/app/Containers/AppSection/User/UI/API/Controllers/UpdateUserController.php
@@ -2,6 +2,7 @@
 
 namespace App\Containers\AppSection\User\UI\API\Controllers;
 
+use Apiato\Core\Exceptions\IncorrectIdException;
 use Apiato\Core\Exceptions\InvalidTransformerException;
 use App\Containers\AppSection\User\Actions\UpdateUserAction;
 use App\Containers\AppSection\User\UI\API\Requests\UpdateUserRequest;
@@ -13,9 +14,12 @@
 class UpdateUserController extends ApiController
 {
     /**
-     * @throws UpdateResourceFailedException
+     * @param UpdateUserRequest $request
+     * @return array
      * @throws InvalidTransformerException
      * @throws NotFoundException
+     * @throws UpdateResourceFailedException
+     * @throws IncorrectIdException
      */
     public function updateUser(UpdateUserRequest $request): array
     {