Installation

This page is the reference for adding the SDK to a Laravel application. For a guided run from an empty directory to a working shell, follow the Quickstart.

Requirements

• PHP 8.4 or higher
• Laravel 13
• An SDK licence — it entitles an installation to laravelui5/sdk; your install token identifies that installation to the registry
• A database
• A login: SDK apps run for authenticated users, so the host needs a login route — laravelui5/auth or your own

Core and OData are installed automatically as dependencies.

1. Configure the package registry

The SDK is distributed via the private registry at packages.pragmatiqu.io — the same one Core comes from, so if Core is already installed this step is done. Let Composer register it:

composer config repositories.pragmatiqu composer https://packages.pragmatiqu.io

Use the command rather than editing composer.json by hand. Composer writes the entry as a named block and keeps that shape as you add repositories later — including the path repository each scaffolded UI5 app needs:

"repositories": {
    "pragmatiqu": {
        "type": "composer",
        "url": "https://packages.pragmatiqu.io"
    }
}

Composer accepts a second shape here, a plain list. Both are valid, but the section holds one value or the other, so mixing them is the one way to get this wrong: the second write replaces the first and takes the registry with it, and you find out one command later when Composer cannot find laravelui5/sdk at all.

2. Authenticate

Use Composer's HTTP-Basic credential store to bind your install token to the registry:

composer config --global http-basic.packages.pragmatiqu.io your-email@example.com YOUR-INSTALL-TOKEN

The token is the password; the username is the email on your account. This is the command the portal hands you with both halves filled in, the moment you mint a token — copy it rather than retyping it.

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. A token from your free Core installation does not reach the SDK, so mint a new one on the SDK installation. Same credential shape as Core — what differs is what the installation is entitled to pull.

3. Install the SDK

composer require laravelui5/sdk
composer require laravelui5/chiron --dev   # optional: guidelines for your coding agent

This pulls in Core and OData automatically.

The second line is optional and dev-only. laravelui5/chiron ships the guidelines and Agent Skills that Laravel Boost hands your coding agent, so it writes this stack instead of guessing at it. It takes one opt-in tick during php artisan boost:install — a scripted install takes nothing without it.

4. Set up Core

If Core is already running in this application, skip to step 5. Otherwise do Part 1 of the Core quickstart — swap in the UI5-aware CSRF middleware and publish Core's config and views:

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

Then switch on the SDK's shell. In resources/views/ui5/head.blade.php and foot.blade.php, uncomment the SDK lines:

@includeIfSdk('ui5::head')   {{-- in head.blade.php --}}
@includeIfSdk('ui5::foot')   {{-- in foot.blade.php --}}

5. Configure config/ui5.php

Point the registry, the context factory, both middleware stacks and the artifact resolvers at the SDK. The values are on Configuration.

6. Connect your users to partners

The SDK authorizes partners, not user accounts. Your users table links each login to its partner:

php artisan make:migration add_partner_id_to_users_table --table=users

public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        // unsignedInteger to match sdk_partners.id; unique — one login per partner
        $table->unsignedInteger('partner_id')->nullable()->unique()->after('id');
        $table->foreign('partner_id')->references('id')->on('sdk_partners')->nullOnDelete();

        // Login state, used when the Partners app creates logins for partners
        $table->unsignedInteger('login_counter')->default(0);
        $table->boolean('is_locked')->default(false);
        $table->dateTime('last_login')->nullable();
        $table->boolean('must_change_password')->default(false);
    });
}

partner_id must be unique

A partner holds at most one login, and the SDK's login seam depends on it: forPartner() returns a single record, while locking, resetting a password and deleting are where('partner_id', …) updates. Without the unique index two users rows can point at one partner, and a password reset meant for one person resets both. If you already ran this migration without it, add the index in a follow-up migration — after checking for duplicates.

Your User model implements the SDK's contract with the trait that ships with it:

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 login-state columns — login_counter to integer, is_locked and must_change_password to boolean, last_login to datetime. Keep the status columns out of $fillable: a lock flag should never be mass-assignable from a form. The Quickstart shows the lines.

7. Run the migrations

php artisan migrate

The SDK's migrations load automatically; every table carries the sdk_ prefix. Grant tables enforce explicit valid_from / valid_until timestamps.

8. Create the platform owner

php artisan ui5:intake --name="Acme GmbH" --email=office@acme.test

This creates the organisation that operates the installation — one per database — and must run before the first sync. It is idempotent, keyed on the email. --name and --email are required; it prompts for them when you don't pass them, and under --no-interaction their absence is an error. Every other detail stays empty unless you pass it. The System Actor lists them.

9. Sync the registry

php artisan ui5:sync

Sync projects Core's metadata and your modules' declarations into the database catalog. It is idempotent; add --dry to preview the changes without writing.

10. Seed the first people

Every person who signs in needs a partner, linked to their users row through partner_id, and the roles that open their apps. Further partners are created later in the Partners app; the first ones come from a seeder written for the company — the first step of every implementation. The First Seed lists what each person needs, and the Quickstart shows a minimal one.

That seeder runs on the QA system, which doubles as the customer's training platform. Once the customer signs off there, the whole database moves to production in the initial deployment — the go-live day.

11. Build help and navigation, publish the shell assets

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. Run it again when help documents change.
• ui5:nav compiles the navigation rail into bootstrap/cache/ui5-nav.php. Run it again after adding an app or changing its route labels.
• ui5:publish copies the icon fonts and the default avatar to public/sdk (the shell bundle is served from the package). Run it again after every SDK update; in CI use --force.

What's next?

• Quickstart — a guided run on a fresh Laravel install
• Configuration — every key you set by hand
• Mental Model — layering, time-aware authorization, one tenant per database