LaraSnap

Installation

Step One

LaraSnap requires fresh Laravel installation. You can include the LaraSnap composer package to your laravel application with the following command:

composer require larasnap/laravel-admin

Next make sure to create a new database and add your database credentials to your .env file, you will also want to add your application URL in the APP_URL variable:

    APP_URL=http://localhost
    DB_HOST=localhost
    DB_DATABASE=homestead
    DB_USERNAME=homestead
    DB_PASSWORD=secret

Step Two

To install LaraSnap simply run

php artisan larasnap:admin-install

Service provider will be discovered automatically.

The command will do the following

Publish LaraSnap Migration & Seeder files to yor application.
Publish Auth/LoginController & Auth/RegisterController
Publish LaraSnap Config file.
Publish LaraSnap View files.
Publish LaraSnap Assets(css & js) files.
Add LaraSnap routes to application's routes\web.php file.

NOTE: Please do install the laravel authentication package(laravel/ui) before installing LaraSnap, if you completed LaraSnap installation already please run the LaraSnap installation again to fix the conflicts in Auth/LoginController & Auth/RegisterController.

When running the php artisan larasnap:admin-install command second time or multiple times, the older copy of the files will be removed & new copy of the files will be published from LaraSnap package, this causes application down if you modified any codes on the package published files. To overcome this, open the larasnap config file (config/larasnap.php) & turn off the config options larasnap.admin_install.* which you like not to perform & run php artisan larasnap:admin-install command.

Run composer dump-autoload to regenerates all classes that need to be included in the project.

Step Three

Once LaraSnap admin installation is completed successfully, run

php artisan migrate to migrate the LaraSnap migrations.
php artisan db:seed --class=LaraSnapSeeder to seed Default User, Admin Menu & Settings Seeder(modifying the default LaraSnap migration files may cause issue while seeding).

Once migration & seeding is completed, open the application's default User-Model (usually app/User.php) and make the class extend \LaraSnap\LaravelAdmin\Models\User instead of Authenticatable.

