marein / php-nchan-client

A PHP https://nchan.io client.

php-nchan-client

Table of contents

• Overview
• Installation and requirements
• Usage
  • Publish a message
  • Get channel information
  • Delete a channel
  • Nchan status information
  • Authorize requests
• PSR-18 compatibility

Overview

This is a PHP client for https://nchan.io.

Installation and requirements

composer require marein/php-nchan-client

If you want to use the PSR-18 adapter, install a library that implements PSR-18 http client (see here) and a library that implements PSR-17 http factories (see here).

If you want to use the built-in http client (default if you don't set anything), enable the php configuration allow_url_fopen.

Usage

The following code examples use the built-in http client.

Publish a message

Show code

<?php

namespace {

    use Marein\Nchan\Api\Model\PlainTextMessage;
    use Marein\Nchan\Nchan;

    include '/path/to/autoload.php';

    $nchan = new Nchan('http://my-nchan-domain');
    $channel = $nchan->channel('/path-to-publisher-endpoint');
    $channelInformation = $channel->publish(
        new PlainTextMessage(
            'my-message-name',
            'my message content'
        )
    );

    // Nchan returns some channel information after publishing a message.
    var_dump($channelInformation);
}

Get channel information

Show code

<?php

namespace {

    use Marein\Nchan\Nchan;

    include '/path/to/autoload.php';

    $nchan = new Nchan('http://my-nchan-domain');
    $channel = $nchan->channel('/path-to-publisher-endpoint');
    $channelInformation = $channel->information();

    var_dump($channelInformation);
}

Delete a channel

Show code

<?php

namespace {

    use Marein\Nchan\Nchan;

    include '/path/to/autoload.php';

    $nchan = new Nchan('http://my-nchan-domain');
    $channel = $nchan->channel('/path-to-publisher-endpoint');
    $channel->delete();
}

Nchan status information

Endpoints with the nchan_stub_status directive can be queried as follows.

Show code

<?php

namespace {

    use Marein\Nchan\Nchan;

    include '/path/to/autoload.php';

    $nchan = new Nchan('http://my-nchan-domain');
    $status = $nchan->status('/path-to-status-location');
    $statusInformation = $status->information();

    var_dump($statusInformation);
}

Authorize requests

Endpoints with the nchan_authorize_request directive must be authorized. The constructor of the built-in http client takes an implementation of type Credentials. This library comes with 2 built-in implementations, BasicAuthenticationCredentials and BearerAuthenticationCredentials.

Show code

<?php

namespace {

    use Marein\Nchan\HttpAdapter\BasicAuthenticationCredentials;
    use Marein\Nchan\HttpAdapter\BearerAuthenticationCredentials;
    use Marein\Nchan\HttpAdapter\HttpStreamWrapperClient;
    use Marein\Nchan\Nchan;

    include '/path/to/autoload.php';

    // Client with basic authentication
    $adapter = new HttpStreamWrapperClient(
        new BasicAuthenticationCredentials('nchan', 'password')
    );

    // Client with bearer authentication
    $adapter = new HttpStreamWrapperClient(
        new BearerAuthenticationCredentials('my-token')
    );

    $nchan = new Nchan('http://my-nchan-domain', $adapter);
}

If you use another http client through the PSR-18 adapter, the respective http client has its own extension points to modify the request before it is sent.

PSR-18 compatibility

This library comes with a PSR-18 compatible adapter. There are good reasons not to use the built-in client. It's based on the http stream wrapper and file_get_contents. This closes the TCP connection after each request. Other clients, see below, can keep the connection open.

The following example uses guzzlehttp/guzzle and guzzlehttp/psr7.

Show code

<?php

namespace {

    use GuzzleHttp\Client;
    use GuzzleHttp\Psr7\HttpFactory;
    use Marein\Nchan\HttpAdapter\Psr18ClientAdapter;
    use Marein\Nchan\Nchan;

    include '/path/to/autoload.php';

    $nchan = new Nchan(
        'http://my-nchan-domain',
        new Psr18ClientAdapter(
            new Client(),
            new HttpFactory(),
            new HttpFactory()
        )
    );
}

The following code example uses symfony/http-client and nyholm/psr7.

Show code

<?php

namespace {

    use Marein\Nchan\HttpAdapter\Psr18ClientAdapter;
    use Marein\Nchan\Nchan;
    use Nyholm\Psr7\Factory\Psr17Factory;
    use Symfony\Component\HttpClient\HttpClient;
    use Symfony\Component\HttpClient\Psr18Client;

    include '/path/to/autoload.php';

    // Symfony itself needs an adapter to be PSR-18 compliant.
    $httpClient = new Psr18Client(
        HttpClient::create(),
        new Psr17Factory(),
        new Psr17Factory()
    );

    $nchan = new Nchan(
        'http://my-nchan-domain',
        new Psr18ClientAdapter(
            $httpClient,
            $httpClient,
            $httpClient
        )
    );
}

php-nchan-client's Issues

Add ComposerRequireChecker to pipeline

Release 3.0.0

Release version 2.0.0

Breaking changes:

• Drop support for php 7.1 and php 7.2
• Constructor of
  \Marein\Nchan\Http\Url
  throws
  \Marein\Nchan\Exception\InvalidUrlException
  instead of
  \InvalidArgumentException

Other changes

• Enhance code documentation
• Upgrade dev dependencies

Provide PSR-18 adapter

This client was built when PSR-18 did not exist. There were other HTTP abstractions such as HTTPlug, but since a PSR was being discussed, it was not used.

Using PSR-18 instead of the current http abstraction directly is a breaking change. This issue is about the creation of an adapter.

Drop support for php 7.3

Rename methods of StatusInformation and ChannelInformation

Be more explicit with method names. Maybe the comments are enough since the current implementation reflects the result from the nchan api.

Examples

// Current names
$statusInformation->storedMessages();
$statusInformation->sharedMemoryUsed();
// ...

// Suggested new names
$statusInformation->numberOfStoredMessages();
$statusInformation->sharedMemoryUsedInKilobyte();
// ...

Think about it.

Allow psr/http-message ^2.0

Fix versions so that they only work with php ^7.1

Problem
In the very start of the project the composer.json required php version >=7.1. This is a problem because an old version is installed under PHP 8 (and all other future versions). To prevent this, the tags in git and in the package registry must be overwritten to require php version ^7.1. This is not a good practice at all, as tags should never change (e.g. for caching reasons). However, PHP 8 will not be released until the end of November. This should give the package registries enough time to update.

Solution

1. Overwrite the history and assign the old tags to the new commits (rebase).
2. Checkout every tag and fix it with a new commit. The new commit is given the old tag.

Although solution 1 would be cleaner, solution 2 is chosen because it gives immediate results since there's no experience with such a rebase.

Branches to be fixed

• v1.0

Tags to be fixed

• 0.0.1
• 0.0.2
• 0.0.3
• 0.0.4
• 1.0.0
• 1.0.1
• 1.0.2
• 1.0.3
• 1.0.4

Add php 8.2 to test pipeline

Allow php ^8.0

Add php 7.3 to travis build

Add php 8.3 to test pipeline

Add php 8.1 to test pipeline

Release 3.0.1

Use commit f08c56d.

Add php 7.4 to automated test

Use typed properties

Implement the group api

Nchan has a concept named groups. A group configuration can be shown and can be changed.

Suggested implementation / collaborators

Code documentation and use statements has been removed for readability.

This class wraps the group api.

<?php

namespace Marein\Nchan\Api;

final class Group
{
    private $groupUrl;

    private $client;

    public function __construct(Url $groupUrl, Client $client)
    {
        $this->groupUrl = $groupUrl;
        $this->client = $client;
    }

    public function configuration(): GroupInformation
    {
        // Create and return value object for group information.
    }

    public function configure(): GroupConfigurator
    {
        return new GroupConfigurator($this->groupUrl, $this->client);
    }
}

This class acts like a builder for the group configuration. The configuration is sent when the configurate method is called.

<?php

namespace Marein\Nchan\Api;

final class GroupConfigurator
{
    private $groupUrl;

    private $client;

    public function __construct(Url $groupUrl, Client $client)
    {
        $this->groupUrl = $groupUrl;
        $this->client = $client;
    }

    public function changeMaximumNumberOfChannels(
        int $maximumNumberOfChannels
    ): GroupConfigurator
    {
        $this->groupUrl = $this->groupUrl->appendQueryString(
            'max_channels',
            $maximumNumberOfChannels
        );

        return $this;
    }

    public function changeMaximumNumberOfSubscribers(
        int $maximumNumberOfSubscribers
    ): GroupConfigurator
    {
        $this->groupUrl = $this->groupUrl->appendQueryString(
            'max_subs',
            $maximumNumberOfSubscribers
        );

        return $this;
    }

    public function configurate(): void
    {
        // Send request with configured items
    }
}