Download the PHP package idei/usim without Composer

USIM — UI Services Implementation Model

A Server-Driven UI framework for Laravel. Define your entire user interface in PHP — screens, menus, forms, tables, modals — and let the framework render, diff, and update everything automatically on the client.

Table of Contents

• Requirements
• What Is New Since 0.5.0
• Installation
  • Quick Start
• Core Concepts
  • Screens
  • Screen Operational Model
  • UI — The Component Factory
  • Event Handlers
  • State Management
• Available Components
• Screens in Depth
  • Creating a Screen
  • Screen Discovery
  • Authorization
  • Menu Integration
  • Lifecycle Hooks
• Event System
  • Handling Button Actions
  • Cross-Service Events
• Built-in UI Helpers
• Database Translations
• Modals & Dialogs
• Data Tables
• File Uploads
• Authentication Scaffolding
• Testing Screens
• Core Contracts & Mockable Architecture
• Configuration
• Headless Mode
• API Endpoints
• Artisan Commands
• Octane / RoadRunner Support
• Directory Structure
• Release & Upgrade Guide
• License

Requirements

What Is New Since 0.6.0 (v0.7.0)

• Container appearance API: ->card() and ->plain() fluent helpers on Container to switch between card and flat visual variants.
• Container tabs API: ->tabs(), ->tabItem(), ->activeTab(), ->onTabChange(), ->onTabClose() and ->tabColors() allow server-driven tab strips with theme-aware defaults, disabled tabs, closable tabs, and per-tab color overrides.
• Carousel and calendar components consume CSS theme tokens for consistent light/dark styling.
• Bug fix: Screen now always persists state after postLoadUI(), fixing stale cache on ?reset=true reloads.
• Bug fix: Checkbox checked state now syncs correctly from incremental server responses.

For the full release details, see CHANGELOG.md.

Installation

Laravel's package auto-discovery will register UsimServiceProvider automatically.

Quick Start

Run the install command to scaffold a complete working application with authentication, profile, menus, configuration, and routes:

Then follow the printed instructions:

Starting the Application

The ./start.sh script uses RoadRunner instead of Laravel's artisan serve command. This is necessary because artisan serve is single-threaded and does not properly support the framework's concurrent execution requirements.

Usage

Note:

Visit http://localhost:8000 — you have a working USIM app.

Use --force to overwrite existing files.

Core Concepts

Screens

A Screen is a PHP class that defines a full page. Each screen extends Screen and builds its UI inside buildBaseUI():

Screen Operational Model

In USIM, treat a Screen as a stateful backend UI service, not as a passive template:

• A Screen owns UI structure, interaction rules, and persisted state.
• buildBaseUI() defines the initial component tree.
• getRoutePath() derives the canonical URL from namespace/class naming.
• Event actions resolve to on<ActionName>(array $params) handlers on the same class.
• Request cycle is: restore state -> run handler -> compute diff -> send only delta.
• Authorization is part of the Screen contract (authorize, checkAccess).
• Menu metadata also belongs to the Screen contract (getMenuLabel, getMenuIcon, getRoutePath).

This model keeps backend as the source of truth and avoids business-logic duplication across client and server.

Important clarification: USIM does not register one Laravel route per Screen class. Instead, it uses a catch-all web route plus a generic /api/ui/{screen} loader and resolves URL <-> Screen class through naming convention.

After creating the file, register it:

Then visit /hello-screen in your browser.

UI — The Component Factory

UI is a static factory that creates component builders. Every builder uses a fluent API:

Event Handlers

When a button fires an action (e.g. ->action('save_form')), the framework calls a handler method on the same screen class. The convention is on + PascalCase action name:

The $params array contains all current component values (inputs, selects, checkboxes, etc.) from the client.

State Management

Screen state is server-side. The framework automatically:

1. Builds the UI tree on first load
2. Stores the serialized state
3. On events, restores state → runs your handler → diffs old vs new → sends only the delta to the client

Properties prefixed with store_ are persisted across requests and mirrored on the client as part of the USIM storage payload.

Persistence is now plain by default:

