Search by

MIDDAG UI contract builders — transport-agnostic PageContract system for contract-driven rendering


README

middag-io/ui

Transport-agnostic PHP contract builders — describe a page once, render it anywhere.

Documentation · What it does · GitHub

CI License: Apache 2.0 PHP PHPStan

Packagist Version Packagist Downloads

Transport-agnostic PHP contract builder system for MIDDAG's contract-driven UI. Produces PageContract (JSON) consumed by @middag-io/react via Inertia or any transport layer.

Zero external dependencies. PHP 8.3+ only.

Open source — Apache-2.0. The foundation layer of the MIDDAG framework stack (ui → framework → moodle / wordpress adapters; @middag-io/react on the client). Host-agnostic and transport-agnostic by design: this package knows nothing about Moodle, WordPress, or any transport — it only describes pages.

Note

Documentation: https://docs.middag.dev/framework/explanation/ui/overview — the hub is the reference; this README is a summary.

What It Does

Pages in the MIDDAG stack are described by a PageContract — a JSON document declaring shell, page metadata, layout template, regions, and blocks. This library provides the PHP side: builders that produce that document. The React side (@middag-io/react) consumes it to render the actual UI.

This means PHP never renders HTML for pages — it declares structure, and React renders.

Features

Feature What you get
Transport-agnostic contracts Builders produce JsonSerializable → PageContract (JSON). No Inertia/transport dependency; works with any wire.
Zero dependencies PHP ^8.3 only. Consumers inherit no transitive packages.
Host-agnostic No Moodle / WordPress / mform / capability coupling. Host-specifics live in the adapter, never here. tests/Architecture/HostVocabularyTest.php scans src/ and schema/, comments included, for host vocabulary.
3 levels of composition Convention (CrudBuilder) → convention + overrides → free composition (PageBuilder).
CRUD convention builder index/create/edit/show pages from an entity class: i18n titles, filters, search, per-action capability gating.
Block types denseTable, formPanel, detailPanel, metricCard, emptyState, statusStrip, activityTimeline, markdownPanel, cardGrid, actionGrid, linkList, chart, tabs — via BlockBuilder or the fluent RegionBuilder.
Typed value objects final readonly + JsonSerializable. camelCase wire keys, omit-empty payloads, immutable witters.
Partial fragments Server-push slices: Fragment, RegionUpdate, ActionResult (push + pull), ResourcePatch.
Navigation tree 3-level NavigationNode (group / section / item), capability-filtered, drill-down + collapsible.
Form system Contracts + VOs (FieldDefinition, Condition, FormState, Section, Group). Renderers live in adapters.
i18n intents Translatable {key, domain, params}. The library never resolves translations — the client does.
Quality gates Full test suite, high coverage, PHPStan L6, php-cs-fixer, Rector — enforced per commit.

Three Levels of Composition

Level 1 — Convention (CrudBuilder)

Full CRUD pages from an entity class name:

// index page with default columns, actions, pagination
$contract = PageBuilder::crud(Invoice::class)->build('index', [
    'rows' => $invoices,
    'pagination' => ['page' => 1, 'perPage' => 25, 'total' => 100, 'lastPage' => 4],
]);

Level 2 — Convention + Overrides (CrudBuilder)

Customize columns, actions, layout without leaving the convention:

$contract = CrudBuilder::for(Invoice::class, slug: 'invoices')
    ->without('show')
    ->columns(['number', 'status', 'amount', 'due_date'])
    ->column('status', fn (array &$col) => $col['variant'] = 'badge')
    ->filters([new FilterDefinition(key: 'status', label: 'Status')])
    ->searchable()                        // or mark a column searchable in its configurator
    ->sort('due_date', 'asc')
    ->perPage(50)
    ->i18n(domain: 'local_app')          // titles as i18n intent; falls back to literal nouns
    ->label('Invoice', 'Invoices')        // or override the noun explicitly
    ->build('index', ['rows' => $invoices]);

Row actions take convention names or ready actions with any target, and page() hands over the underlying PageBuilder for anything the convention does not cover (shell, subtitle, extra regions, the editable panel). Use toProps() instead of build() when the page declares settings that travel next to the contract, such as the editable panel:

$props = CrudBuilder::for(Agent::class, slug: 'agents')
    ->columns(['name', 'role', 'workload'])
    ->column('role', fn (array &$col) => $col['variant'] = ColumnVariant::Badge)
    ->rowActions([new Action(id: 'edit', label: 'Edit', target: ActionTarget::panel()), 'delete'])
    ->rowHref('/agents/{id}')
    ->page(fn (PageBuilder $page) => $page
        ->layout('dashboard')                 // renders the `metrics` region above `content`
        ->subtitle('Who answers tickets')
        ->region('metrics', fn (RegionBuilder $r) => $r->metricCard('agents', 12, 'Agents'))
        ->editablePanel('/agents/{id}/panel'))
    ->toProps('index', ['rows' => $agents]);   // ['contract' => PageContract, 'editablePanel' => ...]

