diff --git a/src/AccessServiceProvider.php b/src/AccessServiceProvider.php index 6258a81..6001f59 100644 --- a/src/AccessServiceProvider.php +++ b/src/AccessServiceProvider.php @@ -34,8 +34,6 @@ public function register() /** * Bootstrap any package services. - * - * @return void */ public function boot() { @@ -46,6 +44,9 @@ public function boot() $this->bootScoutBuilder(); } + /** + * Registers a macro on Laravel Scout's Builder. + */ protected function bootScoutBuilder(): void { if (class_exists(Builder::class)) { diff --git a/src/Controls/Control.php b/src/Controls/Control.php index c9a1e80..8a869fc 100644 --- a/src/Controls/Control.php +++ b/src/Controls/Control.php @@ -68,12 +68,12 @@ 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. + * @param Builder $query The Eloquent query builder to modify. + * @param Model $user The user for whom access control is enforced. * - * @return Builder The modified query builder with access controls applied. + * @return Builder The query builder with access control restrictions applied. */ public function queried(Builder $query, Model $user): Builder { @@ -91,12 +91,12 @@ 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. + * @param \Laravel\Scout\Builder $query The Scout query builder to modify. + * @param Model $user The user for whom access control is enforced. * - * @return Builder The modified query builder with access controls applied. + * @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,12 @@ 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. + * @param Builder $query The Eloquent query builder to modify. + * @param Model $user The user for whom access control is evaluated. * - * @return Builder The query builder after applying access control modifications. + * @return Builder The modified query builder reflecting access control restrictions. */ protected function applyQueryControl(Builder $query, Model $user): Builder { @@ -132,6 +132,14 @@ 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. + * + * @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 +162,24 @@ 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. + * @param Builder $query The Eloquent query builder to modify. * - * @return Builder The modified query builder that yields an empty result set. + * @return Builder The query builder configured to yield no results. */ protected function noResultQuery(Builder $query): Builder { return $query->whereRaw('0=1'); } + /** + * Modifies the Scout query builder to ensure no records are returned. + * + * @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..7461106 100644 --- a/src/Perimeters/Perimeter.php +++ b/src/Perimeters/Perimeter.php @@ -14,6 +14,9 @@ class Perimeter protected Closure $shouldCallback; protected Closure $allowedCallback; + /** + * Initializes the Perimeter with default callbacks for access control and query customization. + */ public function __construct() { // Default implementations that can be overridden @@ -24,19 +27,27 @@ 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. + * @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 callback validation passes; otherwise, false. + * @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,11 @@ public function should(Closure $shouldCallback): self } /** - * Sets the query modification callback. + * Sets a custom callback to modify Eloquent query builders for access control. * - * @param Closure $queryCallback A callback that customizes the query logic. + * @param Closure $queryCallback Callback that receives and returns a query builder. * - * @return self Returns the current instance for method chaining. + * @return self The current Perimeter instance. */ public function query(Closure $queryCallback): self { @@ -109,6 +120,13 @@ 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;