• store_* values are serialized as regular JSON values so the client can inspect and use them directly.
• Add the _crypt suffix only for sensitive values that must be protected before being sent to client storage.
• Browser clients persist storage in sessionStorage (scoped per browser tab) and send X-UI-Client-Id alongside X-USIM-Storage, guaranteeing state and authentication isolation across tabs.
• This makes client-side decisions possible for non-sensitive state such as store_theme, and also enables finer-grained storage synchronization because the client can apply only the changed keys instead of replacing one fully encrypted blob each time.

Use _crypt only when the value should not be readable from client storage.

Available Components

Builders share a fluent API across UIComponent and Container with common methods like:

Screens in Depth

Creating a Screen

1. Create a class in app/UI/Screens/ (or a subdirectory):

2. Run discovery:

3. Visit /products/list — the URL is automatically derived from the namespace path.

Screen Discovery

USIM uses Symfony Finder to scan the configured screens directory and generates a manifest cache:

The manifest maps URL slugs to screen classes using a CRC32-based offset system for deterministic component IDs.

Authorization

Override authorize() to control access:

When authorization fails, the framework automatically redirects to login (for guests) or shows a 403 (for insufficient permissions).

Menu Integration

Screens integrate with the navigation menu via static methods:

Then in your Menu screen, use $menu->screen(MyScreen::class) for automatic linking with permission checks:

Lifecycle Hooks

Component auto-injection: If you declare a typed property with the same name as a component ID, USIM automatically injects the builder instance. For example, protected Input $input_name; will be populated with the input created as UI::input('input_name').

Event System

Handling Button Actions

Cross-Service Events

Emit events that ALL active screen services receive using UsimEvent:

Any screen with a matching handler will react:

Built-in UI Helpers

Available inside any Screen handler:

Labels can now render raw HTML or an existing Blade view:

Most components also support anchor-based positioning helpers for floating or pinned UI:

Database Translations

USIM now supports package-level database translations with key-based identifiers and language fallback.

Published migration stubs create these tables:

• usim_languages
• usim_text_keys
• usim_text_values

The TranslationService manages CRUD for languages, keys, and values (including optional media fields).

Global utility helper:

Resolution order:

1. current locale in DB
2. fallback locale in DB (en by default)
3. key literal

Translation values support placeholders (:name, :count, etc.) and optional media metadata (media_url, media_meta).

Auto-key behavior for human-readable text (t('Some text')):

• key length limit is configurable via usim.i18n.auto_key_max_length (env: USIM_I18N_AUTO_KEY_MAX_LENGTH, default 20)
• when truncation is needed, USIM tries to continue to the next separator so the current word is not cut mid-word
• escaped and real line breaks are normalized before key generation and fallback text storage

I18n suggestion logging:

• when a key is auto-generated from human-readable text, USIM emits an i18n warning suggesting to replace the literal text with the generated key
• log context includes generated key, source text, group, file, line, and best-effort character position
• configure channel with usim.i18n.log_channel (env: USIM_I18N_LOG_CHANNEL, default i18n)
• enable/disable with usim.i18n.log_autokey_suggestions (env: USIM_I18N_LOG_AUTOKEY_SUGGESTIONS, default true)

Recommended key naming for package and scaffolded code:

• usim.component.* for reusable package component defaults.
• usim.dialog.* and usim.time_unit.* for framework-level dialog and timer labels.
• usim.common.* for shared scaffold labels/placeholders.
• usim.auth.*, usim.admin.*, usim.menu.* for generated screen/component UI text.
• usim.service.* for scaffolded service response and validation messages.

When adding or changing scaffold text, prefer t('...') with one of the namespaces above and include the key in UsimTranslationSeeder.

Modals & Dialogs

Quick Confirmation Dialogs

Use ConfirmDialog for standard dialogs:

Dialog types: INFO, CONFIRM, WARNING, ERROR, SUCCESS, CHOICE, TIMEOUT.

Custom Modals

Build custom modal content using any component and set ->parent('modal'):

Data Tables

For paginated server-side data tables, extend AbstractTableModel:

Then use it in your screen:

File Uploads

Use the Uploader for file uploads with temporary storage, preview, and image cropping:

In your event handler, confirm the upload to move it from temporary to permanent storage:

Temporary uploads are automatically cleaned up hourly via a scheduled job.

Image placeholders

An Image without a src receives a generated placeholder by default. The default generator creates an SVG locally using the component caption and configured colors. Its dimensions use pixel-sized width/height when provided, or the configured placeholder dimensions; AspectRatio fills in a missing dimension:

