From 943fd302664dfba0ddafc512724a5e3e2f4c308b Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Wed, 16 Apr 2025 13:32:04 +0000
Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`fea?=
 =?UTF-8?q?ture/scout-queries`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @GautierDele.

* https://github.com/Lomkit/laravel-access-control/pull/11#issuecomment-2809588313

The following files were modified:

* `src/AccessServiceProvider.php`
* `src/Controls/Control.php`
* `src/Perimeters/Perimeter.php`
* `tests/Support/Access/Controls/ModelControl.php`
* `tests/Support/Models/Model.php`
---
 src/AccessServiceProvider.php                 |  9 ++--
 src/Controls/Control.php                      | 49 ++++++++++++-------
 src/Perimeters/Perimeter.php                  | 36 ++++++++++----
 .../Support/Access/Controls/ModelControl.php  |  7 +++
 tests/Support/Models/Model.php                |  5 ++
 5 files changed, 76 insertions(+), 30 deletions(-)

diff --git a/src/AccessServiceProvider.php b/src/AccessServiceProvider.php
index 6258a81..a98d12d 100644
--- a/src/AccessServiceProvider.php
+++ b/src/AccessServiceProvider.php
@@ -33,9 +33,7 @@ public function register()
     }
 
     /**
-     * Bootstrap any package services.
-     *
-     * @return void
+     * Bootstraps package services, including publishing configuration, registering stubs, and extending Scout's builder with access control macros.
      */
     public function boot()
     {
@@ -46,6 +44,11 @@ public function boot()
         $this->bootScoutBuilder();
     }
 