The class basename is treated as a singular noun. The library never fabricates a plural: the slug defaults to the singular, and for(class, slug:) overrides it for a plural URL. Titles resolve via ->label() (explicit) → <key>_plural i18n convention → singular fallback; create/edit verbs are emitted as crud_create/crud_edit intents in a shared UI domain.

Level 3 — Free Composition (PageBuilder)

Full control over every block and region:

$contract = PageBuilder::page('invoices.show')
    ->title('Invoice #1234')
    ->subtitle('Due Jan 31')
    ->shell('product')
    ->layout('split')
    ->breadcrumbs(fn ($bc) => $bc->item('Invoices', '/invoices')->current('#1234'))
    ->actions([
        PageBuilder::action('pay', 'Mark Paid', ActionTarget::request('/invoices/1234/pay'), ActionIntent::PRIMARY),
    ])
    ->region('content', [
        BlockBuilder::detailPanel('invoice.detail', $sections),
    ])
    ->region('aside', [
        BlockBuilder::activityTimeline('invoice.activity', $groups),
    ])
    ->build();

Inertia Props

When you need overlay or help panel metadata alongside the contract:

return $this->inertia('Page', PageBuilder::page('orders.create')
    ->title('New Order')
    ->overlay()
    ->help('Creating an order', 'Fill in the details below.')
    ->inspector('/api/products/{id}')
    ->toProps());
// toProps() returns: ['contract' => ..., 'overlay' => true, 'help' => [...], 'inspector' => ...]

Partial Fragments (server push)

A page can be served two ways, and both share one envelope contract (ContractEnvelopeInterface, carrying the same version):

  1. Full page in PHP — PageContract declares the whole page (shell, layout, regions, blocks). The default.
  2. Page owned by the client, partial props from PHP — when React owns the layout, the server returns a Fragment: one ready, self-describing slice of the contract (a block, a table, a region update, notifications) plus its routing kind. A fragment is a node of the contract with its own header, not a smaller page.
use Middag\Ui\Region\Fragment;
use Middag\Ui\Region\RegionUpdate;

// after a filter/paginate, swap a region's content without reloading the page
$fragment = Fragment::region(RegionUpdate::replace('orders', $block1, $block2));
// {version: '1', kind: 'region', payload: {region: 'orders', mode: 'replace', blocks: [...]}}

RegionUpdate modes: replace / append / prepend / remove (by key) / update (match by key).

Mutations return an ActionResult, which carries both update strategies — push and pull:

use Middag\Ui\Action\ActionResult;

return new ActionResult(
    fragments: [Fragment::table($tableConfig)],   // push: server already built the fresh piece
    refreshBlocks: ['sidebar'],                    // pull: client re-fetches these keys itself
);

A ResourcePatch rides along on a Fragment or ActionResult to push a partial change to preferences / capabilities / feature flags without resending the whole PageResources.

Block Types

Static factories in BlockBuilder:::

Method React Component
BlockBuilder::denseTable($key, $columns, $rows) Dense data grid
BlockBuilder::formPanel($key, $action, $method, $schema, $values) Form panel
BlockBuilder::detailPanel($key, $sections) Read-only detail view
BlockBuilder::metricCard($key, $value, $label, $delta, $icon, $href) KPI card
BlockBuilder::emptyState($key, $variant, $description, $cta) Empty state
BlockBuilder::statusStrip($key, $items, $tone) Status bar
BlockBuilder::activityTimeline($key, $groups, $hasMore, $loadMoreHref) Activity feed
BlockBuilder::markdownPanel($key, $content, $maxHeight) Markdown body
BlockBuilder::cardGrid($key, $columns, $rows, $variant) Card grid
BlockBuilder::actionGrid($key, $items, $flash) Action card grid
BlockBuilder::linkList($key, $items) Link list
BlockBuilder::chart($key, $type, ChartSeries[], ...) Chart (ChartType enum)
BlockBuilder::tabs($key, Tab[]) Tabs container

Or via RegionBuilder fluent API inside a ->region() closure. Each method mirrors its BlockBuilder factory one-to-one, so the same block type produces an identical descriptor whichever entry point you use:

->region('content', function ($r) {
    $r->metricCard('revenue', 42000, 'Revenue', delta: '+8%')
      ->denseTable('orders', ['id', 'total'], $rows)
      ->emptyState('no-results', variant: 'filtered');
})

Navigation

NavigationNode is the @api value object for nav tree entries. Serializes to the shape consumed by SidebarNav in @middag-io/react:

