Integration branch for ably/pubsub-server v2 package

.gitattributes

@@ -0,0 +1,11 @@
+# Keep the Packagist dist archive to what a consumer actually installs.
+# GitHub zipballs honour export-ignore, so this trims the test suite, the
+# ably-common fixture submodule and the CI/planning files from every release.
+/tests            export-ignore
+/ably-common      export-ignore
+/.github          export-ignore
+/phpunit.xml      export-ignore
+/plan.md          export-ignore
+/.ably            export-ignore
+/.gitmodules      export-ignore
+/.gitattributes   export-ignore

.github/workflows/check.yml

@@ -6,6 +6,7 @@ on:
   push:
     branches:
       - main
+      - integration/v2
 
 permissions: {}
 
@@ -18,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-version: [7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4]
+        php-version: ['8.1', '8.2', '8.3', '8.4', '8.5']
         protocol: [ 'json', 'msgpack' ]
         ignorePlatformReq: [ '' ]
 
@@ -34,8 +35,8 @@ jobs:
           php-version: ${{ matrix.php-version }}
           ini-values: error_reporting=E_ALL
 
-      - name: Validate composer.json and composer.lock
-        run: composer validate
+      - name: Validate composer.json
+        run: composer validate --strict
 
       - name: Install dependencies
         env:

.github/workflows/features.yml

@@ -5,6 +5,7 @@ on:
   push:
     branches:
       - main
+      - integration/v2
 
 permissions: {}
 

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Change Log
 
