Installation

For upgrading from an earlier AppShell versions refer to the Upgrade section.

Requirements

As of AppShell v4.0, the requirements are:

• PHP 8.2 - 8.3
• Laravel 10.x, 11.x

Install AppShell

Either create a new Laravel project or go to an existing Laravel 10+ application's root folder and launch these commands:

composer require konekt/appshell
touch config/concord.php

Edit config/concord.php and add this content to it:

<?php

return [
    'modules' => [
        Konekt\AppShell\Providers\ModuleServiceProvider::class
    ]
];

If you have multiple Concord modules, AppShell typically needs to be the very first one in the list.

Test if it works by invoking the command:

php artisan concord:modules

Now you should see this:

+----+---------------------+------+----------+------------------+-----------------+
| #  | Name                | Kind | Version  | Id               | Namespace       |
+----+---------------------+------+----------+------------------+-----------------+
| 1. | Konekt AppShell Box | Box  | 4.3.0    | konekt.app_shell | Konekt\AppShell |
+----+---------------------+------+----------+------------------+-----------------+

TIP: Try php artisan concord:modules -a to see ALL modules

Configure .env, along with a database.

Afterwards run the migrations:

php artisan migrate

AppShell (with the underlying modules) contains ~20 migrations out of the box.

Laravel Auth Support

Auth Scaffolding

Depending on your needs, Laravel offers you several starter kits for authentication: https://laravel.com/docs/11.x/starter-kits

As a reference, here we're showing you how to install breeze with blade, but you can choose any other solution you like.

composer require laravel/breeze --dev

php artisan breeze:install

The User Model

AppShell offers a pre-built User model, that is an extended version of the default Laravel User class. It's not mandatory to use this class though, it's possible to use your own models instead.

To complete user setup, you have several options, see some of the variants below.

Variant 1 - Simple

Modify App\User so that it extends AppShell's user model:

// app/User.php
namespace App;

// No need to use Laravel default traits and properties as
// they're already present in the base class exactly as
// they're defined in a default Laravel installation
class User extends \Konekt\AppShell\Models\User
{
}

Add this to your AppServiceProviders's boot method:

   $this->app->concord->registerModel(\Konekt\User\Contracts\User::class, \App\User::class);

Variant 2 - Flexible

In case you don't want to extend AppShell's User class, then it's sufficient to implement its interface:

// app/User.php
// ... The default User model or arbitrary code for your app

// You can use any other base class eg: TCG\Voyager\Models\User
use Illuminate\Foundation\Auth\User as Authenticatable;
use Konekt\User\Contracts\Profile;
use Konekt\User\Contracts\User as UserContract;

class User extends Authenticatable implements UserContract
{
    // ...

    // Implement these methods from the required Interface:
    public function inactivate()
    {
        $this->is_active = false;
        $this->save();
    }

    public function activate()
    {
        $this->is_active = true;
        $this->save();
    }

    public function getProfile(): ?Profile
    {
        return null;
    }

    // ...
}

Add this to your AppServiceProviders's boot method:

   $this->app->concord->registerModel(\Konekt\User\Contracts\User::class, \App\User::class);

Variant 3 - No App\User

If the "final" user class is not going to be App\User then don't forget to modify model the configuration in your app's config/auth.php file:

    //...
    'providers' => [
        'users' => [
            'driver' => 'eloquent',
            // 'model' => App\User::class <- change this to:
            'model' => Konekt\AppShell\Models\User::class,
        ],
    //...

Create An Initial Super User

Run command php artisan make:superuser.

This will ask a several questions and create a proper superuser that you can start working with.

Frontend Installation

Since this package will be built along with your application, it's assets need to be added to it:

1. Add Admin's CSS To Laravel Mix:

   // webpack.mix.js
   mix.js('resources/js/app.js', 'public/js')
    // Add these 2 lines:
   .js('vendor/konekt/appshell/src/resources/assets/js/appshell.standalone.js', 'public/js/appshell.js')
   .sass('vendor/konekt/appshell/src/resources/assets/sass/appshell.sass', 'public/css')
    // Keep the the original assets if needed or remove them if AppShell's UI is the only one of your app

2. Install the following npm packages:

npm add [email protected] [email protected] popper.js

3. Compile the assets with mix: npm run dev

Next: Application Prerequisites »