Rewrite the README for the 2.0 SDK

README.md

@@ -1,134 +1,197 @@
-![Ably Pub/Sub PHP Header](images/php-SDK-github.png)
-[![Latest Stable Version](https://poser.pugx.org/ably/pubsub-server/v/stable)](https://packagist.org/packages/ably/pubsub-server)
-[![License](https://poser.pugx.org/ably/pubsub-server/license)](https://github.com/ably/ably-pubsub-php/blob/main/LICENSE)
+![Ably Pub/Sub PHP Header](https://raw.githubusercontent.com/ably/ably-pubsub-php/main/images/php-SDK-github.png)
 
----
+[![Packagist: ably/pubsub-server](https://img.shields.io/packagist/v/ably/pubsub-server?label=ably%2Fpubsub-server)](https://packagist.org/packages/ably/pubsub-server)
+[![License](https://badgen.net/github/license/ably/ably-pubsub-php)](https://github.com/ably/ably-pubsub-php/blob/main/LICENSE)
 
 # Ably Pub/Sub PHP SDK
 
-Build using Ably’s Pub/Sub PHP SDK, supported on all popular platforms and frameworks.
+The PHP SDK for [Ably Pub/Sub](https://ably.com/docs/basics): publish messages to channels, read
+message history and presence, and issue tokens for your users, from servers over HTTP.
 
-Ably Pub/Sub provides flexible APIs that deliver features such as pub-sub messaging, message history, presence, and push notifications. Utilizing Ably’s realtime messaging platform, applications benefit from its highly performant, reliable, and scalable infrastructure.
+## Overview
 
-Find out more:
+This SDK provides the server package only, for trusted backends authenticating with an API key.
+There is no device package; for end-user devices, use a device SDK such as
+[JavaScript](https://github.com/ably/ably-pubsub-js), [Swift/Objective-C](https://github.com/ably/ably-pubsub-cocoa),
+[Java/Android](https://github.com/ably/ably-pubsub-java), [.NET](https://github.com/ably/ably-pubsub-dotnet)
+or [Flutter](https://github.com/ably/ably-pubsub-flutter).
 
-* [Ably Pub/Sub docs.](https://ably.com/docs/basics)
-* [Ably Pub/Sub examples.](https://ably.com/examples?product=pubsub)
+| Package | Use it for | Entry point |
+|---------|-----------|-------------|
+| `ably/pubsub-server` | Servers and other trusted backend environments | `Ably\PubSub\Server::createHttpClient()` |
 
----
+## Requirements
 
-## Getting started
+PHP 8.1 or later (tested on 8.1 to 8.5), with the `curl`, `json` and `openssl` extensions.
 
-Everything you need to get started with Ably:
+## Installation
 
-* [Getting started with Pub/Sub using PHP.](https://ably.com/docs/getting-started/php)
-* [SDK Setup for PHP.](https://ably.com/docs/getting-started/setup?lang=php)
+```bash
+composer require ably/pubsub-server
+```
 
----
+## Quick start
 
-## Package
+Use an API key on a server. The samples read it from the `ABLY_API_KEY` environment variable; set it
+to an API key from your [Ably dashboard](https://ably.com/accounts/any/apps/any/app_keys). The
+following code publishes a message over HTTP, then reads the channel's history.
 
-This SDK ships as a single package, `ably/pubsub-server`.
+```php
+<?php
+require __DIR__ . '/vendor/autoload.php';
 
-The package name declares where your code runs. A server is a trusted runtime: it typically authenticates with an API key, one that a browser or a mobile app must never hold, and its connections are exempt from monthly-active-user counting. That declaration has to reach Ably rather than only the README, so the package sends it on every request in the `Ably-Agent` header:
+use Ably\PubSub\Server;
 
-```
-Ably-Agent: ably-pubsub-php/2.0.0 php/8.3.4 ably-pubsub-server
+$ablyApiKey = getenv('ABLY_API_KEY');
+$client = Server::createHttpClient(['key' => $ablyApiKey]);
+$channel = $client->channels->get('test-channel');
+
+$channel->publish('test-event', 'hello world');
+
+$history = $channel->history();
+foreach ($history->items as $message) {
+    echo "Received: {$message->name}: {$message->data}\n";
+}
 ```
 
-The trailing `ably-pubsub-server` entry is the part the platform matches on. It is stamped by `Ably\PubSub\Server::createHttpClient()`, so a client constructed any other way declares no side, and will be rejected on accounts that have monthly-active-user pricing enabled.
+A failed request throws an `Ably\PubSub\Exceptions\AblyException`.
 
-This is the only Ably Pub/Sub package for PHP. There is no device package and no separate core package to depend on, because PHP is a server-side language: this SDK is REST-only and there is no PHP realtime client. See the [Ably REST API](#ably-rest-api) note below for realtime options.
+Always create clients with `Server::createHttpClient()`. A client created with
+`new PubSubHttpClient(...)` does not declare itself as a server.
 
----
+> [!IMPORTANT]
+> Server clients must authenticate with an API key. To use a token instead, see [Server clients and token authentication](https://ably.com/docs/auth/token#server-token-auth).
 
-## Supported platforms
+The following script issues token requests at `/ably-auth`. Devices using a device SDK set
+`authUrl` to its URL, for example `https://your-server.example.com/ably-auth`:
 
-Ably aims to support a wide range of platforms. If you experience any compatibility issues, open an issue in the repository or contact [Ably support](https://ably.com/support).
+```php
+<?php
+// ably-auth.php: serve this script at /ably-auth.
+require __DIR__ . '/vendor/autoload.php';
 
-| Platform | Support |
-| --- | --- |
-| PHP | 8.1, 8.2, 8.3, 8.4, 8.5 |
+use Ably\PubSub\Server;
 
----
+$ablyApiKey = getenv('ABLY_API_KEY');
+$client = Server::createHttpClient(['key' => $ablyApiKey]);
 
-## Laravel packages
+// Authenticate the caller first. Grant only the operations this user needs.
+$userId = 'me'; // the signed-in user's ID, from your session
+$tokenRequest = $client->auth->createTokenRequest([
+    'clientId' => $userId,
+    // Without a capability, the token gets all of the API key's capabilities.
+    'capability' => ['test-channel' => ['publish', 'subscribe', 'history']],
+]);
 
-For Laravel applications, consider these framework-integrated alternatives that provide Laravel integration with automatic configuration and native broadcasting support, eliminating the boilerplate setup required when using the raw PHP SDK directly:
+header('Content-Type: application/json');
+echo json_encode($tokenRequest->toArray());
+```
 
-* **[Ably Pub/Sub PHP Laravel SDK](https://github.com/ably/ably-php-laravel)** - Laravel integration package with clean facade and dependency injection interface.
-* **[Ably Broadcaster for Laravel](https://github.com/ably/laravel-broadcaster)** - Official Laravel broadcaster for real-time event broadcasting.
+See [token authentication](https://ably.com/docs/auth/token) for how devices use it.
 
-Each needs a new major version to run on `ably/pubsub-server`; their current releases depend on `ably/ably-php` 1.x. Those majors ship in the same release window as this package.
+On Laravel, use the [Laravel broadcaster](https://github.com/ably/laravel-broadcaster) instead: it
+issues tokens to Ably's fork of Laravel Echo from Laravel's `/broadcasting/auth` route.
 
----
+## Migrating from 1.x
 
-## Installation
+Version 2.0 renames the package and namespace, and creates clients with a factory method.
 
-To get started with your project, install the package:
+| | 1.x | 2.0 |
+|---|---|---|
+| Package | `ably/ably-php` | `ably/pubsub-server` |
+| Namespace | `Ably\` | `Ably\PubSub\` |
+| HTTP client | `new AblyRest($options)` | `Server::createHttpClient($options)` |
 
-```sh
-composer require ably/pubsub-server
-```
----
+See [UPDATING.md](https://github.com/ably/ably-pubsub-php/blob/main/UPDATING.md#1x-ablyably-php--200-ablypubsub-server) for all other changes.
 
+## Common configuration
 
-## Usage
+`Server::createHttpClient()` takes an options array or an `Ably\PubSub\Models\ClientOptions`
+object.
 
-The following code connects to Ably's REST messaging service, gets reference to a channel to receive messages, and publishes a test message to that same channel:
+### Endpoint
+
+`endpoint` selects the Ably host for HTTP requests. It replaces the 1.x `environment` and
+`restHost` options. 2.0 ignores those options, so a client that still sets them connects to
+production.
 
 ```php
-use Ably\PubSub\Server;
+$ablyApiKey = getenv('ABLY_API_KEY');
+$client = Server::createHttpClient([
+    'key' => $ablyApiKey,
+    'endpoint' => 'nonprod:sandbox',
+]);
+```
 
-// Initialize the Ably HTTP (REST) client for a server
-$ably = Server::createHttpClient(['key' => 'your-ably-api-key', 'clientId' => 'me']);
+- Never put a port in `endpoint`: `localhost:8080` is not a hostname and does not resolve.
+- Set the port with `tlsPort`, or with `port` when TLS is off.
+- With TLS off (`'tls' => false`), use token authentication.
 
-// Get a reference to the 'test-channel' channel
-$channel = $ably->channel('test-channel');
+See [UPDATING.md](https://github.com/ably/ably-pubsub-php/blob/main/UPDATING.md#endpoint-replaces-environment-and-resthost) for how the old options
+map to `endpoint`.
 
-// Publish a test message to the channel
-$channel->publish('test-event', 'hello world');
+### Proxy
+
+To send every request through a proxy, set `http_proxy` (or `https_proxy`) in `$_SERVER`. From
+the PHP command line, an environment variable does this. Put any proxy credentials in the URL:
+
+```bash
+export http_proxy=http://username:password@proxy.example.com:8080
 ```
 
-`createHttpClient()` accepts everything the 1.x client constructor accepted: an options array, an API key string, a token string, or a `ClientOptions` instance.
+### Logging
 
-If your own SDK or framework wraps this package, name it so its traffic is attributed to it:
+Set `logLevel` to `Log::NONE`, `Log::ERROR`, `Log::WARNING` (the default), `Log::DEBUG` or
+`Log::VERBOSE`. Logs go to standard output. To handle them yourself, set `logHandler`:
 
 ```php
-$ably = Server::createHttpClient([
-    'key' => 'your-ably-api-key',
-    'agents' => ['my-framework' => '1.2.3'],
+use Ably\PubSub\Log;
+use Ably\PubSub\Server;
+
+$ablyApiKey = getenv('ABLY_API_KEY');
+$client = Server::createHttpClient([
+    'key' => $ablyApiKey,
+    'logLevel' => Log::DEBUG,
+    'logHandler' => function ($level, $args) {
+        error_log('Ably: ' . json_encode($args));
+    },
 ]);
 ```
 
----
+Logging settings are global: the most recently created client sets them for the whole process.
 
-## Migrating from `ably/ably-php` 1.x
+## Platform notes
 
-`ably/pubsub-server` 2.0.0 supersedes `ably/ably-php`. The client it returns is the same REST client, so for most applications the migration is confined to the `composer require` line, the `use` statements, and the constructor call. [UPDATING.md](./UPDATING.md) has the full mapping table and a before/after example.
+### Laravel
 
-If you are staying on 1.x for now, it is maintained on the `maintenance/1.x` branch of this repository, and receives security and critical-bug fixes only for one year from the 2.0.0 release.
+The current releases of Ably's [Laravel broadcaster](https://github.com/ably/laravel-broadcaster)
+and [Laravel SDK](https://github.com/ably/ably-php-laravel) depend on `ably/ably-php` 1.x, not on
+`ably/pubsub-server`. See [Getting started with Laravel](https://ably.com/docs/getting-started/laravel).
 
----
+## Known limitations
 
-## Releases
+- The SDK has no realtime client. It uses the [Ably REST API](https://ably.com/docs/api/rest-api)
+  only, so it can't subscribe to channels or enter presence.
+- To receive messages in PHP, use Ably's [MQTT adapter](https://ably.com/docs/protocols/mqtt)
+  with an MQTT client such as [Mosquitto-PHP](https://github.com/mgdm/Mosquitto-PHP).
 
-The [CHANGELOG.md](./CHANGELOG.md) contains details of the latest releases for this SDK. You can also view all Ably releases on [changelog.ably.com](https://changelog.ably.com).
+## Further reading
 
----
+- [Getting started with Pub/Sub using PHP](https://ably.com/docs/getting-started/php)
+- [Ably Pub/Sub documentation](https://ably.com/docs/basics) and [examples](https://ably.com/examples?product=pubsub)
+- [Token authentication](https://ably.com/docs/auth/token)
+- [UPDATING.md](https://github.com/ably/ably-pubsub-php/blob/main/UPDATING.md): migrating from 1.x
+- [CHANGELOG.md](https://github.com/ably/ably-pubsub-php/blob/main/CHANGELOG.md): release notes; all Ably releases are listed on [changelog.ably.com](https://changelog.ably.com)
 
 ## Contributing
 
-Read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines to contribute to Ably.
-
-Development happens in this repository, `ably-pubsub-php`. The Packagist package is published from a read-only distribution mirror, so issues and pull requests belong here.
-
----
+Read [CONTRIBUTING.md](https://github.com/ably/ably-pubsub-php/blob/main/CONTRIBUTING.md) before contributing.
 
-## Support, feedback, and troubleshooting
+## Support, feedback and troubleshooting
 
-For help or technical support, visit the [Ably Support page](https://ably.com/support).
+For help, visit Ably's [support page](https://ably.com/support). Report bugs and compatibility
+problems on [GitHub Issues](https://github.com/ably/ably-pubsub-php/issues).
 
-### Ably REST API
+## License
 
-This SDK currently supports only the [Ably REST API](https://www.ably.com/docs/rest). For realtime capabilities, you can use the [MQTT adapter](https://www.ably.com/docs/mqtt) alongside [Mosquitto PHP](https://github.com/mgdm/Mosquitto-PHP) to implement Ably's Realtime features.
+Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/ably/ably-pubsub-php/blob/main/LICENSE).