PHP SDK Planned

PSR-compliant PHP SDK for the message.com REST API. Composer-installable, framework-agnostic, with first-party adapters for Laravel and Symfony. Targets PHP 8.1+.

Installation

The package follows PSR-4 autoloading and PSR-18 HTTP client discovery. If you already have Guzzle or Symfony HttpClient installed, it will pick them up automatically.

composer require message-com/sdk

# Composer pins ~1.0; we follow semver strictly

Initialise the client

Pass the constructor your API key. The client wraps a PSR-18 HTTP client and stores the workspace context for the lifetime of the process.

<?php
require 'vendor/autoload.php';

use MessageCom\Client;

$msg = new Client([
    'api_key' => getenv('MESSAGE_API_KEY'),
    'timeout' => 5,
]);

Sync visitors

Upsert keys on externalId first, then email. Pass attributes as a flat associative array; nested arrays are flattened into JSON.

<?php
// Upsert a visitor from a webhook handler
$msg->visitors->upsert([
    'email'       => '[email protected]',
    'externalId'  => 'crm-4567',
    'name'        => 'Alice Johnson',
    'attributes'  => [
        'plan' => 'pro',
        'mrr'  => 99,
    ],
]);

Create tickets

Tickets are conversations with channel = "ticket". The helper hides the channel parameter. Replies land in the unified inbox in your dashboard.

<?php
// Open a ticket when a Stripe charge fails
$msg->tickets->create([
    'visitorEmail' => '[email protected]',
    'subject'      => 'Auto-detected failed payment',
    'body'         => 'Stripe charge ch_xyz failed. Reach out within 4h.',
    'tags'         => ['billing', 'auto-created'],
]);

Laravel integration

Bind the client as a singleton in a service provider and inject it where you need it. The package also publishes a php artisan message:install command that scaffolds the config and a starter webhook controller.

<?php
// config/services.php
return [
    // ...
    'message' => [
        'api_key' => env('MESSAGE_API_KEY'),
    ],
];

// In a service provider
$this->app->singleton(MessageCom\Client::class, fn () => new MessageCom\Client([
    'api_key' => config('services.message.api_key'),
]));

// In a controller
public function store(MessageCom\Client $msg, Request $req) {
    $msg->tickets->create([
        'visitorEmail' => $req->email,
        'subject'      => $req->subject,
        'body'         => $req->body,
    ]);
}

Symfony integration

The Symfony bundle registers the client as an autowireable service. Drop it into your constructor like any other service. Configuration goes in config/packages/message_com.yaml.

Errors

All API failures throw MessageCom\Exception\ApiException with the status code, error code, and human message preserved. Network failures throw the underlying PSR-18 exceptions.

Common pitfalls

• Do not block the main request thread. If you call from inside a Laravel controller or Symfony action, queue the call instead.
• Always set externalId on visitor upserts. Without it we cannot reconcile when a user changes their email.
• Use HTTPS-only API keys. The SDK refuses to send live keys over plain HTTP.