README

PHP client for sending application alerts and event notifications to SignalHub.

Documentation: English | Русский | Bahasa Indonesia

The SDK targets the SignalHub incoming source API:

POST https://signalhub.pro/api/source/{sourceToken}/messages

Requirements

• PHP 8.1 or newer
• ext-json
• Outbound HTTPS access to signalhub.pro

The default transport uses PHP streams, so the package does not require Guzzle, Symfony, or any other HTTP client.

Installation

Install through Composer after the package is published:

composer require signalhub/php-sdk

For local development before Packagist publication:

{
  "repositories": [
    {
      "type": "path",
      "url": "../signalhub-php-sdk"
    }
  ],
  "require": {
    "signalhub/php-sdk": "*"
  }
}

Then install it in your project:

composer update signalhub/php-sdk

Source Token

Create a source in the SignalHub panel and choose the PHP SDK integration. Copy the generated source token and pass it to SignalHub\Client.

Do not commit source tokens to your repository. Store them in environment variables or a secret manager.

Quick Start

<?php

require __DIR__.'/vendor/autoload.php';

use SignalHub\Client;
use SignalHub\Message;
use SignalHub\MessageLevel;
use SignalHub\MessagePriority;
use SignalHub\SignalHubException;

$client = new Client($_ENV['SIGNALHUB_SOURCE_TOKEN']);
$message = Message::create('Gateway callback did not respond in time')
    ->withTitle('Payment webhook timeout')
    ->withPriority(MessagePriority::High)
    ->withLevel(MessageLevel::Error);

try {
    $result = $client->send($message);

    echo sprintf("SignalHub accepted message %s with status %s\n", $result->token, $result->status);
} catch (SignalHubException $exception) {
    echo sprintf("SignalHub error: %s\n", $exception->getMessage());
}

Sending a Full Payload

Use Message as a small immutable payload builder.

$message = Message::create('p95 latency is above <b>1500 ms</b>')
    ->withTitle('Checkout latency is high')
    ->withPriority(MessagePriority::Urgent)
    ->withLevel(MessageLevel::Warning)
    ->with('imageUrls', [
        'https://example.com/charts/checkout-latency.png',
    ])
    ->withData([
        'metadata' => [
            'service' => 'checkout',
            'region' => 'eu-central',
        ],
    ]);

$result = $client->send($message);

Use sendPayload() when you already have the complete incoming payload as an array.

$result = $client->sendPayload([
    'title' => 'Checkout latency is high',
    'text' => 'p95 latency is above <b>1500 ms</b>',
    'priority' => MessagePriority::Urgent,
    'level' => MessageLevel::Warning,
    'metadata' => [
        'service' => 'checkout',
        'region' => 'eu-central',
    ],
]);

text is required. SignalHub accepts plain text and a small safe HTML subset for message formatting: <b>, <i>, <a>, and <br>.

Custom Host and Timeout

The default host is https://signalhub.pro. Pass a custom host for staging or self-hosted deployments.

$client = new Client(
    sourceToken: $_ENV['SIGNALHUB_SOURCE_TOKEN'],
    baseUrl: 'https://signalhub.pro',
    timeoutSeconds: 5,
);

Error Handling

API and transport failures are reported as SignalHubException.

try {
    $client->send(Message::create('Database replica lag is above threshold'));
} catch (SignalHubException $exception) {
    $statusCode = $exception->statusCode();
    $responseData = $exception->responseData();
}

Use statusCode() to inspect HTTP failures and responseData() to read a decoded API error response when one is available.

API Reference

Client::__construct()

new Client(
    string $sourceToken,
    ?string $baseUrl = null,
    ?HttpTransportInterface $transport = null,
    int $timeoutSeconds = 10,
)

Creates a client for one SignalHub source.

Client::send()

send(Message $message): MessageResult

Sends a message object.

Common message payload fields:

• title: visible message title
• priority: one of MessagePriority::*
• level: one of MessageLevel::*
• imageUrls: list of public image URLs
• fileUrls: list of public file URLs
• actions: action metadata
• any custom metadata fields accepted by your SignalHub workflow

Client::sendPayload()

sendPayload(array $payload): MessageResult

Sends a complete payload. The payload must contain a non-empty text field.

Message

Message::create('Text')
    ->withTitle('Title')
    ->withPriority(MessagePriority::High)
    ->withLevel(MessageLevel::Error)
    ->with('metadata', ['service' => 'billing']);

Immutable message payload builder accepted by Client::send().

withPriority() accepts MessagePriority|null. withLevel() accepts MessageLevel|null.

MessageResult

$result->token;
$result->status;
$result->deliveriesCount;

Represents the accepted SignalHub message.

Development

Install dependencies:

composer install

Run all checks:

composer all

Run checks separately:

composer cs:check
composer phpstan
composer test

Release Checklist

1. Create a public repository for this package, for example signalhub/php-sdk.
2. Push this directory as the repository root.
3. Confirm support.source and support.issues in composer.json.
4. Run composer validate --strict and composer all.
5. Tag the first release, for example v0.1.0.
6. Submit the repository to Packagist as signalhub/php-sdk.

License

MIT. See LICENSE.