$node = new NavigationNode(
    key: 'audience.segments.index',
    label: 'Segments',
    icon: 'users',
    href: '/segments',
    active: true,
    weight: 10,
);
// Registered in AbstractNavigationRegistry implementations (in framework)

Form System

This library provides contracts and value objects only — renderers live in middag-io/framework (Inertia) and the host adapters.

Contracts

Interface Role
FormInterface schema() → hydrate() → validate() → validated()
FieldInterface toDefinition(): FieldDefinition — produces the boundary object
FormRendererInterface target(): RenderTarget + render(Form): RendererOutput
LayoutElementInterface id() + children() — Section and Group implement this

Value Objects

Class Notes
FieldDefinition Immutable boundary object between DSL and renderers. No JsonSerializable — renderers map manually.
Condition field + operator (ConditionOperator enum) + value + kind. Kinds: visible_when, hidden_when, required_when, disabled_when.
FormState Immutable readonly VO. withValues() / withErrors() return a new instance. Carries values, errors, submitted.
RendererOutput Static factories ::html() and ::props() for the two render targets. html() carries a body a renderer downstream produced, as opaque data; no ui contract produces markup.
FileValue A file field value: url plus optional name, size, type, id and uploadToken, an opaque string the host adapter maps to its pending-upload storage.

Layout Primitives

$section = Section::of('personal')
    ->label(Translatable::of('personal_info_section', 'forms')) // or a literal string
    ->fields($nameField, $emailField, Group::of('phone')->fields($countryCode, $number));

Section::label() takes a string|Translatable like every other label in the contract; labelData() serializes it via Label (a {key, domain} payload for an intent, a raw string for a literal).

Field Types (FieldType enum)

A closed backed enum of field types (TEXT, TEXTAREA, SELECT, DATE, RICHTEXT, TIME, AUTOCOMPLETE, TAGS, …) — see src/Shared/Enum/FieldType.php for the full catalogue.

Adding a type requires a new field class, matching renderer-side mappers, and the client component — most of which live downstream.

Table Builder

Fluent API for producing TableConfig consumed by dense table blocks:

$config = TableBuilder::make()
    ->column('name', 'Name', ['sortable' => true, 'searchable' => true])
    ->column('amount', 'Amount', ['sortable' => true, 'format' => ValueFormat::CURRENCY, 'formatOptions' => ['currency' => 'BRL']])
    ->filter('status', 'Status', FilterType::SELECT, [
        ['value' => 'active', 'label' => 'Active'],
        ['value' => 'inactive', 'label' => 'Inactive'],
    ])
    ->rowAction(PageBuilder::action('edit', 'Edit', ActionTarget::link('/invoices/{id}/edit')))
    ->bulkAction(PageBuilder::action('delete', 'Delete', ActionTarget::request('/invoices/bulk/delete'), ActionIntent::DANGER))
    ->options(new TableDisplayOptions(perPage: 25, sortColumn: 'name', selectable: true))
    ->build();

Installation

Requires PHP ^8.3. Install via Composer:

composer require middag-io/ui

Development

composer install
composer test           # PHPUnit
composer check          # style + rector + stan + schema drift
composer fix            # style + rector (apply)
composer lint:php83     # parse every file (incl. tooling configs) on real PHP 8.3 (Docker)

The dev toolchain may run a newer PHP than the supported floor (^8.3). Newer syntax such as new X()->method() parses on 8.4 but is a fatal error on 8.3, so composer check alone will not catch it. Two guards keep the floor honest: composer lint:php83 runs php -l under a real PHP 8.3 interpreter over the source, tests, and the .php-cs-fixer.dist.php / .php-rector.php configs; and the static checks of the CI run on PHP 8.3, the floor. PHPStan targets the floor (phpVersion: 80300); it does not catch syntax-level issues, which is the lint's job. CI runs the tests on PHP 8.3, 8.4 and 8.5, and a highest job resolves the highest dependency versions on 8.4 and 8.5 without the platform pin.

Git hooks configured automatically via post-install-cmd. commit-msg enforces Conventional Commits.

type(scope): description

Types: feat, fix, chore, docs, style, refactor, perf, test, build, ci, revert

Releases managed by release-please.

Versioning

Support starts at 2.0.0; the 1.x line is pre-stable and unsupported, and the cut to 2.0.0 is clean. From 2.0.0, all middag-php-* libraries form one version family: they share MAJOR.MINOR, a patch carries fixes only, a minor never breaks, and a family MINOR or MAJOR is released in every library on the decision of the product owner. Every library of the family is required with the same ^2.N. Support covers the @api surface only. Rules: https://docs.middag.dev/libraries/reference/versioning-and-compatibility. Details: API-STABILITY.md and CONTRIBUTING.md §Versioning.

Help and status

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Copyright 2026 MIDDAG

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Contributing

See CONTRIBUTING.md.