PHPackages                             idei/usim - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. idei/usim

ActiveLibrary[Framework](/categories/framework)

idei/usim
=========

UI Services Implementation Model Framework

v0.12.0(1mo ago)040MITPHPPHP ^8.2CI passing

Since Mar 9Pushed 1mo agoCompare

[ Source](https://github.com/idei/usim)[ Packagist](https://packagist.org/packages/idei/usim)[ Docs](https://github.com/idei/usim)[ RSS](/packages/idei-usim/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (18)Versions (16)Used By (0)

USIM — UI Services Implementation Model
=======================================

[](#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
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [What Is New Since 0.5.0](#what-is-new-since-050)
- [Installation](#installation)
    - [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
    - [Screens](#screens)
        - [Screen Operational Model](#screen-operational-model)
    - [UI — The Component Factory](#uibuilder--the-component-factory)
    - [Event Handlers](#event-handlers)
    - [State Management](#state-management)
- [Available Components](#available-components)
- [Screens in Depth](#screens-in-depth)
    - [Creating a Screen](#creating-a-screen)
    - [Screen Discovery](#screen-discovery)
    - [Authorization](#authorization)
    - [Menu Integration](#menu-integration)
    - [Lifecycle Hooks](#lifecycle-hooks)
- [Event System](#event-system)
    - [Handling Button Actions](#handling-button-actions)
    - [Cross-Service Events](#cross-service-events)
- [Built-in UI Helpers](#built-in-ui-helpers)
- [Database Translations](#database-translations)
- [Modals & Dialogs](#modals--dialogs)
- [Data Tables](#data-tables)
- [File Uploads](#file-uploads)
- [Authentication Scaffolding](#authentication-scaffolding)
- [Testing Screens](#testing-screens)
- [Configuration](#configuration)
- [Headless Mode](#headless-mode)
- [API Endpoints](#api-endpoints)
- [Artisan Commands](#artisan-commands)
- [Octane / RoadRunner Support](#octane--roadrunner-support)
- [Directory Structure](#directory-structure)
- [Release & Upgrade Guide](docs/package-update-and-consumer-upgrade-guide.md)
- [License](#license)

---

Requirements
------------

[](#requirements)

DependencyVersionPHP^8.2Laravel10.x / 11.x / 12.x / 13.xlaravel/sanctum`^3.0` / `^4.0`spatie/laravel-permission^6.0symfony/finder`^6.0` / `^7.0`nikic/php-parser^5.7symfony/var-dumper`^6.0` / `^7.0`illuminate/contracts`^10.0` / `^11.0` / `^12.0` / `^13.0`---

What Is New Since 0.6.0 (v0.7.0)
--------------------------------

[](#what-is-new-since-060-v070)

- 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
------------

[](#installation)

```
composer require idei/usim
```

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

### Quick Start

[](#quick-start)

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

```
php artisan usim:install
```

Then follow the printed instructions:

```
php artisan migrate
php artisan db:seed --class=UsimSeeder        # creates default admin/user from .env
./start.sh [-r]
```

Starting the Application
------------------------

[](#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

[](#usage)

Note:

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

> Use `--force` to overwrite existing files.

---

Core Concepts
-------------

[](#core-concepts)

### Screens

[](#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

[](#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(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.

```