Refer Overriding Default User Model section(Point #3) for modifying the default User Model.

Specified key was too long error

If you see this error message you have an outdated version of MySQL. To fix this you have to edit your AppServiceProvider.php file and inside the boot method set a default string length

                use Illuminate\Support\Facades\Schema;
                
                public function boot()
                {
                Schema::defaultStringLength(191);
                }

Run php artisan storage:link Artisan command to create the symbolic link & its manadatory.

GENERAL NOTE: If you have removed public from the SITE URL, you can configure the asset URL by setting the ASSET_URL variable in your .env file instead of manually modifying all the asset() function. Eg: ASSET_URL = your_domain.com/public

Visit your_domain.com/admin to access admin panel.

LaraSnap default installation imports dummy data to the application, a user has been created for you with the following login credentials:

email: admin@admin.com

password: password

NOTE: LaraSnap general configs are added in the config/larasnap.php file. Feel free to modify the config values based on your needs.

To modify the laravel auth UI, use LaraSnap Auth UI Composer Package.

Core Concepts

User Management

The User Management module allows you to add, edit, view, delete user and assign role to user.

Role Management

LaraSnap comes with Roles, Permissions, Screens out of the box. Each User has a Role which has a set of Permissions and roles are mapped to screen. User can access the screen only if the role mapped to user, has privileage to access the screen.

Roles

The Roles module allows you to add, edit, delete roles, assign permissions to role and assign screens to role.

Permissions

The Permissions module allows you to add, edit, delete permissions.

Screens

The Screens module you to add, edit, delete screens, map screen to module and assign roles to screen.

NOTE: Assigning Roles to Screen is built with 2 way-binding mechanism, you can assign roles to screen (or) screens to role.

To check if a user has a certain role, you can use the helper userHasRole('admin') or the blade directive @userHasRole('admin'), admin is the name of the role.

Menu Management

With LaraSnap you can easily create menus for your application. In fact the LaraSnap admin is using the menu builder for the navigation you use on the left hand side.

You can add, edit, or delete any current menu. This means that you can create a new menu for the header, sidebar, or footer of your site. Create as many menus as you would like.

When you are ready to add menu items to your menu you can click on the builder button of the corresponding menu.

Menu Item accepts both Static URL & Dynamic Route for adding URL. Dynamic Route is recommended only for developers. Its manadatory to add parameters for the routes which requries parameters, missing the parameters or adding incorrect parameter will throw error in the application.

After creating and configuring your menu, you can easily implement that menu in your application. Say that we have a menu called main. Inside of any view file we could now output the menu by using the following code menu('main');.This will output your menu in a bootstrap(default) style.

If you need custom menu design for your web app you can pass a second argument to the menu display method telling it that you want to stylize the menu with custom styles like so: menu('main', 'custom'); and add the custom design file to the resources/views/menus/template/custom.blade.php (The blade name needs to match the second argument passed to the menu function).

NOTE: Menu Management is built with cache mechanism, this will cache the menu and avoid rendering the menu from DB on every request.

Category Management

With LaraSnap you can easily create/manage categories for any module instanlly & use them on them on the application

Parent Categories

The Categories module allows you to add, edit, delete parent categories and manage the categories mapped under it.

Site Settings

The Settings module allows you to configure any site wide settings you would like.

You can use the setting on the application on blade template, controller or on any other file by doing the following: setting('site_name') site_name is the name of the setting. Similary you can use the other settings, by adding the respective setting name to the helper.

Default Settings

Name	Usage
site_name	This setting is used to set name of the application. This name will be displayed on the header, footer, left sidebar on the admin panel & other sections where the site name is needed.
site_logo	This setting is used to set logo of the application. This logo will be displayed on the left sidebar on the admin panel & other sections where the site logo is needed.
admin_email	This setting is used to set admin email of the application.
date_format	This setting is used to set default date format of the application. This date format will be used when displaying date.
date_time_format	This setting is used to set default date & time format of the application. This date & time format will be used when displaying both date & time.
time_format	This setting is used to set default time format of the application. This time format will be used when displaying time.
entries_per_page	This setting is used to set entries per page limit on the list pages.(ie.)used to set how many entries needs to be displayed on the list pages.

Refer Adding additional settings section for adding custom settings to the application.

NOTE: LaraSnap also has an inbuilt user documentation within the package, with the summary of the Core Concepts.

Customization

Overriding Default User Model

LaraSnap removes name column from the default laravel users table & adds new table userprofiles for storing user additional information.
LaraSnap is designed to built admin panel with no global user registration but it doesn't stops you completely from registering through frontend(laravel default registeration), if you like to continue with the larasnap setup simply remove the name field from the default laravel registration form & you can use the frontend registeration form as well. If you like to modify the registeration flow, feel free to modify the application's Auth/RegisterController file(before modifying please view the DB Schema of the User Table).
Now, open the application's default User-Model (usually app/User.php) and make the class extend \LaraSnap\LaravelAdmin\Models\User instead of Authenticatable.

        class User extends \LaraSnap\LaravelAdmin\Models\User
        {
            // ...
        }

Also modify the $fillable array with the following code

    protected $fillable = [
        'email', 'password', 'status', 'created_by', 'last_login_at', 'last_login_ip',
    ];

Restricting Link or Button based on User Role

To restrict a link or button based on the user role on the blade file use @canAccess directive , the first parameter is the route name and its required.

    @canAccess('users.show')
           // link or button HTML goes here
    @endcanAccess

Here, if screen based authentication is set for the route(screen) users.show, only the users who have permission to view the screen can only view the HTML content added inside the directive.

Real Time Usage: If you have set screen based authentication for the User View screen, and added the link for the User View Screen on the User List Screen, now if you want to show this link only to the users who have permission for the User View Screen, you can wrap the User View Link with @canAccess directive.

Adding additional settings

If you want to add new setting to the application, follow below the steps

Add the setting name to the larasnap config file(config key - site_settings).
Create a new field in views/settings/create.blade.php file.
Create a new seeder for adding the setting name default value.

NOTE: The setting name added on the config file, form field name & value added on the seeder for this setting should be same.(Eg. admin_email - This name should be same on the 'config file', form field name & seeder(ie)value for the 'name' column on the table - settings).

DB Schema

LaraSnap database schema diagram. The below schema diagram represents the description of a database structure, tables, columns, data types, and the constraints on the database.

Releases

v1.0.0	Initial Release.
v1.1.0	Modified role based screen authentication logics to improve security.
v1.2.0	Added Module Management for grouping screens to module.
v1.3.0	Added Category Management.
v1.4.0	Performance Optimization.

Compatibility

Laravel 6.x

Laravel 7.x

LaraSnapDocs

Introduction