From a6ef2b42f8ea75c4921a9bbe0f4799514567637a Mon Sep 17 00:00:00 2001 From: Jehizkia Date: Fri, 31 Mar 2023 20:19:38 +0200 Subject: [PATCH 1/2] Updated docs --- README.md | 189 +++++++++++++++++++++++++------ config/resource-lock.php | 48 +++----- src/Models/Concerns/HasLocks.php | 2 +- 3 files changed, 174 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 2ff6b82..cadda3b 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,19 @@ # Resoure Lock + +filament-shield-art + + + [![Latest Version on Packagist](https://img.shields.io/packagist/v/kenepa/resourcelock.svg?style=flat-square)](https://packagist.org/packages/kenepa/resourcelock) [![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/kenepa/resourcelock/run-tests?label=tests)](https://github.com/kenepa/resourcelock/actions?query=workflow%3Arun-tests+branch%3Amain) [![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/kenepa/resourcelock/Check%20&%20fix%20styling?label=code%20style)](https://github.com/kenepa/resourcelock/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain) [![Total Downloads](https://img.shields.io/packagist/dt/kenepa/resourcelock.svg?style=flat-square)](https://packagist.org/packages/kenepa/resourcelock) - - -This is where your description should go. Limit it to a paragraph or two. Consider adding a small example. +Filament Resource Lock is a Filament plugin that adds resource locking functionality to your site. When a +user begins editing a resource, Filament Resource Lock automatically locks the resource to prevent other users from +editing it at the same time. The resource will be automatically unlocked after a set period of time, or when the user +saves or discards their changes. ## Installation @@ -17,12 +23,153 @@ You can install the package via composer: composer require kenepa/resource-lock ``` -You can run the install command to publish config files, migrations and run migrations (optional) +You can run the installation command to publish config files, migrations and run migrations (optional) ```bash -php artisan resource-lock:instal +php artisan resource-lock:install +``` + +## Usage + +The Filament Resource Lock package enables you to lock a resource and prevent other users from editing it at the same +time. Currently, this package only locks +the [EditRecord](https://filamentphp.com/docs/2.x/admin/resources/editing-records) page and the edit modal when editing +a [simple modal resource.](https://filamentphp.com/docs/2.x/admin/resources/getting-started#simple-modal-resources) +Follow the steps below to add locks to your resources. + +### Add Locks to your modal + +The first step is to add the HasLocks trait to the modal of your resource. The HasLocks trait enables the locking +functionality on your model. + +```php +use Kenepa\ResourceLock\Models\Concerns\HasLocks; + +class Post extends Model +{ + use HasFactory; + use HasLocks; + + protected $table = 'posts'; + + protected $guarded = []; +} +``` + +### Add Locks to your EditRecord Page + +The second step is to add the UsesResourceLock trait to your EditRecord page. The UsesResourceLock trait enables the +locking function on your edit page. + +```php +use Kenepa\ResourceLock\Resources\Pages\Concerns\UsesResourceLock; + +class EditPost extends EditRecord +{ + use UsesResourceLock; + + protected static string $resource = PostResource::class; +} +``` + +#### Simple modal Resource + +If your resource is +a [simple modal](https://filamentphp.com/docs/2.x/admin/resources/getting-started#simple-modal-resources) resource, +you'll need to use the UsesSimpleResourceLock trait instead. + +```php +use Kenepa\ResourceLock\Resources\Pages\Concerns\UsesSimpleResourceLock; + +class ListExamples extends ManageRecords +{ + use UsesSimpleResourceLock; + + protected static string $resource = ExampleResource::class; + +} ``` +And that's it! Your resource is now able to be locked. Refer to the documentation below for more information on how to +configure the locking functionality. + +## Configuration + +### Access + +filament-shield-art + +You can restrict the access to the **Unlock** button by adjusting the access variable. Enabling the "limited" key and +setting it to true allows you to specify either a Laravel Gate class or a permission name from +the [Spatie Permissions package](https://github.com/spatie/laravel-permission). + +```php + + /* + |-------------------------------------------------------------------------- + | Resource Unlocker + |-------------------------------------------------------------------------- + | + | The unlocker configuration specifies whether limited access is enabled for + | the resource lock feature. If limited access is enabled, only specific + | users or roles will be able to unlock locked resources. + | + */ + + 'unlocker' => [ + 'limited_access' => false, + 'gate' => 'unlock-resource' + ], +``` + +### Using custom models + +Sometimes, you may have a customized implementation for the User model in your application, or you may want to use a +custom class for the ResourceLock functionality. In such cases, you can update the configuration file to specify the new +class you want to use. This will ensure that the ResourceLock functionality works as expected with the new +implementation. + +```php + /* + |-------------------------------------------------------------------------- + | Models + |-------------------------------------------------------------------------- + | + | The models configuration specifies the classes that represent your application's + | data objects. This configuration is used by the framework to interact with + | the application's data models. You can even implement your own ResourceLock model. + | + */ + + 'models' => [ + 'User' => \App\Models\CustomUser::class, + 'ResourceLock' => \App\Models\CustomResourceLock::class, + ], +``` + +### Overriding default functionality + +If you need some custom functionality beyond what the traits provide, you can override the functions that they use. For +example, if you want to change the URL that the "Return" button redirects to, you can override the +resourceLockReturnUrl() function. By default, this button takes you to the index page of the resource, but you can +change it to whatever URL you want by adding your custom implementation in the resourceLockReturnUrl() function. + +For instance, if you want the "Return" button to redirect to https://laracasts.com, you can override the function as +follows: + +```php + public function resourceLockReturnUrl(): string + { + return 'https://laracasts.com'; + } +``` + +Now the return url will redirect to laracasts.com + +This will change the behavior of the "Return" button to redirect to the provided URL. + +## Publishing migrations, configuration and view + ```bash php artisan vendor:publish --tag="resource-lock-migrations" php artisan migrate @@ -43,28 +190,11 @@ php artisan vendor:publish --tag="resource-lock-config" Optionally, you can publish the views using -```bash -php artisan vendor:publish --tag="resource-lock-views" -``` - -This is the contents of the published config file: - -```php -return [ -]; -``` - -## Usage - -```php -$resourcelock = new Kenepa\ResourceLock(); -echo $resourcelock->echoPhrase('Hello, Kenepa!'); -``` - -## Testing +> Note: Publishing Blade views can introduce breaking changes into your app. If you're interested in how to stay +> safe, [see this article by Dan Harrin](https://filamentphp.com/blog/publishing-views-in-laravel). ```bash -composer test +php artisan vendor:publish --tag="resource-lock-views" ``` ## Changelog @@ -75,15 +205,6 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details. -## Security Vulnerabilities - -Please review [our security policy](../../security/policy) on how to report security vulnerabilities. - -## Credits - -- [Jehizkia](https://github.com/Jehizkia) -- [All Contributors](../../contributors) - ## License The MIT License (MIT). Please see [License File](LICENSE.md) for more information. diff --git a/config/resource-lock.php b/config/resource-lock.php index 4a866e1..e38ca8d 100644 --- a/config/resource-lock.php +++ b/config/resource-lock.php @@ -7,15 +7,15 @@ | Models |-------------------------------------------------------------------------- | - | This value is the name of your application. This value is used when the - | framework needs to place the application's name in a notification or - | any other location as required by the application or its packages. + | The models configuration specifies the classes that represent your application's + | data objects. This configuration is used by the framework to interact with + | the application's data models. You can even implement your own ResourceLock model. | */ 'models' => [ 'User' => \App\Models\User::class, - // 'ResourceLock' => null, + // 'ResourceLock' => null, ], /* @@ -23,53 +23,41 @@ | Resource Unlocker |-------------------------------------------------------------------------- | - | This value is the name of your application. This value is used when the - | framework needs to place the application's name in a notification or - | any other location as required by the application or its packages. + | The unlocker configuration specifies whether limited access is enabled for + | the resource lock feature. If limited access is enabled, only specific + | users or roles will be able to unlock locked resources. | */ 'unlocker' => [ 'limited_access' => false, - // 'gate' => '' + // 'gate' => '' ], /* |-------------------------------------------------------------------------- - | Lock Expire (in minutes) + | Lock timeout (in minutes) |-------------------------------------------------------------------------- | - | This value is the name of your application. This value is used when the - | framework needs to place the application's name in a notification or - | any other location as required by the application or its packages. + | The lock_timeout configuration specifies the time interval, in minutes, + | after which a lock on a resource will expire if it has not been manually + | unlocked or released by the user. | */ - 'locks_expires' => 10, + 'lock_timeout' => 10, /* |-------------------------------------------------------------------------- - | Lock Expire (in minutes) + | Throw Forbidden Exception |-------------------------------------------------------------------------- | - | This value is the name of your application. This value is used when the - | framework needs to place the application's name in a notification or - | any other location as required by the application or its packages. - | - */ - - 'display_user_of_lock' => true, - - /* - |-------------------------------------------------------------------------- - | Throw forbidden exception - |-------------------------------------------------------------------------- - | - | If a tech savvy user is able to bypass the locked resource modal an 304 forbidden - | exception will be thrown right before the model is saved. The user will be - | greeted by a 403 error. + | The throw_forbidden_exception configuration specifies whether a 403 forbidden + | exception should be thrown if a tech-savvy user is able to bypass the locked + | resource modal and attempt to save the resource. | */ 'throw_forbidden_exception' => true, ]; + diff --git a/src/Models/Concerns/HasLocks.php b/src/Models/Concerns/HasLocks.php index 6e769f0..c263313 100644 --- a/src/Models/Concerns/HasLocks.php +++ b/src/Models/Concerns/HasLocks.php @@ -78,7 +78,7 @@ public function hasExpiredLock(): bool return false; } - $expiredDate = (new Carbon($this->resourceLock->updated_at))->addMinutes(config('resource-lock.locks_expires')); + $expiredDate = (new Carbon($this->resourceLock->updated_at))->addMinutes(config('resource-lock.lock_timeout')); return Carbon::now()->greaterThan($expiredDate); } From 107970af09cfe40d5d0bc2de3a17b35186a8792b Mon Sep 17 00:00:00 2001 From: Jehizkia Date: Fri, 31 Mar 2023 20:38:13 +0200 Subject: [PATCH 2/2] Updated docs --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index cadda3b..ad8de67 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ user begins editing a resource, Filament Resource Lock automatically locks the r editing it at the same time. The resource will be automatically unlocked after a set period of time, or when the user saves or discards their changes. +filament-shield-art + ## Installation You can install the package via composer: