Ui5App

Introduction

A Ui5App is a frontend artifact in LaravelUi5 that encapsulates a reusable UI5 app developed outside the Laravel application. It bridges a deployed dist folder with backend metadata, versioning, and registry integration.

Each app is integrated into the Laravel app as part of a Ui5Module, and can later be discovered, versioned, and served through the LaravelUi5 registry.

📝 Note A module can contain either a UI5 app or a UI5 library — but never both. The Module is a namespace-keyed container; the App is its single root artifact. See Modules.

Conceptual Overview

LaravelUi5 supports importing fully built UI5 apps and wrapping them as native Laravel modules. This integration includes:

• A Ui5App is a first-class backend representation of a deployed UI5 application.
• It is located inside a dedicated LaravelUi5 module (e.g. ui5/Offers/) that must not mix in libraries.
• Each app implements Ui5AppInterface and is registered via a module in config/ui5.php.
• The app metadata is extracted directly from the frontend build (e.g. ui5.yaml, manifest.json, index.html, i18n.properties).
• A dedicated ServiceProvider is generated to bootstrap the module and register it with Laravel providers.
• A composer.json is created — package name, PSR-4 root, the service provider — so the module is a package the host requires from a path repository.

How to Generate

You can generate an Ui5App class using:

php artisan ui5:app Offers --create --package-prefix=acme --php-ns-prefix=Acme --vendor="Acme GmbH"

This assumes a source folder exists next to the host in one of the following forms:

../ui5-offers/           ← LaravelUi5 naming convention, always searched
../com.acme.offers/      ← SAP Easy UI5 convention, searched with --js-ns-prefix=com.acme

The generator runs npm run build for you by default. Pass --no-build to skip it (useful when you've just built and want to re-import only).

⚠️ Patch the lib dependencies after yo easy-ui5 The Easy UI5 generator scaffolds a minimal source project declaring only sap.ui.core and sap.m under sap.ui5.dependencies.libs. If your app renders a Dashboard — or any other LaravelUi5 server-emitted control that materialises a Card, Chart, or grid container — add sap.f to that map. Core's Dashboard control walks vocabulary entries like sap.f.GridContainer, sap.f.Card, and sap.f.cards.Header that all live in the sap.f library. If the dashboard also embeds integration cards, add sap.ui.integration as well. The same libraries must also be declared in ui5.yaml (and the sibling ui5-dist.yaml / ui5-coverage.yaml files) under framework.libraries; manifest.json alone fails at runtime with failed to load 'library.js'. Both declarations are required: manifest.json drives the application-side load contract; the ui5*.yaml files drive build-time resolution. Treat the patch as the first thing you do after each fresh yo easy-ui5 scaffold. php artisan ui5:doctor checks both places and names the library and the file that miss it.

Options

Option	Description
--create	Scaffold new app module (fails if it already exists)
--refresh	Update an existing app module (fails if it does not exist)
--no-build	Skip the UI5 build before importing assets (build runs by default)
--package-prefix=	Required on --create. Composer vendor of the package, e.g. acme
--php-ns-prefix=	Required on --create. PHP namespace prefix, e.g. Acme or Acme\Erp
--vendor=	Required on --create. The vendor name of the module, e.g. "Acme GmbH"
--js-ns-prefix=	Optional. Also look for an Easy UI5 source folder, e.g. com.acme → ../com.acme.offers/

⚠️ Pass --create or --refresh explicitly. Without either, the command only reports whether the module exists, names the flag to use, and exits with an error.

⚠️ The three identity options have no defaults. They name your vendor, so the generator will not guess them: a --create without them aborts before doing anything, names every missing option and prints a complete command line. They end up in source written once — the Composer package name (acme/offers), every PHP namespace (Acme\Offers\…), the app's vendor — which makes them expensive to change later, so the friction sits here, at the one moment where it costs a command line. A package prefix Composer would refuse (Acme) or a PHP prefix that is no namespace aborts too. --refresh needs none of them.

changed in 3.0The generator no longer falls back to our own vendor names.

The UI5 namespace is not among them: it comes from the source project's sap.app/id, which is why --js-ns-prefix only widens the search for the source folder.

Identity coordinates survive --refresh

A UI5 app's PHP namespace and version are identity coordinates — the same @{ver} segment that drives the routing URL (/ui5/app/{ns}@{ver}/…) is also pinned in the dev vhost proxy and built-asset paths. The namespace lives on the App leaf (OffersApp.php), the version on the module (OffersModule.php) since 7.0; --refresh rewrites neither, so both survive by construction rather than by parsing. The generator still reads the PHP namespace back out of the leaf — the regenerated base must carry the same namespace declaration, and it is the source-registration key — and aborts if it can't be parsed rather than clobber. Source-derived fields (title, description, bootstrap attributes, head script / CSS) refresh into the base after the rebuild.

ui5:app --create writes the module's initial version from the source's sap.app/applicationVersion (a placeholder such as ${version} becomes 1.0.0). After that the version is yours: bump it with every release that changes a served file — a built file is kept by browsers for good under its version — and ui5:doctor reports a change you forgot to bump (core.W7).

resources/ui5/ is generated — edit the source project

Everything under the module's resources/ui5/ is output. --refresh rebuilds the UI5 project and re-imports dist/ wholesale, manifest.json included. That is the point: a new route, a new dependency, a changed sap.ui5 section lands in the host module because it was declared in the app, and no one has to remember a second place.

The cost of that guarantee is that the copy is not a place to write:

A hand-edit in ui5/<Name>/resources/ui5/manifest.json survives exactly until the next --refresh.

It will not error, and it will not warn. The file is simply overwritten with what the source produced, and the edit is gone. The same holds for i18n/*.properties, Component-preload.js, and every other imported asset.

So make the change where it is authored, in the UI5 project:

ui5-offers/webapp/manifest.json     ← here
ui5/Offers/resources/ui5/manifest.json   ← not here (generated)

then ui5:app <Name> --refresh to deliver it. It runs npm run build at first so your dist is always uptodate. If a value seems to belong only to the host and not to the app, it is a sign it belongs in the Laravel-side manifest fragment (<Name>Manifest.php) instead — that file is src/, it is yours, and --refresh does not touch it.

Two things that are not exceptions to this rule, because they are not hand-edits:

• Identity coordinates (PHP namespace, version) live on the App leaf, which --refresh never rewrites, as described above.
• OData dataSources / models are injected into the served manifest at runtime by Core. You never write them into either copy.

Output

Upon successful execution, the following artifacts are generated inside the Laravel project:

ui5/Offers/
├── composer.json               ← Composer package file
├── src/
│   ├── OffersApp.php           ← App leaf — yours, written once, never regenerated
│   ├── OffersAppBase.php       ← Framework-owned base — rewritten on every `--refresh`
│   ├── OffersManifest.php      ← Laravel-side manifest fragment
│   ├── OffersModule.php        ← Module wrapper (the container)
│   └── OffersServiceProvider.php  ← ServiceProvider class
└── resources/ui5/              ← UI5 assets (preloads, i18n, etc.)

The build assets are copied from the dist/ folder.

Metadata Resolution

LaravelUi5 reads app metadata from the following locations in the source folder:

Source file	Extracted data
ui5.yaml	JS namespace, OpenUI5 version → getUi5Version() (see configuration)
package.json	The build script the generator runs
webapp/manifest.json	UI5 namespace (sap.app.id), sap.ui5 section
webapp/index.html	Bootstrap data-sap-ui-* attributes, inline JS/CSS
webapp/i18n/i18n.properties	appTitle, appDescription
dist/i18n/*.properties	All files copied into Laravel resources/ui5/i18n/

Metadata is read from the authoring webapp/; the assets that land in resources/ui5/ (manifest.json, Component-preload.js, the i18n bundles) are copied from dist/ — which is why ui5:app runs npm run build first unless you pass --no-build.

Class Structure

The App is a base/leaf pair

ui5:app does not scaffold one App class but two, split along a single line: who owns the file.

File	Owner	Written	Carries
OffersAppBase.php	Framework	on --create and every --refresh	everything derived from the UI5 source build
OffersApp.php	You	on --create only, never again	identity, wiring, and everything you author

The split exists because a --refresh has to re-sync source-derived state after a UI5 rebuild, and the old single mixed-ownership App class made that write reach hand-authored code as well. Now the refreshing write cannot reach your class at all: it targets a different file.

⚠️ Never hand-edit OffersAppBase.php. It is regenerated from the UI5 source on every --refresh, silently and without warning — the same contract as resources/ui5/. To customise a base member, override it in the leaf, where plain inheritance keeps it through every refresh.

OffersAppBase.php — framework-owned

abstract class OffersAppBase extends AbstractUi5App
{
    public const string TITLE       = 'Offers';
    public const string DESCRIPTION = 'Customer offer catalog and authoring tools.';

    public function getUi5BootstrapAttributes(): array { /* from index.html */ }
    public function getAdditionalHeadScript(): ?string { /* inline <script> */ }
    public function getAdditionalInlineCss(): ?string  { /* inline <style> */ }
}

It extends AbstractUi5App (which extends LaravelUi5\OData\ODataService) and implements Ui5AppInterface. Every UI5 app is therefore also a backend OData service: the same artifact serves both /ui5/app/{ns}@{ver}/… and /odata/{ns}@{ver}/….

The members it declares are exactly the ones that change when the UI5 project changes:

Member	Re-synced from
TITLE / DESCRIPTION	i18n.properties (appTitle, appDescription)
getUi5BootstrapAttributes()	the sap-ui-bootstrap script tag in index.html
getAdditionalHeadScript()	inline JS in index.html
getAdditionalInlineCss()	inline CSS in index.html

That is the whole base. Add a sap.* library, change the bootstrap, retitle the app — one --refresh and the host module agrees again, with nothing of yours at risk.

OffersApp.php — the leaf, yours

class OffersApp extends OffersAppBase
{
    public const string NAMESPACE = 'com.acme.offers';

    public function getResourceNamespaces(): array
    {
        return ['com.laravelui5.core'];
    }

    public function getLaravelUiManifest(): string
    {
        return OffersManifest::class;
    }

    public function getVendor(): string
    {
        return 'Acme GmbH';
    }
}

Identity is declared as class constants — NAMESPACE here on the leaf, TITLE and DESCRIPTION on the base. The three getters (getNamespace(), getTitle(), getDescription()) come from the HasArtifactIdentity trait used by AbstractUi5App. The constants are intrinsic identity; the methods are the app's runtime contribution. changed in 7.0The version is not the app's: it is the module's VERSION, read through getModule()->getVersion().

Member	Purpose
NAMESPACE	the UI5 namespace — the {ns} of every route, and the module's namespace via getArtifactRoot()
getResourceNamespaces()	non-sap.* libraries the app needs (e.g. com.laravelui5.core), wired server-side because the LaravelUi5 manifest is server-generated
getLaravelUiManifest()	FQCN of the Laravel-shaped manifest fragment (actions, settings, …)
getVendor()	vendor string, surfaced via VendorTaggedInterface

This is also where everything you author later belongs, and where it is safe: an #[Access] attribute gating the app, a configure(EdmBuilderInterface $builder) body registering entity sets, or an override of any base member.

Methods provided further up — getModule(), getSource(), getManifestPath(), getType() (returns CoreArtifactType::Application), and the identity getters — are not re-declared in either generated class. Override them only when you have a specific reason.

Migrating a pre-split app

An app scaffolded before the split is a monolith leaf with no base. Running --refresh on it is non-destructive: the base is created from the current source, the existing leaf is left byte-for-byte untouched, and the command prints a short manual of what to do. Until you act, the leaf's own definitions harmlessly shadow the base and nothing breaks. To finish:

1. make OffersApp extend OffersAppBase instead of AbstractUi5App;
2. delete the now-shadowed source-derived members from the leaf — TITLE, DESCRIPTION, getUi5BootstrapAttributes(), getAdditionalHeadScript(), getAdditionalInlineCss();
3. keep everything else: NAMESPACE, getResourceNamespaces(), getLaravelUiManifest(), getVendor(), and anything you authored — and move VERSION to the module (Core 7).

OffersModule.php

Implements Ui5ModuleInterface via AbstractUi5Module. The Module is the namespace-keyed container — it names the App as its root in ARTIFACT_ROOT, derives its namespace from the App's NAMESPACE constant (getArtifactRoot()->getNamespace()), and names its sub-artifacts in ARTIFACTS — see Ui5Module. changed in 4.0The module used to expose one getter per kind (getCards(), getActions(), …).

The Module is not itself an artifact — it implements neither ArtifactInterface nor declares getType(). It carries the version every artifact it holds runs under:

class OffersModule extends AbstractUi5Module
{
    public const string ARTIFACT_ROOT = OffersApp::class;
    public const string VERSION       = '1.0.0';

    public const array ARTIFACTS = [
    ];
}

OffersServiceProvider.php

Standard Laravel ServiceProvider for registering classes and services scoped to the module (the per-app …Manifest binding, action handlers, providers, …).

OffersManifest.php

Extends AbstractManifest; returns the per-module Laravel-side manifest fragment (actions, settings, resources, reports, …). Returned by OffersApp::getLaravelUiManifest() and injected into the served manifest.json under laravel.ui5.

Module Integration

Each app is part of a domain-specific module. Modules are registered as a class-only array in your application's config/ui5.php — the registry derives every namespace from the module's root artifact (i.e. from OffersApp::NAMESPACE):

// config/ui5.php
return [
    'modules' => [
        \Acme\Offers\OffersModule::class,
    ],
];

No keyed slugs; the namespace is single-sourced from the App class.

Best Practices

• Use CamelCase names for apps (e.g. Offers, BudgetPlanner).
• Always run npm run build before executing ui5:app — or let ui5:app build for you (default).
• Provide meaningful values for appTitle and appDescription in i18n.properties.
• Register your app module in config/ui5.php right after generation.
• Avoid mixing libraries and apps in the same module.
• Never hand-edit <Name>AppBase.php — write in the leaf <Name>App.php, and override a base member there if you need to.
• Bump the module's VERSION with every release that changes a served file, and only then; run ui5:doctor before you tag.

Related Links

• Modules
• Parameters, Settings, Slots
• Artifacts Overview