checkAccess, checkUpdateAllowed, checkDeleteAllowed - description

Author: siggi-k

src/actions/DeleteAction.php

@@ -38,10 +38,25 @@ class DeleteAction extends JsonApiAction
     public $scenario = Model::SCENARIO_DEFAULT;
 
     /**
-     * @var callable|null a PHP callable that checks if deletion is allowed.
+     * @var callable|null A PHP callable that will be called to determine
+     * whether the deletion of a model is allowed. If not set, no deletion
+     * check will be performed. The callable should have the following signature:
+     *
+     * @example
+     * ```php
+     * function ($action, $model) {
+     *     // $model is the model instance being deleted.
+     *
+     *     // If the deletion is not allowed, an error should be thrown. For example:
+     *     if ($model->status !== 'draft') {
+     *         throw new MethodNotAllowedHttpException('The model can only be deleted if its status is "draft".');
+     *     }
+     * }
+     * ```
      */
     public $checkDeleteAllowed;
 
+
     /**
      * @var callable|Closure Callback after save model with all relations
      * @example

src/actions/JsonApiAction.php

@@ -61,13 +61,20 @@ class JsonApiAction extends Action
     public $findModel;
 
     /**
-     * @var callable a PHP callable that will be called when running an action to determine
-     * if the current user has the permission to execute the action. If not set, the access
-     * check will not be performed. The signature of the callable should be as follows,
+     * @var callable A PHP callable that will be called when running an action to determine
+     * whether the current user has permission to execute the action. If not set, no access
+     * check will be performed. The callable should have the following signature:
+     *
+     * @example
      * ```php
      * function ($action, $model = null) {
      *     // $model is the requested model instance.
-     *     // If null, it means no specific model (e.g. IndexAction)
+     *     // If null, it indicates no specific model (e.g., IndexAction).
+     *
+     *     // If the user does not have the required permissions, an error should be thrown. For example:
+     *     if (!Yii::$app->user->can('admin')) {
+     *         throw new ForbiddenHttpException();
+     *     }
      * }
      * ```
      */

src/actions/UpdateAction.php

@@ -68,7 +68,21 @@ class UpdateAction extends JsonApiAction
     public $scenario = Model::SCENARIO_DEFAULT;
 
     /**
-     * @var callable|null a PHP callable that checks if updating is allowed.
+     * @var callable|null A PHP callable that will be called to determine
+     * whether the update of a model is allowed. If not set, no update
+     * check will be performed. The callable should have the following signature:
+     *
+     * @example
+     * ```php
+     * function ($action, $model) {
+     *     // $model is the model instance being updated.
+     *
+     *     // If the update is not allowed, an error should be thrown. For example:
+     *     if ($model->status === 'archived') {
+     *         throw new MethodNotAllowedHttpException('The model cannot be updated when its status is "archived".');
+     *     }
+     * }
+     * ```
      */
     public $checkUpdateAllowed;