+## [2.0.0](https://github.com/ably/ably-pubsub-php/tree/pubsub-server/2.0.0) (unreleased)
+
+[Full Changelog](https://github.com/ably/ably-pubsub-php/compare/1.1.12...pubsub-server/2.0.0)
+
+The first release of the `ably/pubsub-server` package, superseding
+`ably/ably-php`. See [`UPDATING.md`](./UPDATING.md) for the migration guide and
+the full mapping table.
+
+**Breaking changes:**
+
+- The package is now `ably/pubsub-server`, installed with `composer require ably/pubsub-server`. `ably/ably-php` is superseded and receives security and critical-bug fixes only for one year from this release, from the `maintenance/1.x` branch.
+- The namespace is now `Ably\PubSub\`. Every class other than the client keeps its name, so `Ably\Models\Message` becomes `Ably\PubSub\Models\Message`.
+- The client class `Ably\AblyRest` is now `Ably\PubSub\PubSubHttpClient` ([PDR-091d](https://ably.atlassian.net/wiki/spaces/product/pages/5363957781)). Applications that only construct through `Server::createHttpClient()` are unaffected; type hints and DI bindings naming the class must be updated.
+- Clients are constructed through `Ably\PubSub\Server::createHttpClient()`, which declares the server side on the wire. It accepts everything the constructor accepted: an options array, an API key string, a token string, or a `ClientOptions` instance. A client constructed directly declares no side, and is rejected on accounts with monthly-active-user pricing enabled.
+- Removed `AblyRest::setAblyAgentHeader()` and `AblyRest::setLibraryFlavourString()`, replaced by the per-client `agents` client option.
+- Removed `ably-loader.php`; Composer's autoloader is the only supported install path.
+- Added the `endpoint` client option (REC1, REC2), which is now the only way to choose where the client connects. The default primary domain is `main.realtime.ably.net`, with fallback hosts `main.[a-e].fallback.ably-realtime.com`.
+- Removed the `environment` and `restHost` client options in favour of `endpoint`. They are now ignored if passed, so a client still setting `environment` connects to production.
+- Setting `port` or `tlsPort` no longer disables the default fallback hosts; a hostname `endpoint` does.
+- `ClientOptions::getPrimaryRestHost()` is now `getPrimaryDomain()`. `Defaults::$restHost`, `Defaults::$realtimeHost` and `Defaults::getEnvironmentFallbackHosts()` are replaced by `Defaults::$endpoint`, `Defaults::getPrimaryDomain()` and `Defaults::getEndpointFallbackHosts()`.
+- Removed the `demo/` Heroku application and its `Procfile`.
+- The minimum supported PHP version is now 8.1; the SDK is tested on 8.1 through 8.5.
+
+**Other changes:**
+
+- The SDK agent identifier is now `ably-pubsub-php`, and the server side is declared by an `ably-pubsub-server` entry: `Ably-Agent: ably-pubsub-php/2.0.0 php/8.3.4 ably-pubsub-server`.
+- Added the `agents` client option (`array<string, string|null>`) so an SDK or framework built on this package can attribute its own traffic.
+- `rybakit/msgpack` is now constrained to `^0.9.1 || ^1.0`.
+
 ## [1.1.12](https://github.com/ably/ably-php/tree/1.1.12) (2026-06-23)
 
 [Full Changelog](https://github.com/ably/ably-php/compare/1.1.11...1.1.12)

CONTRIBUTING.md

@@ -3,6 +3,6 @@
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Ensure you have added suitable tests and the test suite is passing (run `vendor/bin/phpunit`)
+4. Ensure you have added suitable tests and the test suite is passing (run `vendor/bin/phpunit`). Tests run against the `nonprod:sandbox` endpoint; set `ABLY_ENDPOINT` to use another.
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request

README.md

@@ -1,6 +1,6 @@
 ![Ably Pub/Sub PHP Header](images/php-SDK-github.png)
-[![Latest Stable Version](https://poser.pugx.org/ably/ably-php/v/stable)](https://packagist.org/packages/ably/ably-php)
-[![License](https://poser.pugx.org/ably/ably-php/license)](https://github.com/ably/ably-pubsub-php/blob/main/LICENSE)
+[![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)
 
 ---
 
@@ -26,12 +26,29 @@ Everything you need to get started with Ably:
 
 ---
 
+## Package
+
+This SDK ships as a single package, `ably/pubsub-server`.
+
+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:
+
+```
+Ably-Agent: ably-pubsub-php/2.0.0 php/8.3.4 ably-pubsub-server
+```
+
+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.
+
+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.
+
+---
+
 ## Supported platforms
 
 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).
 
-> [!IMPORTANT]
-> PHP SDK versions < 1.1.9 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025.
+| Platform | Support |
+| --- | --- |
+| PHP | 8.1, 8.2, 8.3, 8.4, 8.5 |
 
 ---
 
@@ -42,14 +59,16 @@ For Laravel applications, consider these framework-integrated alternatives that
 * **[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.
 
+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.
+
 ---
 
 ## Installation
 
 To get started with your project, install the package:
 
 ```sh
-composer require ably/ably-php
+composer require ably/pubsub-server
 ```
 ---
 
@@ -59,8 +78,10 @@ composer require ably/ably-php
 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:
 
 ```php
-// Initialize Ably REST client
-$ably = new AblyRest(['key' => 'your-ably-api-key', 'clientId' => 'me']);
+use Ably\PubSub\Server;
+
+// Initialize the Ably HTTP (REST) client for a server
+$ably = Server::createHttpClient(['key' => 'your-ably-api-key', 'clientId' => 'me']);
 
 // Get a reference to the 'test-channel' channel
 $channel = $ably->channel('test-channel');
@@ -69,6 +90,27 @@ $channel = $ably->channel('test-channel');
 $channel->publish('test-event', 'hello world');
 ```
 
+`createHttpClient()` accepts everything the 1.x client constructor accepted: an options array, an API key string, a token string, or a `ClientOptions` instance.
+
+If your own SDK or framework wraps this package, name it so its traffic is attributed to it:
+
+```php
+$ably = Server::createHttpClient([
+    'key' => 'your-ably-api-key',
+    'agents' => ['my-framework' => '1.2.3'],
+]);
+```
+
+---
+
+## Migrating from `ably/ably-php` 1.x
+
+`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.
+
+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.
+
+---
+
 ## Releases
 
 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).
@@ -79,6 +121,8 @@ The [CHANGELOG.md](./CHANGELOG.md) contains details of the latest releases for t
 
 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.
+
 ---
 
 ## Support, feedback, and troubleshooting
