README

PHP 8 attributes for HTTP routes, health probes, vhosts, and WebSocket channels, RPC, heartbeat, and client assets. Use them on handler classes in apps built with mammatus/http-server; its Composer plugin reads these attributes when autoload is dumped and generates routing configuration.

Install

To install via Composer, use the command below, it will automatically detect the latest version and bind it with ^.

composer require mammatus/http-server-attributes

Attributes

This package provides the following attributes:

Vhost

Class-level, repeatable. Names the virtual host the handler belongs to.

use Mammatus\Http\Server\Attributes\Vhost;

#[Vhost('frontend')]
final readonly class HomePageHandler
{
}

Route

Class- or method-level, repeatable. HTTP method and path pattern. The method is HttpMethod (HEAD, GET, POST, PUT, PATCH, DELETE).

use Mammatus\Http\Server\Attributes\HttpMethod;
use Mammatus\Http\Server\Attributes\Route;

#[Route(HttpMethod::GET, '/ping/{name}')]
final readonly class PingHandler
{
}

Probe

Class-level, repeatable. Marks the handler as a Kubernetes-style probe for Helm integration in the server plugin. The type is ProbeType: StartUp, Liveness, or Readiness.

use Mammatus\Http\Server\Attributes\HttpMethod;
use Mammatus\Http\Server\Attributes\Probe;
use Mammatus\Http\Server\Attributes\ProbeType;
use Mammatus\Http\Server\Attributes\Route;
use Mammatus\Http\Server\Attributes\Vhost;

#[Vhost('healthz')]
#[Route(HttpMethod::GET, '/probe/liveness')]
#[Probe(ProbeType::Liveness)]
final class LivenessProbeHandler
{
}

See healthz-vhost for full probe handlers.

Bus

Class-level marker with a bus name (successor to http-server-annotations Bus). Not consumed by mammatus/http-server today.

use Mammatus\Http\Server\Attributes\Bus;

#[Bus('domain-events')]
final readonly class OrderPlacedHandler
{
}

WebSocket

Attributes in Mammatus\Http\Server\Attributes\WebSocket configure vhosts, broadcast channels, heartbeat, client assets, and RPC methods. Put HeartbeatChannel, HeartbeatInterval, and ServeClientAsset on the vhost class. Put Channel on channel payload or broadcaster classes. Put Rpc on handler methods.

Combined vhost:

use Mammatus\Http\Server\Attributes\Vhost;
use Mammatus\Http\Server\Attributes\WebSocket\HeartbeatChannel;
use Mammatus\Http\Server\Attributes\WebSocket\HeartbeatInterval;
use Mammatus\Http\Server\Attributes\WebSocket\ServeClientAsset;

#[Vhost('frontend')]
#[ServeClientAsset]
#[HeartbeatChannel('heartbeat')]
#[HeartbeatInterval(seconds: 30.0)]
final readonly class FrontendVhost
{
}

WebSocket Channel

Class-level, repeatable. Registers a broadcast $channel and $payloadClass (both required). See Channel.

When the annotated class is the payload type, pass self::class:

use Mammatus\Http\Server\Attributes\Vhost;
use Mammatus\Http\Server\Attributes\WebSocket\Channel;

#[Vhost('frontend')]
#[Channel('demo-events', self::class)]
final readonly class WebSocketDemoEvent
{
    public function __construct(public string $message)
    {
    }
}

Separate broadcaster and payload:

#[Channel('events', EventPayload::class)]
final readonly class EventBroadcaster
{
}

WebSocket HeartbeatChannel

Class-level. Sets the broadcast channel name used for WebSocket heartbeat traffic. See HeartbeatChannel.

#[HeartbeatChannel('heartbeat')]
final readonly class FrontendVhost
{
}

WebSocket HeartbeatInterval

Class-level. Sets the WebSocket heartbeat interval in seconds. Omit the attribute to use the server default. See HeartbeatInterval.

#[HeartbeatInterval(seconds: 30.0)]
final readonly class FrontendVhost
{
}

WebSocket ServeClientAsset

Class-level marker on a vhost class. Tells the mammatus/http-server plugin to serve bundled WebSocket client assets for that vhost. See ServeClientAsset.

#[ServeClientAsset]
final readonly class FrontendVhost
{
}

WebSocket Rpc

Method-level, repeatable. JSON-RPC-style method name on WebSocket handlers. See Rpc. mammatus/http-server accepts (ServerRequestInterface $upgradeRequest) with a named return type, or ($params, ServerRequestInterface $upgradeRequest) where $params is a user DTO class. See Collector.

use Mammatus\Http\Server\Attributes\Vhost;
use Mammatus\Http\Server\Attributes\WebSocket\Rpc;
use Psr\Http\Message\ServerRequestInterface;

#[Vhost('frontend')]
final readonly class WebSocketPingHandler
{
    #[Rpc('ping')]
    public function ping(WebSocketPingParams $params, ServerRequestInterface $upgradeRequest): WebSocketPingResult
    {
        return new WebSocketPingResult(pong: true, echo: $params->message);
    }
}

More examples in the http-server dev app: PingHandler.

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

mammatus / http-server-attributes

Package info

Security

Statistics