dispatchEvent

The dispatchEvent() function updates reactive state values programmatically. On the client, it resolves and updates the target key directly in the browser. On the server, the PHPX::dispatchEvent() helper can emit the equivalent JavaScript so that the client performs the update after render. By default, targets are resolved starting from the current component unless you override this with scope.

Client API (JavaScript)

Signature

pphp.dispatchEvent(
  target: string,
  value: any | ((prev: any) => any),
  opts?: {
    scope?: 'current' | 'parent' | 'root' | string | string[];
    from?: Element;
  }
): Promise<string | false>
Param Type Description
target string Path to update. Component-scoped (user.name) or shared (app.theme).
value any | (prev) => any New value or functional updater receiving the previous value.
opts.scope 'current' | 'parent' | 'root' | string | string[] Controls resolution base:
  • 'current' (default): current component hierarchy
  • 'parent': immediate parent hierarchy
  • 'root' (alias 'app'): application root
  • string: explicit base path
  • string[]: explicit base segments
opts.from Element Optional DOM element to infer hierarchy when no effect/event context exists.
Returns Promise<string | false> Resolved absolute path updated (e.g. app.xyz.user.name), or false on failure.

Client Examples

<p>User: {{ user.name }}</p>

<script>
  const [user, setUser] = pphp.state({ name: "Guest" });

  export const updateName = () => {
    pphp.dispatchEvent('user.name', 'Jefferson');
  };

  export const capitalizeName = () => {
    pphp.dispatchEvent('user.name', prev => prev.toUpperCase());
  };
</script>
<script>
  export const toggleDarkMode = () => {
    pphp.dispatchEvent('app.theme', prev => prev === 'dark' ? 'light' : 'dark');
  };
</script>

Server Helper (PHPX::dispatchEvent)

Inside a PHPX component, you can call dispatchEvent() to emit the same client call during render. If $name is empty, it safely returns an empty string (no output). This is useful for conditionally triggering state changes from server-rendered HTML without manual JS. 

protected function dispatchEvent(?string $name, string $value, array $options = []): string
// Emits: pphp.dispatchEvent(name, value, options);
// Returns '' if $name is empty.
Param Type Behavior
$name string|null Target key/path. If null/empty, returns ''.
$value string Inserted verbatim in JS.
$options array Normalized to { scope: 'current'|'parent'|'root'|string[] }; invalid scope → 'current'.
Returns string JS snippet or '' if $name is empty.

Server Examples

<script>
{$this->dispatchEvent($props, 'value', ['scope' => 'parent'])}
</script>

<script>
{$this->dispatchEvent('counter', '(prev) => (prev ?? 0) + 1', ['scope' => 'parent'])}
</script>

<script>
{$this->dispatchEvent($props, 'new Date()', ['scope' => 'parent'])}
{$this->dispatchEvent($props, 'true', ['scope' => 'parent'])}
{$this->dispatchEvent($props, 'false', ['scope' => 'parent'])}
{$this->dispatchEvent($props, 'null', ['scope' => 'parent'])}
</script>

<script>
{$this->dispatchEvent('', json_encode('anything'))} // returns ''
</script>
Notes:
  • Resolution semantics match the client API.
  • Use json_encode() for safe literals; pass raw JS only when intentional.
  • No output is generated if $name is empty — protects against accidental dispatches.
  • Only emits JavaScript; actual update runs on the client when executed.