Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jmkim/laravel-entrust-gui
GUI for Shanmuga's LaravelEntrust for Laravel 5+ (5, 6, 7, 8 and 9)
https://github.com/jmkim/laravel-entrust-gui
access-control entrust laravel laravel-application role-permissions
Last synced: 26 days ago
JSON representation
GUI for Shanmuga's LaravelEntrust for Laravel 5+ (5, 6, 7, 8 and 9)
- Host: GitHub
- URL: https://github.com/jmkim/laravel-entrust-gui
- Owner: jmkim
- License: mit
- Created: 2022-06-08T04:43:32.000Z (over 2 years ago)
- Default Branch: 6.x-and-above
- Last Pushed: 2022-06-08T06:21:29.000Z (over 2 years ago)
- Last Synced: 2024-03-15T08:22:19.285Z (8 months ago)
- Topics: access-control, entrust, laravel, laravel-application, role-permissions
- Language: PHP
- Homepage: https://packagist.org/packages/jmkim/laravel-entrust-gui
- Size: 254 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Entrust GUI
[](https://codeclimate.com/github/jmkim/laravel-entrust-gui)
[](https://travis-ci.org/jmkim/laravel-entrust-gui)
[](https://packagist.org/packages/jmkim/laravel-entrust-gui)
[](https://packagist.org/packages/jmkim/laravel-entrust-gui)
[](https://packagist.org/packages/jmkim/laravel-entrust-gui)
[](https://packagist.org/packages/jmkim/laravel-entrust-gui)
Entrust GUI is a Admin Interface that makes the administration of users, roles and permissions easier for [Shanmuga's Laravel Entrust](https://github.com/shanmuga3/laravel-entrust) package.
This package is currently not for handling authentication, authorisation or registration of users.
## Disclaimer
Entrust GUI was fully written by Mitch Stanley ([@acoustep](https://github.com/acoustep)). The original codebase is placed at [https://github.com/acoustep/entrust-gui](https://github.com/acoustep/entrust-gui).
This package is a port for [Shanmuga's Laravel Entrust](https://github.com/shanmuga3/laravel-entrust).
* **(Laravel 5, original but unmaintained)** [acoustep's Entrust GUI](https://github.com/acoustep/entrust-gui) for [Zizaco's ENTRUST](https://github.com/Zizaco/entrust)
* **(Laravel 5 ~ 9, ported and maintained)** [jmkim's Laravel Entrust GUI (this package)](https://github.com/jmkim/laravel-entrust-gui) for [Shanmuga's Laravel Entrust](https://github.com/shanmuga3/laravel-entrust)
You can easily migrate from acoustep's to this package by replacing:
* `Acoustep` to `Jmkim`
* `acoustep` to `jmkim`
## Installation
Add the package to your ```composer.json``` file
```
"jmkim/laravel-entrust-gui": "6.x-dev",
"shanmuga/laravel-entrust": "3.x-dev",
"watson/validating": "3.2.0 as 2.0.1"
```
Add the service provider to your ```config/app.php``` file
```
Jmkim\EntrustGui\EntrustGuiServiceProvider::class,
```
Add the Entrust Alias to your ```config/app.php``` file as well.
```
'Entrust' => Shanmuga\LaravelEntrust\LaravelEntrustFacade::class,
```
Publish the configuration file(s)
```
php artisan vendor:publish --tag="config"
```
Add the ```table``` key with the value ```users``` to the ```providers.users``` array in ```config/auth.php```.
```
'providers' => [
'users' => [
'driver' => 'eloquent',
'model' => App\User::class,
'table' => 'users',
],
// 'users' => [
// 'driver' => 'database',
// 'table' => 'users',
// ],
],
```
If you haven't already set up Entrust then make the migration file and run the migration.
```
php artisan entrust:migration
php artisan migrate
```
If you see the following error:
```
[Illuminate\Database\QueryException]
SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes (SQL: alter table
`users` add unique `users_email_unique`(`email`))
```
Add the following to your `app/Providers/AppServiceProvider.php`
```
use Illuminate\Support\Facades\Schema;
...
public function boot() {
Schema::defaultStringLength(191);
}
```
If you then see this error
```
ReflectionException : Method Shanmuga\LaravelEntrust\MakeMigrationCommand::handle() does not exist
```
This is an issue with `Entrust`, there is a temporary fix by going to `vendor-> shanmuga-> laravel-entrust-> src-> commands-> MakeMigrationCommand.php` and changing `fire()` to `handle()` and re-running thie migration. [See here for more details](https://github.com/Zizaco/entrust/issues/836). Once this is done, rerun the migration commands.
Finally, if you have this error
```
(errno: 150 "Foreign key constraint is incorrectly formed") (SQL: alter table `role_user` add constraint `role_user_user_id_foreign` foreign key (`user_id`) references `users` (`id`) on delete cascade on update cascade)
```
Go to the newly created migration file (`entrust_setup_tables`) and update the `user_id` foreign key constraint in `role_user` to use `bigInteger`.
```
Schema::create('role_user', function (Blueprint $table) {
$table->bigInteger('user_id')->unsigned();
$table->integer('role_id')->unsigned();
$table->foreign('user_id')->references('id')->on('users')
->onUpdate('cascade')->onDelete('cascade');
$table->foreign('role_id')->references('id')->on('roles')
->onUpdate('cascade')->onDelete('cascade');
$table->primary(['user_id', 'role_id']);
});
```
Rerun the entrust migration afterwards (You may need to clear your database, too).
Entrust GUI uses [esensi/model](https://github.com/esensi/model) which means you can set your validation rules in your models.
To generate ```User```, ```Role``` and ```Permission``` models run the ```entrust-gui:models``` command.
```
php artisan entrust-gui:models
```
See the **manually creating models** section if you prefer to adjust your current model files.
By default, all three files are published into the ```app_path()``` directory. You can specify the files separately and the location
Add the Entrust GUI middleware to ```app\Http\Kernal.php```. This middleware will allow users with the role ```admin``` (case sensitive) to access Entrust GUI and deny other users.
```
protected $routeMiddleware = [
// ...
'entrust-gui.admin' => \Jmkim\EntrustGui\Http\Middleware\AdminAuth::class,
];
```
Finally, there is currently an issue with Entrust which requires you to set the cache driver to array. This may change in the future. You can change this setting in your ```.env``` file.
```
CACHE_DRIVER=array
```
At this point you're all good to go. See Getting Started for how to use the package.
## Getting Started
### Using Laravel Authentication
Run the auth command if you haven't already set it up.
```
php artisan make:auth
```
### Accessing Entrust GUI
By default all routes are prefixed with ```/entrust-gui```.
* Users: ```/entrust-gui/users```
* Roles: ```/entrust-gui/roles```
* Permissions: ```/entrust-gui/permissions```
You can change this prefix by editing ```route-prefix``` in ```config/entrust-gui.php```.
```
'route-prefix' => 'admin'
```
Pointing your app to ```/entrust-gui/users``` will redirect you to ```/auth/login``` if you are not logged in as admin using the default ```entrust-gui.admin``` middleware.
If you have not set up Laravel authentication you will see a ```NotFoundHttpException``` exception. See the Laravel [Authentication](http://laravel.com/docs/5.1/authentication) documentation for setting up the Login system in Laravel 5.1.
### Middleware
By default Entrust GUI uses ```entrust-gui.admin``` for middleware. This allows logged in users with the ```admin``` role to access it.
You can change the middleware in ```config/entrust-gui.php``` in the ```middleware``` setting.
If you wish to test out the system without middleware then go to ```config/entrust-gui.php```, remove ```entrust-gui.admin``` middleware and keep ```web``` which is required for flash messages to work correctly in Laravel 5.2.
```
'middleware' => 'web',
```
If you want to change the name of the role that has access to the ```admin``` middleware, update ```middleware-role``` in the configuration file.
```
"middleware-role" => 'sudo-admin',
```
### Layout
To use your own layout override the ```layout``` key in ```config/entrust-gui.php``` with the template you wish to use.
```
"layout" => "app", // located in views/app.blade.php
```
Each template yields to ```heading``` and ```content``` so make sure your new layout has those sections.
```
title
@yield('heading')
@include('entrust-gui::partials.notifications')
@yield('content')
```
### Editing Templates
To edit the template files you first need to publish them
```
php artisan vendor:publish --tag="views"
```
All files are then stored in the ```resources/views/vendor/entrust-gui``` directory.
### Routes
You may wish to link to pages in your own templates. EntrustGUI follows Laravel's ```Route::resource``` method with the exception of ```show```.
```
route('entrust-gui::users.index')
route('entrust-gui::users.create')
route('entrust-gui::users.destroy', $id)
route('entrust-gui::users.update', $id)
route('entrust-gui::users.edit', $id)
```
### Events
The following event classes are available:
* ```UserCreatedEvent```, ```UserDeletedEvent```, ```UserUpdatedEvent```.
* ```RoleCreatedEvent```, ```RoleDeletedEvent```, ```RoleUpdatedEvent```.
* ```PermissionCreatedEvent```, ```PermissionDeletedEvent```, ```PermissionUpdatedEvent```.
#### Example Event Listener
```
user->email);
}
}
```
Add the listeners you need to use to ```app/Providers/EventServiceProvider.php```.
```
protected $listen = [
'Jmkim\EntrustGui\Events\UserCreatedEvent' => [
'App\Listeners\UserCreatedListener',
],
'Jmkim\EntrustGui\Events\UserUpdatedEvent' => [
'App\Listeners\UserUpdatedListener',
],
'Jmkim\EntrustGui\Events\UserDeletedEvent' => [
'App\Listeners\UserDeletedListener',
],
'Jmkim\EntrustGui\Events\RoleCreatedEvent' => [
'App\Listeners\RoleCreatedListener',
],
'Jmkim\EntrustGui\Events\RoleUpdatedEvent' => [
'App\Listeners\RoleUpdatedListener',
],
'Jmkim\EntrustGui\Events\RoleDeletedEvent' => [
'App\Listeners\RoleDeletedListener',
],
'Jmkim\EntrustGui\Events\PermissionCreatedEvent' => [
'App\Listeners\PermissionCreatedListener',
],
'Jmkim\EntrustGui\Events\PermissionUpdatedEvent' => [
'App\Listeners\PermissionUpdatedListener',
],
'Jmkim\EntrustGui\Events\PermissionDeletedEvent' => [
'App\Listeners\PermissionDeletedListener',
]
];
```
### Editing Translations
Run the publish translation command
```
php artisan vendor:publish --tag="translations"
```
Translations are then published to ```resources/lang/vendor/entrust-gui```.
### Adding Password Confirmation Field to Users
Update your ```User``` model to the following:
```
[
'email' => 'required|email|unique:users',
'password' => 'required|confirmed',
],
'updating' => [
'email' => 'required|email|unique:users',
'password' => 'confirmed',
],
];
public function entrustPasswordHash()
{
$this->password = Hash::make($this->password);
$this->forceSave();
}
}
```
Update ```config/entrust-gui.php```
```
'confirmable' => true,
```
### Generating Models Command Options
Generating a specific model
```
php artisan entrust-gui:models User
```
Changing the model directory destination
```
php artisan entrust-gui:models --path=new/path
```
Skipping confirmation prompts for overwriting existing files
```
php artisan entrust-gui:models --force
```
### Manually Creating Models
Here are ```User```, ```Role``` and ```Permission``` models. Make sure these parameters are and traits are included for the package to work as intended.
#### app/User.php
```
[
'email' => 'required|email|unique:users',
'password' => 'required',
],
'updating' => [
'email' => 'required|email|unique:users',
'password' => '',
],
];
public function entrustPasswordHash()
{
$this->password = Hash::make($this->password);
$this->save();
}
}
```
#### app/Role.php
```
'required|unique:roles',
'display_name' => 'required|unique:roles',
];
}
```
#### app/Permission.php
```
'required|unique:permissions',
];
}
```
### Custom queries, sorting and filters for users
If you would like to search, sort and filter the users you can use the l5-repository searchable fields feature.
In your entrust-gui.php configuration file, add the fields that you wish to be searchable
```
"users" => [
'fieldSearchable' => [
'email'
],
],
```
You can now create links such as the following:
* http://localhost.dev/entrust-gui/users?search=John%20Doe
* http://localhost.dev/entrust-gui/users?search=email&searchFields=email:like
* http://localhost.dev/entrust-gui/users?search=email&searchFields=email:like&orderBy=email&sortedBy=asc
* http://tcascompressors.dev/admin/users?filter=email
You can read more about these options [here](https://github.com/andersao/l5-repository#using-the-requestcriteria)
## Upgrade Guide / Breaking Changes
### 5.2 Branch
Add the following to the ```config/entrust-gui.php``` configuration file to enable custom sorting and filters
```
"users" => [
'fieldSearchable' => [],
],
```
Optional removal of ```Esensi\Model\Traits\HashingModelTrait```. Replaced with ```Jmkim\EntrustGui\Contracts\HashMethodInterface``` and allows users to set their own password hashing method for within the Entrust GUI. For the default Laravel 5.2 Auth it's recommended to use the following snippet in your User model.
```
use Jmkim\EntrustGui\Contracts\HashMethodInterface;
use Hash;
class User extends Model implements AuthenticatableContract, CanResetPasswordContract, ValidatingModelInterface, HashMethodInterface
// ...
public function entrustPasswordHash()
{
$this->password = hash::make($this->password);
$this->save();
}
}
```
### 0.6
Includes a new config key, ```"unauthorized-url"``` which lets you set the redirection if a user is not authorized. If this key is not found, it will use the old url, ```/auth/login```. The default is set to ```/login``` to match Laravel 5.2's built in authentication route.
### 0.3.* to 0.4.0
Starting from 0.4.0 Entrust GUI switches from ```dwightwatson/validating``` to ```esensi/model```.
Hashing passwords has moved from the package to the ```User``` model.
Update your ```User``` model to the one in the latest documentation.
Add ```'confirmable' => false,``` to your configuration file.
If you intend to use the confirmable option and have already published the views add the following to your ```resources/views/vendor/entrust-gui/users/partials/form.blade.php``` template
```
@if(Config::get('entrust-gui.confirmable') === true)
Confirm Password
@endif
```
## Support Entrust GUI
If you'd like to help, please feel free to open an issue with feature requests or proposals.
## To do
* Advanced middleware configuration
* More testing
* More documentation
* Animated video preview