Skip to content

Quickstart ​

From an empty directory to the LeanShell with the SDK's own apps — the Launchpad, Partners and Settings — on a fresh Laravel install, in about fifteen minutes. Every command below is meant to be copied as it is.

You need PHP 8.4, Composer, and an install token for an installation that is entitled to the SDK. The fresh Laravel app uses SQLite, so there is no database server to set up.

Reading the docs is free. Installing the SDK needs a licence: buying it creates a new installation, and a token minted on that installation installs both laravelui5/core and laravelui5/sdk.

1. Create a Laravel app ​

bash
composer create-project laravel/laravel acme
cd acme

2. Install the SDK and a login ​

bash
composer config repositories.pragmatiqu composer https://packages.pragmatiqu.io
composer config --global http-basic.packages.pragmatiqu.io [email protected] YOUR-INSTALL-TOKEN
composer require laravelui5/sdk laravelui5/auth

The SDK pulls in Core and OData. laravelui5/auth (MIT, from Packagist) gives you a login screen — the SDK's apps run for signed-in users only.

3. Set up Core ​

Swap in the UI5-aware CSRF middleware in bootstrap/app.php:

php
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
use LaravelUi5\Core\Http\Middleware\VerifyCsrfToken;

// …
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(replace: [
            PreventRequestForgery::class => VerifyCsrfToken::class,
        ]);
    })

Publish Core's config and views:

bash
php artisan vendor:publish --tag=ui5-config
php artisan vendor:publish --tag=ui5-views

In resources/views/ui5/head.blade.php uncomment @includeIfSdk('ui5::head'), and in resources/views/ui5/foot.blade.php uncomment @includeIfSdk('ui5::foot'). These two lines put the shell around your apps.

4. Point Core at the SDK ​

In config/ui5.php, set these keys:

php
'registry'        => \LaravelUi5\Sdk\Ui5\SdkRegistry::class,
'context_factory' => \LaravelUi5\Sdk\Runtime\SdkUi5ContextFactory::class,

'middleware' => [
    'web',
    \LaravelUi5\Core\Http\Middleware\ResolveRequestLanguage::class,
    \LaravelUi5\Core\Http\Middleware\ResolveUi5Context::class,
    \LaravelUi5\Core\Http\Middleware\EnsureUi5Authenticated::class,
    \LaravelUi5\Sdk\Http\Middleware\CheckAuthMiddleware::class,
],

'odata_middleware' => [
    'web',
    \LaravelUi5\Core\Http\Middleware\ResolveRequestLanguage::class,
    \LaravelUi5\Core\Http\Middleware\FetchCsrfToken::class,
    \LaravelUi5\Core\Http\Middleware\ResolveODataEndpoint::class,
    \LaravelUi5\Core\Http\Middleware\EnsureODataAuthenticated::class,
    \LaravelUi5\Sdk\Http\Middleware\BindSdkContextForOData::class,
],

'artifact_resolvers' => [
    \LaravelUi5\Core\Runtime\PathBasedArtifactResolver::class,
    \LaravelUi5\Sdk\Shell\ShellContextArtifactResolver::class,
    \LaravelUi5\Sdk\Export\ExportArtifactResolver::class,
],

Configuration explains each one.

5. Name the home route ​

After logout, laravelui5/auth sends you to a route named home. Give Laravel's welcome route that name in routes/web.php:

php
Route::get('/', function () {
    return view('welcome');
})->name('home');

After login it sends you to dashboard. The SDK provides that route, and it lands on the Launchpad.

6. Connect users to partners ​

The SDK authorizes partners, not user accounts. Link each login to its partner:

bash
php artisan make:migration add_partner_id_to_users_table --table=users
php
public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        // unique — a partner holds at most one login
        $table->unsignedInteger('partner_id')->nullable()->unique()->after('id');
        $table->foreign('partner_id')->references('id')->on('sdk_partners')->nullOnDelete();

        $table->unsignedInteger('login_counter')->default(0);
        $table->boolean('is_locked')->default(false);
        $table->dateTime('last_login')->nullable();
        $table->boolean('must_change_password')->default(false);
    });
}

Then let app/Models/User.php implement the SDK's contract:

php
use LaravelUi5\Sdk\Partners\Contracts\HasPartnerInterface;
use LaravelUi5\Sdk\Partners\Traits\HasPartner;

class User extends Authenticatable implements HasPartnerInterface
{
    use HasPartner;
    // …
}

Make partner_id fillable, and cast the four new columns. Add these lines to what the model already has:

php
protected $fillable = [
    // 'name', 'email', 'password',
    'partner_id',
];

protected function casts(): array
{
    return [
        // 'email_verified_at' => 'datetime', 'password' => 'hashed',
        'login_counter'        => 'integer',
        'is_locked'            => 'boolean',
        'last_login'           => 'datetime',
        'must_change_password' => 'boolean',
    ];
}

The four status columns stay out of $fillable: a lock flag should never be mass-assignable from a form.

7. Migrate, write the operator, sync ​

bash
php artisan migrate
php artisan ui5:intake --name="Acme GmbH" [email protected]
php artisan ui5:sync

ui5:intake writes the organisation that runs this installation — the operator — and generates app/Installation.php with its key and the installation's values (country, currency, time zone, decimals). Check the values and commit the file. The command asks for the name and email if you don't pass them; every other detail stays empty unless you pass it as an option (see Installation and Tenant). ui5:sync then writes the catalog: the SDK's own apps, their abilities and roles, the default settings.

8. Seat yourself ​

bash
FIRST_CHAIR_PASSWORD=password php artisan ui5:tenant --operator \
  [email protected] --admin-first-name=Ada --admin-name=Admin \
  --password-env=FIRST_CHAIR_PASSWORD

ui5:tenant runs once per database. --operator makes Acme its own tenant — it runs the app for itself. The command writes the first person who can sign in: you, acting for Acme, with a login and the roles that open the Partners and Settings apps. The password comes from the environment variable you name, never from the command line. Everyone else you seat in the Partners app.

9. Build help and navigation, publish the shell ​

bash
php artisan ui5:help --all
php artisan ui5:nav
php artisan ui5:publish
  • ui5:help --all compiles the help that ships with the apps and builds the search index. The shell loads that index when it starts.
  • ui5:nav compiles the navigation rail into bootstrap/cache/ui5-nav.php.
  • ui5:publish copies the fonts and the fallback avatar to public/sdk, and seeds the CI logos into public/assets/ci/ — only if nothing is there, so your own branding is never overwritten. The shell bundle itself needs no publishing; the SDK serves it from the package.

10. Open it ​

bash
php artisan serve

Open http://localhost:8000/login and sign in as [email protected] with the password password. You land on the Launchpad. The navigation rail holds the Launchpad, Partners and Settings — the two admin apps are there because ui5:tenant gave you the roles of the operator's admin, local_admin among them.

Try the shell's keys: Cmd/Ctrl + K searches, Cmd/Ctrl + B toggles the rail, F1 opens the help.

11. Check the labels ​

ui5:nav already did: it stops when a rail entry has no label, and names the key and the app. Add the key to that app's i18n.properties and run it again. Switch the browser to German and reload — the rail follows the language. The rules behind the keys are on Navigation.

What's next? ​