Phui

Appearance

Component ​

Phui\Component, the attributes that declare its reactive members, and the nodes that mount it.

Component ​

abstract class Phui\Component

Extended by every component. Only build() is required.

Building ​

php
abstract build(): Node

Returns the component's node tree. Throws InvalidArgumentException if it returns a hidden node, since that would leave the component with nothing to render; wrap the component in Node::when() at its mount site instead.

php
bindings(): array

Returns the component's Binding array — all of its keyboard, paste, click and scroll behaviour. Parents remap or suppress individual bindings per instance through bindings() on the component node.

php
isFocusable(): bool

Whether the component takes part in focus traversal. A parent's focusable() on the mount node wins; otherwise the answer comes from canFocus().

php
canFocus(): bool

Whether the component takes focus when the parent has no opinion. Returns $focusable by default; override it when focusability depends on the component's own state.

php
protected function canFocus(): bool
{
    return ! $this->disabled;
}

Lifecycle ​

php
onMount(): void

Runs once when the component is added to the tree, before its first build. Services and the runtime context are available, so initialise anything the first frame reads here — and start timers, fetches, or focus.

php
onRebuild(): void

Runs after the component rebuilds.

php
beforeUnmount(): void

Runs just before the component is removed from the tree.

Mounting ​

php
final static mount(?string $key = null): ComponentNode

Returns a ComponentNode that mounts this component.

php
UserList::mount()->props(users: $this->users)
php
final static modal(?string $key = null): ModalNode

Returns a ModalNode that mounts this component in a layer above the rest of the tree.

Protected members ​

php
protected bool $focusable = false

Whether the component can take focus. Set it to true to opt in, or override canFocus() for a value that depends on the component's state.

php
protected private(set) Focus $focus
protected private(set) Timers $timers
protected private(set) System $system
protected private(set) Async $async
protected private(set) Themes $themes
protected private(set) Keymaps $keymaps

The runtime services, supplied by the framework.

php
final protected colours(string $class): object

Returns the colours object for $class: the one the parent set on this instance if there is one, otherwise the value resolved from the active Theme.

php
final protected get(string $class): mixed

Returns the service registered on the Screen under $class. Throws MissingServiceException when nothing is registered.

php
final protected has(string $class): bool

Returns whether a service is registered under $class.

php
final protected emit(string $event, mixed $data = null): void

Emits a named event with an optional payload, dispatched to any handler the parent registered on this instance with on().

Attributes ​

Classes in the Phui\Attributes namespace, applied to component properties.

php
#[State(bool $isDeep = false)]

Marks a property as internal state. Writing to it schedules a rebuild. $isDeep compares nested array and object contents rather than the top-level value.

php
#[Prop(bool $isDeep = false)]

Marks a property as owned by the parent and supplied through props().

php
#[Model(string $emit, bool $isDeep = false)]

Marks a property as two-way bound. Writing to it emits the $emit event carrying the new value, for the parent to handle with on().

php
#[Ref]

Marks an ElementRef property, which the framework creates and binds once the node carrying it renders.

ComponentNode ​

class Phui\Nodes\ComponentNode extends Node

Returned by mount().

php
props(mixed ...$props): static

Sets the component's #[Prop] and #[Model] values, passed as named arguments.

php
on(
    string $eventName,
    Closure $handler,
    ?Closure $condition = null,
): static

Registers a handler for an event the component emits. The handler receives the EmitEvent, whose data carries the payload. $condition gates whether the handler runs.

php
bindings(array $bindings): static

Overrides the component's own bindings for this instance. Overrides merge by signature — event, key and modifiers — and Binding::none() removes a default outright.

php
colours(object ...$colours): static

Sets colours objects for this instance, taking precedence over the active theme.

php
requestFocus(): static

Asks the runtime to focus this component once it mounts.

php
focusable(bool $focusable = true): static

Decides focusability for this instance, overriding whatever the component decides for itself. false takes it out of tab traversal, so it never holds focus or receives keyboard input. Mouse input is positional and still reaches it.

php
Checkbox::mount()
    ->props(label: 'Ready', checked: $this->ready)
    ->focusable(false);

ModalNode ​

final class Phui\Nodes\ModalNode extends ComponentNode

Returned by modal(). Adds the following to the ComponentNode surface.

php
interactable(bool $interactable = true): static

Sets whether the modal receives input.

php
transparent(bool $transparent = true): static

Sets whether the tree behind the modal shows through.

VirtualContainer ​

final class Phui\Nodes\VirtualContainer extends ElementNode implements ContainerNode

A container that builds only the rows currently in view.

php
static make(
    Closure $builder,
    int|Closure $itemCount,
    ?int $itemHeight = null,
    ?string $key = null,
): self

Creates a virtual container. $builder receives an index and returns that row. $itemHeight fixes every row to the same height; when it is null rows are measured, and each row must then be an element node rather than a component.

php
version(
    int|string|null $version,
    int|array|null $changed = null,
): static

Marks the backing data as changed so built rows are discarded. $changed limits the discard to the given indices.

Canvas ​

final class Phui\Nodes\Canvas extends ElementNode

An element drawn cell by cell.

php
static make(
    int $width,
    int $height,
    ?string $key = null,
): self

Creates a canvas of a fixed cell size.

php
draw(Closure $callback): static

Sets the callback that paints the canvas, called with a Surface.

php
getWidth(): int
getHeight(): int

Return the canvas's cell dimensions.

Released under the MIT License.