PHPackages                             rocketman/spoa-php - 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. rocketman/spoa-php

ActiveLibrary[Framework](/categories/framework)

rocketman/spoa-php
==================

Stream Processing Offload Agent (SPOA) framework for PHP

v0.9.4(3mo ago)0325↓33.3%MITPHPPHP >=8.2CI passing

Since Jan 17Pushed 3mo agoCompare

[ Source](https://github.com/RocketMan/spoa-php)[ Packagist](https://packagist.org/packages/rocketman/spoa-php)[ RSS](/packages/rocketman-spoa-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (4)Versions (6)Used By (0)

spoa-php
========

[](#spoa-php)

A lightweight PHP framework for building HAProxy **Stream Processing Offload Agent (SPOA)** services

This library implements the SPOE protocol and allows PHP applications to receive messages from HAProxy, process request or session metadata, and return variables back to HAProxy for use in ACLs and routing decisions.

[![Latest Version](https://camo.githubusercontent.com/863cb02ff56ff8b80a753c94344fc710b77b0512ca41d1536a46c09ebb8f0367/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f726f636b65746d616e2f73706f612d706870)](https://packagist.org/packages/rocketman/spoa-php)[![CI](https://github.com/rocketman/spoa-php/actions/workflows/ci.yml/badge.svg)](https://github.com/rocketman/spoa-php/actions/workflows/ci.yml)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/rocketman/spoa-php?tab=readme-ov-file#MIT-1-ov-file)

---

Features
--------

[](#features)

- Native SPOE protocol implementation
- Event-driven, asynchronous I/O using ReactPHP
- Simple handler-based programming model
- Support for all HAProxy variable scopes
- Minimal runtime dependencies
- PHPUnit and PHPStan coverage

---

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

[](#requirements)

- PHP **8.2** or later
- A running HAProxy instance with SPOE enabled

---

Installation
------------

[](#installation)

Install via Composer:

```
composer require rocketman/spoa-php
```

### Dependencies

[](#dependencies)

**Runtime**

- `react/socket`

**Development**

- `phpunit/phpunit`
- `phpstan/phpstan`
- `react/event-loop`

---

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

[](#core-concepts)

### The `Connection` class

[](#the-connection-class)

The central abstraction in this framework is `SPOA\Server\Connection`.

Each incoming SPOE connection from HAProxy is represented by a `Connection` instance. Applications register message handlers on the connection and return variables (or Promises that resolve to variables) to HAProxy in response.

The framework handles:

- SPOE handshake and negotiation
- Message decoding
- Frame fragmentation
- Action encoding and responses

Your application code only needs to define handlers.

---

### Registering message handlers

[](#registering-message-handlers)

Handlers are registered by message name:

```
$conn->on('get-ip-reputation', function (array $args): PromiseInterface|array {
    // ...
});
```

- **Message Name**: The event name (e.g., `get-ip-reputation`) **must match** the `spoe-message` identifier in your HAProxy configuration.
- **Arguments (**`$args`**)**: An associative array of `SPOA\Protocol\Arg` object instances.

    - **Named Arguments**: Accessed via their name defined in HAProxy (e.g., `$args['client_ip']`).
    - **Nameless Arguments**: Accessed via the key `arg(n)`, where `n`is the zero-based position (e.g., `$args['arg(0)']`).
    - **Ordinal Access**: As the array maintains the order defined in HAProxy, you can retreive any argument by its position regardless of its name (e.g., `$fourthArg = $args[array_keys($args)[3]]`).

---

Returning variables to HAProxy
------------------------------

[](#returning-variables-to-haproxy)

Handlers return an associative array of variables to set or unset.

```
use SPOA\Protocol\Arg;

return [
    'sess.one' => Arg::str('two'),
    'txn.score' => Arg::uint32(42),
];
```

Alternatively, a handler may return a `React\Promise\PromiseInterface`that resolves to the associative array. This allows handlers to perform asynchronous operations before returning data to HAProxy.

#### Variable scopes

[](#variable-scopes)

Variable names may be prefixed with a scope:

PrefixScope`proc.`Process`sess.`Session`txn.`Transaction`req.`Request`res.`ResponseIf no prefix is provided, the variable defaults to **process scope**.

Specifying `null` as a value will **unset** the variable. To set a variable to null, use `Arg::null()`.

---

Getting Started
---------------

[](#getting-started)

Below is a minimal SPOA agent implemented using this library. The example is intentionally procedural to focus on the framework’s programming model.

### Minimal PHP agent

[](#minimal-php-agent)

```