@@ -87,4 +131,4 @@ For help or technical support, visit the [Ably Support page](https://ably.com/su
 
 ### Ably REST API
 
-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.
+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.

UPDATING.md

@@ -0,0 +1,122 @@
+# Upgrade / Migration Guide
+
+## 1.x (`ably/ably-php`) → 2.0.0 (`ably/pubsub-server`)
+
+Version 2.0.0 ships from a new package, `ably/pubsub-server`, under a new namespace, `Ably\PubSub\`. `ably/ably-php` is superseded: it receives security and critical-bug fixes only for one year from the 2.0.0 release date, and is then end-of-life.
+
+Under monthly-active-user pricing the platform has to classify every connection as device-side or server-side. The new package declares that automatically, on every request, in the `Ably-Agent` header; the old constructor cannot declare anything. That is the forcing function for this migration: once monthly-active-user pricing is live, `new Ably\AblyRest(...)` from `ably/ably-php` is rejected on accounts where it is enabled.
+
+The client `Server::createHttpClient()` returns is the same REST client as before, renamed from `AblyRest` to `PubSubHttpClient`. Channels, message publishing, history, presence, authentication, push admin and crypto behave exactly as they did in 1.x. The one change to `ClientOptions` is how the client chooses where to connect: the `endpoint` option replaces `environment` and `restHost` (see [Endpoint](#endpoint-replaces-environment-and-resthost)). For most applications the migration is confined to the `composer require` line, the `use` statements, the constructor call, and any host options.
+
+### Mapping
+
+| 1.x (`ably/ably-php`) | 2.0 (`ably/pubsub-server`) |
+| --- | --- |
+| `composer require ably/ably-php` | `composer require ably/pubsub-server` |
+| `use Ably\AblyRest;` / `new AblyRest($opts)` | `use Ably\PubSub\Server;` / `Server::createHttpClient($opts)` |
+| `use Ably\Models\Message;` (any `Ably\X` type) | `use Ably\PubSub\Models\Message;` (`Ably\PubSub\X`) |
+| `AblyRest::setAblyAgentHeader('x', 'v')` | `Server::createHttpClient(['agents' => ['x' => 'v'], …])` |
+| `AblyRest::setLibraryFlavourString('x')` | removed — use the `agents` option |
+| `require 'ably-loader.php';` | removed — use Composer's autoloader (`vendor/autoload.php`) |
+| PHP 7.2 – 8.0 | PHP `^8.1` (tested on 8.1 – 8.5) |
+| `\Ably\AblyRest` type hints | `\Ably\PubSub\PubSubHttpClient` ([091d](https://ably.atlassian.net/wiki/spaces/product/pages/5363957781)) |
+| `'environment' => 'sandbox'` / `'restHost' => '…'` | `'endpoint' => …` (see [Endpoint](#endpoint-replaces-environment-and-resthost)) |
+
+Every class moves namespace, and `AblyRest` is the only one that also changes name, so the rename is mechanical: replace the prefix `Ably\` with `Ably\PubSub\` throughout — including in type hints, `catch` blocks and fully-qualified string class names — and then `AblyRest` with `PubSubHttpClient`.
+
+### Example
+
+```php
+// 1.x
+use Ably\AblyRest;
+
+$ably = new AblyRest(['key' => getenv('ABLY_API_KEY'), 'clientId' => 'me']);
+$ably->channel('test-channel')->publish('test-event', 'hello world');
+
+// 2.0
+use Ably\PubSub\Server;
+
+$ably = Server::createHttpClient(['key' => getenv('ABLY_API_KEY'), 'clientId' => 'me']);
+$ably->channel('test-channel')->publish('test-event', 'hello world');
+```
+
+`createHttpClient()` accepts everything the 1.x constructor accepted: an options array, an API key string, a token string, or a `ClientOptions` instance. A `ClientOptions` instance you pass in is copied rather than mutated.
+
+### Endpoint replaces environment and restHost
+
+The `endpoint` client option is now the only way to choose where the client connects. `environment` and `restHost` are removed. Like any other unknown key, they are now ignored, so a client still passing `'environment' => 'sandbox'` connects to production: replace them before upgrading.
+
+| 1.x | 2.0 |
+| --- | --- |
+| no host options | no change; traffic moves from `rest.ably.io` to `main.realtime.ably.net` |
+| `'environment' => 'sandbox'` | `'endpoint' => 'nonprod:sandbox'` |
+| `'environment' => 'acme'` (dedicated cluster) | `'endpoint' => 'acme'` |
+| `'restHost' => 'localhost'` | `'endpoint' => 'localhost'` |
+| `'restHost' => 'rest.example.com'` | `'endpoint' => 'rest.example.com'` |
+| custom `'fallbackHosts' => […]` | unchanged |
+
+How `endpoint` resolves:
+
+| `endpoint` | Primary domain | Default fallback hosts |
+| --- | --- | --- |
+| unset (`main`) | `main.realtime.ably.net` | `main.[a-e].fallback.ably-realtime.com` |
+| `[id]`, e.g. `acme` | `[id].realtime.ably.net` | `[id].[a-e].fallback.ably-realtime.com` |
+| `nonprod:[id]`, e.g. `nonprod:sandbox` | `[id].realtime.ably-nonprod.net` | `[id].[a-e].fallback.ably-realtime-nonprod.com` |
+| a hostname: contains `.` or `::`, or is `localhost` | the value as given | none |
+
+A non-empty `fallbackHosts` still replaces the default fallback hosts. Setting `port` or `tlsPort` no longer disables the default fallback hosts; only a hostname `endpoint` does.
+
+```php
+// 1.x
+$ably = new AblyRest(['key' => getenv('ABLY_API_KEY'), 'environment' => 'sandbox']);
+
+// 2.0
+$ably = Server::createHttpClient(['key' => getenv('ABLY_API_KEY'), 'endpoint' => 'nonprod:sandbox']);
+```
+
+`ClientOptions::getPrimaryRestHost()` is renamed `getPrimaryDomain()`, and `Defaults::$restHost`, `Defaults::$realtimeHost` and `Defaults::getEnvironmentFallbackHosts()` are replaced by `Defaults::$endpoint`, `Defaults::getPrimaryDomain()` and `Defaults::getEndpointFallbackHosts()`.
+
+Firewall allowlists and outbound proxies must allow `*.realtime.ably.net` and `*.fallback.ably-realtime.com` in place of `rest.ably.io` and `*.ably-realtime.com`.
+
+### Declaring the side
+
+Construct through the door. `new Ably\PubSub\PubSubHttpClient(...)` still works — the library and its own tests use it — but it declares no side, and will be rejected on monthly-active-user-enabled accounts just as the 1.x constructor is. The door produces:
+
+```
+Ably-Agent: ably-pubsub-php/2.0.0 php/8.3.4 ably-pubsub-server
+```
+
+If you are building an SDK or framework on top of this package, name it through the `agents` option instead of the removed static setters. Your entries are preserved, in order, ahead of the side entry:
+
+```php
+$ably = Server::createHttpClient([
+    'key' => getenv('ABLY_API_KEY'),
+    'agents' => ['laravel' => '11.0.0', 'laravel-broadcaster' => '1.0.4'],
+]);
+
+// Ably-Agent: ably-pubsub-php/2.0.0 php/8.3.4 laravel/11.0.0 laravel-broadcaster/1.0.4 ably-pubsub-server
+```
+
+The `agents` option is per-client, unlike the process-global static setters it replaces, so two clients in one process can carry different attribution.
+
+### Removed in 2.0.0
+
+* `AblyRest::setAblyAgentHeader()` and `AblyRest::$agents` — replaced by the per-client `agents` option.
+* `AblyRest::setLibraryFlavourString()` — already deprecated in 1.x; replaced by the same option.
+* `ably-loader.php`, the hand-rolled autoloader — Composer is the only supported install path.
+* The `environment` and `restHost` client options — replaced by `endpoint`. They are ignored if passed.
+* The `demo/` Heroku application and its `Procfile`.
+* PHP 7.2 – 8.0 support.
+
+`Auth::authorise()`, the British-spelling alias deprecated in favour of `Auth::authorize()`, is still present in 2.0.0.
+
+### Unchanged
+
+* The REST client and its whole surface: `channel()`, `channels`, publishing, message history, presence and presence history, `auth`, token requests and token issuing, `push` admin, `stats`, `time()`, and crypto.
+* Every `ClientOptions` key other than the host options above, and the array / key-string / token-string / `ClientOptions` forms of the constructor argument.
+* Message and error semantics, including `AblyException` and its codes.
+* Requirements: `ext-json`, `ext-curl`, `ext-openssl`, and `rybakit/msgpack` for the msgpack protocol.
+
+### Staying on 1.x
+
+`ably/ably-php` 1.x is maintained on the `maintenance/1.x` branch of this repository. It gets security and critical-bug fixes for one year from the 2.0.0 release date and no new features, then reaches end-of-life. Both packages can be installed side by side during a migration: they declare different namespaces and different PSR-4 prefixes, so their autoloading does not collide.