xcorp1986/sandstone

PHP microframework designed to build a RestApi working together with a websocket server. Build a real time RestApi!

Sandstone

PHP microframework designed to build a RestApi working together with a websocket server.

Build a real time RestApi!

💬 New (18 April 2018)

I opened a chat channel where you can get help, give feedback, and talk about Sandstone (Mattermost instance):

💬 https://framateam.org/sandstone 💬

Install

composer require eole/sandstone

Usage

Create a Sandstone application

Sandstone is a Silex application with websockets:

$app = new Eole\Sandstone\Application();

Declare a websocket topic

Similar as declaring a Silex route:

$app->topic('chat/{channel}', function ($topicPattern, $arguments) {
    $channelName = $arguments['channel'];

    return new ChatTopic($topicPattern, $channelName);
});

See ChatTopic class here.

Send push notifications

When an endpoint is called on the RestApi, i.e POST /api/articles and update a resource, you can send a push notification to notify this update.

On the RestApi stack:

use Symfony\Component\HttpFoundation\Response;

$app->post('api/articles', function () use ($app) {
    // Dispatch an event on article creation
    $app['dispatcher']->dispatch('article.created', new ArticleEvent());

    return new Response([], 201);
});

// Send all 'article.created' events to push server
$app->forwardEventToPushServer('article.created');

Then on the websocket stack:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Eole\Sandstone\Websocket\Topic;

class MyWebsocketTopic extends Topic implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'article.created' => 'onArticleCreated',
        ];
    }

    public function onArticleCreated(ArticleEvent $event)
    {
        $this->broadcast([
            'message' => 'An article has just been published: '.$event->title,
        ]);
    }
}

Examples

Working examples from scratch:

• RestApi + Websocket + push notification
• Authentication on RestApi and Websockets
• Chat example

Documentation

See the full documentation here

Sandstone edition

You're planning to start a new real-time Rest Api application based on Sandstone?

You may be interested by Sandstone edition.

It already integrates a Sandstone application with a docker environment, a database, debug tools...

Get started with Sandstone edition.

Misc

Articles about Sandstone:

• Sandstone explained to NodeJS, Python or PHP users
• Creating a poker planning application with PHP and websockets
• What is Sandstone, What can I do with Sandstone

Big picture: https://eole-io.github.io/sandstone-doc/big-picture

Changelog

See Releases page.

License

This library is under MIT License.