+    /**
+     * Registers a macro on Laravel Scout's Builder to apply access control based on the authenticated user.
+     *
+     * If the Scout Builder class exists, adds a 'controlled' macro that scopes queries using the model's control logic and the current user.
+     */
     protected function bootScoutBuilder(): void
     {
         if (class_exists(Builder::class)) {
diff --git a/src/Controls/Control.php b/src/Controls/Control.php
index c9a1e80..ed32f5d 100644
--- a/src/Controls/Control.php
+++ b/src/Controls/Control.php
@@ -68,12 +68,13 @@ public function applies(Model $user, string $method, Model $model): bool
     }
 
     /**
-     * Modifies the query builder to enforce access control restrictions for a given user.
+     * Applies access control restrictions to an Eloquent query builder for the specified user.
      *
-     * @param Builder $query The query builder instance to modify.
-     * @param Model   $user  The user model used to determine applicable query control restrictions.
+     * Modifies the query to ensure that only records accessible to the user are returned, based on defined perimeters and configuration.
      *
-     * @return Builder The modified query builder with access controls applied.
+     * @param Builder $query The Eloquent query builder to modify.
+     * @param Model $user The user for whom access control is enforced.
+     * @return Builder The query builder with access control restrictions applied.
      */
     public function queried(Builder $query, Model $user): Builder
     {
@@ -91,12 +92,11 @@ public function queried(Builder $query, Model $user): Builder
     }
 
     /**
-     * Modifies the scout query builder to enforce access control restrictions for a given user.
+     * Applies access control restrictions to a Laravel Scout query builder for the specified user.
      *
-     * @param \Laravel\Scout\Builder $query The scout query builder instance to modify.
-     * @param Model                  $user  The user model used to determine applicable query control restrictions.
-     *
-     * @return Builder The modified query builder with access controls applied.
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @param Model $user The user for whom access control is enforced.
+     * @return \Laravel\Scout\Builder The query builder with access controls applied.
      */
     public function scoutQueried(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
     {
@@ -104,12 +104,13 @@ public function scoutQueried(\Laravel\Scout\Builder $query, Model $user): \Larav
     }
 
     /**
-     * Applies query modifications based on access control perimeters for the given user.
+     * Modifies an Eloquent query builder to enforce access control rules for the specified user.
      *
-     * @param Builder $query The query builder instance to be modified.
-     * @param Model   $user  The user model used to evaluate access control conditions.
+     * Iterates through all defined perimeters, applying their query modifications if access is allowed. If no perimeter applies, the query is modified to return no results.
      *
-     * @return Builder The query builder after applying access control modifications.
+     * @param Builder $query The Eloquent query builder to modify.
+     * @param Model $user The user for whom access control is evaluated.
+     * @return Builder The modified query builder reflecting access control restrictions.
      */
     protected function applyQueryControl(Builder $query, Model $user): Builder
     {
@@ -132,6 +133,15 @@ protected function applyQueryControl(Builder $query, Model $user): Builder
         return $noResultCallback($query);
     }
 
+    /**
+     * Applies access control modifications to a Laravel Scout query builder based on defined perimeters.
+     *
+     * Iterates through perimeters to determine if access should be granted for the user, applying perimeter-specific query modifications. If no perimeter applies, modifies the query to yield no results.
+     *
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @param Model $user The user for whom access control is being enforced.
+     * @return \Laravel\Scout\Builder The modified Scout query builder reflecting access control restrictions.
+     */
     protected function applyScoutQueryControl(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
     {
         $noResultCallback = function (\Laravel\Scout\Builder $query) {
@@ -154,17 +164,22 @@ protected function applyScoutQueryControl(\Laravel\Scout\Builder $query, Model $
     }
 
     /**
-     * Modifies the query builder to return no results.
+     * Alters the Eloquent query builder to ensure no records are returned.
      *
-     * @param Builder $query The query builder instance to modify.
-     *
-     * @return Builder The modified query builder that yields an empty result set.
+     * @param Builder $query The Eloquent query builder to modify.
+     * @return Builder The query builder configured to yield no results.
      */
     protected function noResultQuery(Builder $query): Builder
     {
         return $query->whereRaw('0=1');
     }
 
+    /**
+     * Modifies a Scout query builder to return no results by adding a condition on a non-existent field.
+     *
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @return \Laravel\Scout\Builder The modified query builder that yields no results.
+     */
     protected function noResultScoutQuery(\Laravel\Scout\Builder $query): \Laravel\Scout\Builder
     {
         return $query->where('__NOT_A_VALID_FIELD__', 0);
diff --git a/src/Perimeters/Perimeter.php b/src/Perimeters/Perimeter.php
index 5e63d3e..0ee152d 100644
--- a/src/Perimeters/Perimeter.php
+++ b/src/Perimeters/Perimeter.php
@@ -14,6 +14,11 @@ class Perimeter
     protected Closure $shouldCallback;
     protected Closure $allowedCallback;
 
+    /**
+     * Initializes the Perimeter with default callbacks for access control and query customization.
+     *
+     * By default, all callbacks either return their input unchanged or allow access, enabling further customization through setter methods.
+     */
     public function __construct()
     {
         // Default implementations that can be overridden
@@ -24,19 +29,25 @@ public function __construct()
     }
 
     /**
-     * Executes the should callback to determine if the access control condition is met.
+     * Determines if the access control condition should be applied for the given user, method, and model.
      *
-     * @param Model  $user   The user instance for which the check is performed.
-     * @param string $method The access control method or action being evaluated.
-     * @param Model  $model  The model instance related to the access check.
-     *
-     * @return bool True if the callback validation passes; otherwise, false.
+     * @param Model $user The user being evaluated.
+     * @param string $method The access control action or method.
+     * @param Model $model The related model instance.
+     * @return bool True if the condition applies; false otherwise.
      */
     public function applyShouldCallback(Model $user, string $method, Model $model): bool
     {
         return ($this->shouldCallback)($user, $method, $model);
     }
 
+    /**
+     * Applies the configured Scout query callback to modify a Laravel Scout search query for a given user.
+     *
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @param Model $user The user model for whom the query is being modified.
+     * @return \Laravel\Scout\Builder The modified Scout query builder.
+     */
     public function applyScoutQueryCallback(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
     {
         return ($this->scoutQueryCallback)($query, $user);
@@ -96,11 +107,10 @@ public function should(Closure $shouldCallback): self
     }
 
     /**
-     * Sets the query modification callback.
-     *
-     * @param Closure $queryCallback A callback that customizes the query logic.
+     * Sets a custom callback to modify Eloquent query builders for access control.
      *
-     * @return self Returns the current instance for method chaining.
+     * @param Closure $queryCallback Callback that receives and returns a query builder.
+     * @return self The current Perimeter instance.
      */
     public function query(Closure $queryCallback): self
     {
@@ -109,6 +119,12 @@ public function query(Closure $queryCallback): self
         return $this;
     }
 
+    /**
+     * Sets the callback used to modify Laravel Scout search queries for this perimeter.
+     *
+     * @param Closure $scoutQueryCallback Callback that receives a Scout query builder and user model, and returns a modified query builder.
+     * @return self
+     */
     public function scoutQuery(Closure $scoutQueryCallback): self
     {
         $this->scoutQueryCallback = $scoutQueryCallback;
diff --git a/tests/Support/Access/Controls/ModelControl.php b/tests/Support/Access/Controls/ModelControl.php
index 56da960..87cca17 100644
--- a/tests/Support/Access/Controls/ModelControl.php
+++ b/tests/Support/Access/Controls/ModelControl.php
@@ -12,6 +12,13 @@
 
 class ModelControl extends Control
 {
+    /**
+     * Defines and returns a set of access perimeters with associated permission and query logic.
+     *
+     * Each perimeter specifies conditions for access (allowed, should) and query modifications for both Eloquent and Laravel Scout builders, based on user and model attributes.
+     *
+     * @return array List of configured perimeter instances for access control.
+     */
     protected function perimeters(): array
     {
         $shouldCallback = function (Model $user, string $method, Model $model) {
diff --git a/tests/Support/Models/Model.php b/tests/Support/Models/Model.php
index 3d8e05f..ca57d7f 100644
--- a/tests/Support/Models/Model.php
+++ b/tests/Support/Models/Model.php
@@ -14,6 +14,11 @@ class Model extends BaseModel
     use HasControl;
     use Searchable;
 
+    /**
+     * Creates a new instance of the model's factory.
+     *
+     * @return ModelFactory The factory instance for this model.
+     */
     protected static function newFactory()
     {
         return new ModelFactory();

From 87bced60eaf5ba8c795ffb40125967e199365303 Mon Sep 17 00:00:00 2001
From: StyleCI Bot <bot@styleci.io>
Date: Wed, 16 Apr 2025 13:32:12 +0000
Subject: [PATCH 2/4] Apply fixes from StyleCI

---
 src/Controls/Control.php     | 14 ++++++++++----
 src/Perimeters/Perimeter.php | 10 +++++++---
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/src/Controls/Control.php b/src/Controls/Control.php
index ed32f5d..6278653 100644
--- a/src/Controls/Control.php
+++ b/src/Controls/Control.php
@@ -73,7 +73,8 @@ public function applies(Model $user, string $method, Model $model): bool
      * Modifies the query to ensure that only records accessible to the user are returned, based on defined perimeters and configuration.
      *
      * @param Builder $query The Eloquent query builder to modify.
-     * @param Model $user The user for whom access control is enforced.
+     * @param Model   $user  The user for whom access control is enforced.
+     *
      * @return Builder The query builder with access control restrictions applied.
      */
     public function queried(Builder $query, Model $user): Builder
@@ -95,7 +96,8 @@ public function queried(Builder $query, Model $user): Builder
      * Applies access control restrictions to a Laravel Scout query builder for the specified user.
      *
      * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
-     * @param Model $user The user for whom access control is enforced.
+     * @param Model                  $user  The user for whom access control is enforced.
+     *
      * @return \Laravel\Scout\Builder The query builder with access controls applied.
      */
     public function scoutQueried(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
@@ -109,7 +111,8 @@ public function scoutQueried(\Laravel\Scout\Builder $query, Model $user): \Larav
      * Iterates through all defined perimeters, applying their query modifications if access is allowed. If no perimeter applies, the query is modified to return no results.
      *
      * @param Builder $query The Eloquent query builder to modify.
-     * @param Model $user The user for whom access control is evaluated.
+     * @param Model   $user  The user for whom access control is evaluated.
+     *
      * @return Builder The modified query builder reflecting access control restrictions.
      */
     protected function applyQueryControl(Builder $query, Model $user): Builder
@@ -139,7 +142,8 @@ protected function applyQueryControl(Builder $query, Model $user): Builder
      * Iterates through perimeters to determine if access should be granted for the user, applying perimeter-specific query modifications. If no perimeter applies, modifies the query to yield no results.
      *
      * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
-     * @param Model $user The user for whom access control is being enforced.
+     * @param Model                  $user  The user for whom access control is being enforced.
+     *
      * @return \Laravel\Scout\Builder The modified Scout query builder reflecting access control restrictions.
      */
     protected function applyScoutQueryControl(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
@@ -167,6 +171,7 @@ protected function applyScoutQueryControl(\Laravel\Scout\Builder $query, Model $
      * Alters the Eloquent query builder to ensure no records are returned.
      *
      * @param Builder $query The Eloquent query builder to modify.
+     *
      * @return Builder The query builder configured to yield no results.
      */
     protected function noResultQuery(Builder $query): Builder
@@ -178,6 +183,7 @@ protected function noResultQuery(Builder $query): Builder
      * Modifies a Scout query builder to return no results by adding a condition on a non-existent field.
      *
      * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     *
      * @return \Laravel\Scout\Builder The modified query builder that yields no results.
      */
     protected function noResultScoutQuery(\Laravel\Scout\Builder $query): \Laravel\Scout\Builder
diff --git a/src/Perimeters/Perimeter.php b/src/Perimeters/Perimeter.php
index 0ee152d..c251342 100644
--- a/src/Perimeters/Perimeter.php
+++ b/src/Perimeters/Perimeter.php
@@ -31,9 +31,10 @@ public function __construct()
     /**
      * Determines if the access control condition should be applied for the given user, method, and model.
      *
-     * @param Model $user The user being evaluated.
+     * @param Model  $user   The user being evaluated.
      * @param string $method The access control action or method.
-     * @param Model $model The related model instance.
+     * @param Model  $model  The related model instance.
+     *
      * @return bool True if the condition applies; false otherwise.
      */
     public function applyShouldCallback(Model $user, string $method, Model $model): bool
@@ -45,7 +46,8 @@ public function applyShouldCallback(Model $user, string $method, Model $model):
      * Applies the configured Scout query callback to modify a Laravel Scout search query for a given user.
      *
      * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
-     * @param Model $user The user model for whom the query is being modified.
+     * @param Model                  $user  The user model for whom the query is being modified.
+     *
      * @return \Laravel\Scout\Builder The modified Scout query builder.
      */
     public function applyScoutQueryCallback(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
@@ -110,6 +112,7 @@ public function should(Closure $shouldCallback): self
      * Sets a custom callback to modify Eloquent query builders for access control.
      *
      * @param Closure $queryCallback Callback that receives and returns a query builder.
+     *
      * @return self The current Perimeter instance.
      */
     public function query(Closure $queryCallback): self
@@ -123,6 +126,7 @@ public function query(Closure $queryCallback): self
      * Sets the callback used to modify Laravel Scout search queries for this perimeter.
      *
      * @param Closure $scoutQueryCallback Callback that receives a Scout query builder and user model, and returns a modified query builder.
+     *
      * @return self
      */
     public function scoutQuery(Closure $scoutQueryCallback): self

From 0483960a2e4f90c6c7ed08494b372f34895183b0 Mon Sep 17 00:00:00 2001
From: Gautier DELEGLISE <gautier.deleglise@gmail.com>
Date: Wed, 16 Apr 2025 15:41:59 +0200
Subject: [PATCH 3/4] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20removed=20unecessary?=
 =?UTF-8?q?=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/AccessServiceProvider.php                  | 6 ++----
 src/Controls/Control.php                       | 8 +-------
 src/Perimeters/Perimeter.php                   | 2 --
 tests/Support/Access/Controls/ModelControl.php | 7 -------
 tests/Support/Models/Model.php                 | 7 +------
 5 files changed, 4 insertions(+), 26 deletions(-)

diff --git a/src/AccessServiceProvider.php b/src/AccessServiceProvider.php
index a98d12d..6001f59 100644
--- a/src/AccessServiceProvider.php
+++ b/src/AccessServiceProvider.php
@@ -33,7 +33,7 @@ public function register()
     }
 
     /**
-     * Bootstraps package services, including publishing configuration, registering stubs, and extending Scout's builder with access control macros.
+     * Bootstrap any package services.
      */
     public function boot()
     {
@@ -45,9 +45,7 @@ public function boot()
     }
 
     /**
-     * Registers a macro on Laravel Scout's Builder to apply access control based on the authenticated user.
-     *
-     * If the Scout Builder class exists, adds a 'controlled' macro that scopes queries using the model's control logic and the current user.
+     * Registers a macro on Laravel Scout's Builder.
      */
     protected function bootScoutBuilder(): void
     {
diff --git a/src/Controls/Control.php b/src/Controls/Control.php
index 6278653..8a869fc 100644
--- a/src/Controls/Control.php
+++ b/src/Controls/Control.php
@@ -70,8 +70,6 @@ public function applies(Model $user, string $method, Model $model): bool
     /**
      * Applies access control restrictions to an Eloquent query builder for the specified user.
      *
-     * Modifies the query to ensure that only records accessible to the user are returned, based on defined perimeters and configuration.
-     *
      * @param Builder $query The Eloquent query builder to modify.
      * @param Model   $user  The user for whom access control is enforced.
      *
@@ -108,8 +106,6 @@ public function scoutQueried(\Laravel\Scout\Builder $query, Model $user): \Larav
     /**
      * Modifies an Eloquent query builder to enforce access control rules for the specified user.
      *
-     * Iterates through all defined perimeters, applying their query modifications if access is allowed. If no perimeter applies, the query is modified to return no results.
-     *
      * @param Builder $query The Eloquent query builder to modify.
      * @param Model   $user  The user for whom access control is evaluated.
      *
@@ -139,8 +135,6 @@ protected function applyQueryControl(Builder $query, Model $user): Builder
     /**
      * Applies access control modifications to a Laravel Scout query builder based on defined perimeters.
      *
-     * Iterates through perimeters to determine if access should be granted for the user, applying perimeter-specific query modifications. If no perimeter applies, modifies the query to yield no results.
-     *
      * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
      * @param Model                  $user  The user for whom access control is being enforced.
      *
@@ -180,7 +174,7 @@ protected function noResultQuery(Builder $query): Builder
     }
 
     /**
-     * Modifies a Scout query builder to return no results by adding a condition on a non-existent field.
+     * Modifies the Scout query builder to ensure no records are returned.
      *
      * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
      *
diff --git a/src/Perimeters/Perimeter.php b/src/Perimeters/Perimeter.php
index c251342..7461106 100644
--- a/src/Perimeters/Perimeter.php
+++ b/src/Perimeters/Perimeter.php
@@ -16,8 +16,6 @@ class Perimeter
 
     /**
      * Initializes the Perimeter with default callbacks for access control and query customization.
-     *
-     * By default, all callbacks either return their input unchanged or allow access, enabling further customization through setter methods.
      */
     public function __construct()
     {
diff --git a/tests/Support/Access/Controls/ModelControl.php b/tests/Support/Access/Controls/ModelControl.php
index 87cca17..56da960 100644
--- a/tests/Support/Access/Controls/ModelControl.php
+++ b/tests/Support/Access/Controls/ModelControl.php
@@ -12,13 +12,6 @@
 
 class ModelControl extends Control
 {
-    /**
-     * Defines and returns a set of access perimeters with associated permission and query logic.
-     *
-     * Each perimeter specifies conditions for access (allowed, should) and query modifications for both Eloquent and Laravel Scout builders, based on user and model attributes.
-     *
-     * @return array List of configured perimeter instances for access control.
-     */
     protected function perimeters(): array
     {
         $shouldCallback = function (Model $user, string $method, Model $model) {
diff --git a/tests/Support/Models/Model.php b/tests/Support/Models/Model.php
index ca57d7f..eff43e9 100644
--- a/tests/Support/Models/Model.php
+++ b/tests/Support/Models/Model.php
@@ -13,12 +13,7 @@ class Model extends BaseModel
     use HasFactory;
     use HasControl;
     use Searchable;
-
-    /**
-     * Creates a new instance of the model's factory.
-     *
-     * @return ModelFactory The factory instance for this model.
-     */
+    
     protected static function newFactory()
     {
         return new ModelFactory();

From 4f566191d837ea250b801aa2b7b65fbe9d032acd Mon Sep 17 00:00:00 2001
From: StyleCI Bot <bot@styleci.io>
Date: Wed, 16 Apr 2025 13:42:14 +0000
Subject: [PATCH 4/4] Apply fixes from StyleCI

---
 tests/Support/Models/Model.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Support/Models/Model.php b/tests/Support/Models/Model.php
index eff43e9..3d8e05f 100644
--- a/tests/Support/Models/Model.php
+++ b/tests/Support/Models/Model.php
@@ -13,7 +13,7 @@ class Model extends BaseModel
     use HasFactory;
     use HasControl;
     use Searchable;
-    
+
     protected static function newFactory()
     {
         return new ModelFactory();