README

This repository contains the PHP protocol package elqora/interactions which defines the authoritative wire protocol for Elqora frontend-host interactions.

Protocol Architecture

The Elqora Interaction System is designed in two complementary parts:

PHP runtime package (elqora/interactions): The protocol authority. It defines what an interaction means, how it is serialized, and what constitutes a valid payload.
React shadcn registry: The frontend host implementation. It resolves serialized wire payloads to React components and executors (e.g. rendering dialogue overlays, loading scripts, invoking exports).

By separating description from execution, PHP applications can coordinate complex UI transformations, client-side actions, and dynamic components without being coupled to frontend runtime quirks.

Installation

Install the package via Composer:

composer require elqora/interactions

Stable Interaction Types

Type	PHP Class	Description
`instructions`	`Instructions`	Markdown instructions rendered by the frontend host using the resolved presentation.
`qr_code`	`QrCode`	Encoded raw text value or a canonical structured QR image representation.
`redirect`	`Redirect`	Browser or client-side application navigation.
`script`	`Script`	Order-significant script files to load prior to calling a controlled handler/global/module-export.
`mount`	`Mount`	Mount resolves a registered frontend mount-handler key. Source-based mount resolution may be introduced later through a discriminated resolver model.
`component`	`Component`	The React host resolves and imports the declared component source, selects the requested export, and renders it inside the existing React tree.

Flexible Payloads

The protocol enforces exact JSON types for flexible parameters:

metadata: string-keyed JSON object (array<string, mixed>)
props: string-keyed JSON object (array<string, mixed>)
parameters: string-keyed JSON object (array<string, mixed>)
attributes: string-keyed JSON object (array<string, mixed>)
arguments: ordered JSON array (array<int, mixed>) - associative or sparse arrays are rejected.

QR Code Image Structure

The QR code image source is represented using a canonical structured shape:

'image' => [
    'type' => 'url', // or 'data_uri'
    'src' => 'https://example.com/qr.png', // or 'data:image/png;base64,...'
]

Plain strings as QR image sources are not supported.

Presentation Layout Preferences

Supported presentations represent a layout preference (which the host may override):

inline: Standard flow placement in the active viewport.
dialog: Floating modal window requiring user interaction.
popover: Floating card aligned to a trigger element.

Note: Redirect does not support presentation.

Usage Examples

1. Construction & Serialization

Every DTO is immutable (readonly) and self-validates upon construction.

use Elqora\Interactions\Interactions\Instructions;
use Elqora\Interactions\Enums\Presentation;

// Construct an instructions interaction
$interaction = new Instructions(
    content: "# Complete Verification\n\nPlease submit your ID.",
    title: "Verification",
    metadata: ["user_id" => 42],
    presentation: Presentation::Dialog
);

// Serialize to canonical flat wire format
$payload = $interaction->toArray();
/*
[
    'type' => 'instructions',
    'content' => "# Complete Verification\n\nPlease submit your ID.",
    'title' => 'Verification',
    'metadata' => ['user_id' => 42],
    'presentation' => 'dialog',
]
*/

2. Hydration

Hydrate raw payloads back to their original strongly-typed DTOs using InteractionFactory.

use Elqora\Interactions\Serialization\InteractionFactory;

$payload = [
    'type' => 'redirect',
    'url' => 'https://elqora.com/dashboard',
    'replace' => true
];

$interaction = InteractionFactory::fromArray($payload);

echo $interaction->url; // "https://elqora.com/dashboard"

Quality Gate Checks

All changes should pass the validation scripts:

composer validate --strict
composer test
composer analyse

React shadcn Registry

The repository also distributes an editable React interactions frontend implementation through a shadcn registry:

Registry definition: registry.json
Registry component sources: registry/interactions/
Playground / Tests workspace: examples/react/

For detailed information on React usage, activation state semantics, layout overrides, host security policies, and custom renderers, refer to the React Registry Documentation.

elqora / interactions

Maintainers

Package info

Statistics

Security