For images saved by USIM's upload flow, storage() resolves a relative filename with UploadService::fileUrl(). Absolute URLs and root-relative paths remain unchanged:

placeholderId() provides a stable identity for seeded image services. To use Picsum, set USIM_IMAGE_PLACEHOLDER_GENERATOR to Idei\Usim\Services\ImagePlaceholders\PicsumImagePlaceholderGenerator; the URL uses the configured seed prefix and the same identity to return a stable image. To integrate another image API (including one requiring an API key), implement ImagePlaceholderGeneratorInterface and configure its fully-qualified class in USIM_IMAGE_PLACEHOLDER_GENERATOR, or bind that interface in the application.

The available .env settings are USIM_IMAGE_PLACEHOLDER_ENABLED, USIM_IMAGE_PLACEHOLDER_WIDTH, USIM_IMAGE_PLACEHOLDER_HEIGHT, USIM_IMAGE_PLACEHOLDER_BACKGROUND, USIM_IMAGE_PLACEHOLDER_TEXT_COLOR, and USIM_IMAGE_PLACEHOLDER_SEED_PREFIX. An explicit src always takes precedence; an action-based image shows its placeholder while the request is in progress. fallback() remains the separate behavior for a source that fails to load.

Authentication Scaffolding

php artisan usim:install provides a complete authentication and admin system:

Supporting files:

• AuthController — API endpoints for register, login, logout, verify email, reset password
• UsimUser trait — Custom notification methods for password reset and email verification
• UserService — Full user management: find, get, create, update (with role sync, email validation, notifications)
• Default root/admin/user provisioning is now handled during php artisan usim:install through config-driven database upsert.
• EventServiceProvider — App-level event/listener registration scaffold
• Email view stubs — Styled Blade views for password reset and email verification emails
• Terms view — Blade view for terms and conditions display
• Migrations — temporary_uploads, profile_image column, and terms_accepted_at column on users table

Default Users (via .env)

After install, configure your .env:

The installer now provisions the default access data during php artisan usim:install; no separate package seeder is required.

Testing Screens

This package ships a self-contained testing guide under docs/:

• docs/SCREEN_TESTING_GUIDE.md — Human-oriented guide with patterns, helpers, and examples.
• docs/tests_prompt.md — Copy/paste prompt template to ask any agent/chat to generate new screen tests.

Recommended workflow:

1. Read the guide to follow the project conventions (uiScenario, component-level assertions, response contracts).
2. Use docs/tests_prompt.md as a base when delegating test generation to an AI agent.
3. Validate locally with php artisan test (or file-level execution first).

Core approach used across this project:

Core Contracts & Mockable Architecture

USIM is decoupled from the host application using Dependency Inversion (DIP). The core package never depends on host models like App\Models\User or concrete database libraries directly. Instead, it relies on strict interfaces in Idei\Usim\Contracts:

In-Memory Testing with Mocks

Because screens authorize via ScreenAuthorizerInterface, you can test authorization in unit tests without database migrations, seeds, or Spatie permissions:

Configuration

Publish the config file (done automatically by usim:install):

This creates config/usim.php:

Headless Mode

USIM can run in headless mode, serving API endpoints only without requiring a web renderer.

Configuration

Set the environment variable:

Behavior

• When USIM_HEADLESS_MODE=true: Requests to the web catch-all route return 406 Not Acceptable with JSON error
• All clients must consume /api/ui/{screen} and /api/ui-event endpoints directly
• API endpoints function identically in both modes
• Ideal for backend-driven applications, AI agents, mobile apps, or multi-client architectures

Example (Node.js/JavaScript Client)

Example (PHP Client)

API Endpoints

USIM registers these routes automatically:

The client-side JavaScript (ui-renderer.js) handles these calls automatically.

Artisan Commands

Octane / RoadRunner Support

USIM is compatible with long-running processes. The service provider automatically resets the component ID generator on each request when laravel/octane is detected:

The UIChangesCollector is registered as a scoped singleton, ensuring clean state per request.

Directory Structure

After usim:install, your application will have:

The package itself lives in vendor/idei/usim/ (or packages/idei/usim/ during development).

License

MIT