Docs and migration guide for the ably/pubsub-server 2.0 split

[umair-ably]

Plan steps 19 and 20 of plan.md, plus the 2.0.0 CHANGELOG body — row 5 of the PR stack. Stacked on #225 (which is stacked on #223) — review those first; this diff shows only the docs changes.

Docs only. No file under src/, tests/, .github/ or composer.json is touched, and neither is CONTRIBUTING.md (PR 2 owns its release section).

What changed

File	Change
README.md	Rewritten for ably/pubsub-server: badges, install line and quickstart move onto the new package and the door; a new Package section; a supported-platforms table on the 8.1–8.5 floor replacing the protocol-v1 deprecation notice; a Migrating from ably/ably-php 1.x section; a 1.x pointer at maintenance/1.x; a note that Packagist is fed from a read-only mirror.
UPDATING.md	New. The 1.x → 2.0.0 section: why, the mapping table, a before/after example, the side declaration, removals, what is unchanged, and staying on 1.x.
CHANGELOG.md	The body of the ## [2.0.0] entry PR 1 added. The heading and compare link are unchanged byte for byte, because tests/PackagingTest.php reads Defaults::LIB_VERSION out of that heading.

Why a single package

PHP ships one package, ably/pubsub-server, where the other SDKs ship a core plus side packages — and the README says so rather than leaving it as an apparent omission. PHP is server-only and REST-only: there is no realtime client and no device package, so a core would have exactly one consumer, and PHP cannot re-export types, so consumers would have to use classes out of a package labelled internal. Packagist binds every Composer-valid tag of a repository to the package, so a second package would mean a second repository and a second mirror to operate for no consumer benefit. That is plan.md step 1 and PDR-091b2, whose PHP row names only ably/pubsub-server. The consequence the README carries: development happens here, and the package is published from a read-only distribution mirror.

Mapping table (as written in UPDATING.md)

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
PHP 7.2 – 8.0	PHP ^8.1 (tested 8.1 – 8.5)
⚠️ 091d: \Ably\AblyRest type hints	\Ably\PubSub\HttpClient (not yet decided)

Auth::authorise() is still present in 2.0.0 — checked against #223's diff, which removes only the two static agent setters, the loader and the demo. The guide says so, and says it may go in the 091d pass.

How the samples were verified

Every snippet in both files was executed, not read. Two scratch scripts (not committed) load vendor/autoload.php and the tests\HttpMock transport from tests/HttpTest.php, run each sample against it, and read the Ably-Agent header back out of CURLOPT_HTTPHEADER.

$ php snippets.php
quickstart channel: Ably\PubSub\Channel
quickstart agent  : ably-pubsub-php/2.0.0 php/8.5.10 ably-pubsub-server
wire shape matches README: yes
wrapper agent     : ably-pubsub-php/2.0.0 php/8.5.10 laravel/11.0.0 laravel-broadcaster/1.0.4 ably-pubsub-server
door accepts key string: Ably\PubSub\AblyRest
door accepts token string: Ably\PubSub\AblyRest
door accepts ClientOptions: ably-pubsub-php/2.0.0 php/8.5.10 ably-pubsub-server
caller ClientOptions unmutated: yes
surface auth: Ably\PubSub\Auth
surface push: Ably\PubSub\Push
surface channels: Ably\PubSub\Channels
Auth::authorise exists: yes
setAblyAgentHeader exists: no
setLibraryFlavourString exists: no
LIB_VERSION: 2.0.0
ALL OK

$ php updating.php
publish path agent: ably-pubsub-php/2.0.0 php/8.5.10 ably-pubsub-server
AblyException: Ably\PubSub\Exceptions\AblyException
stats: yes, time: yes
OK

So: the door's header is asserted equal to ably-pubsub-php/2.0.0 php/<PHP_VERSION> ably-pubsub-server (the header carries the full PHP_VERSION, 8.5.10 locally, 8.3.4 in the documented example); the wrapper sample's agents entries land in order ahead of the side entry; each of the four argument forms the guide claims the door accepts was actually passed to it; the "unchanged" list was checked against the live object; and both removals the mapping table asserts were confirmed absent via method_exists.

$ vendor/bin/phpunit --filter PackagingTest
OK (7 tests, 11 assertions)

testLibVersionMatchesTheTopChangelogEntry is the one that would catch a CHANGELOG heading edit, and it passes.

Links: every external URL in both files returns 200 under curl -sI -L. The two poser.pugx.org badge URLs also return 200 and render a placeholder, since the package is not on Packagist yet. Markdown reviewed rendered.

Follow-ups

• Badges show "no stable version" until ably/pubsub-server is registered on Packagist (plan step 15c). The poser.pugx.org URLs are correct now and start resolving then; the Packagist link redirects to the Packagist homepage until registration (checked: it does not 404).
• Repo links stay on ably/ably-php except the licence badge target, which matches what Update repository references for rename to ably-pubsub-php #222 already changed. The rename (step 17) / Update repository references for rename to ably-pubsub-php #222 handles the rest.
• 091d rename pass (PR 6) will need a pass over both files if AblyRest becomes HttpClient; the guide's draft banner says so.
• Docs repo: the 23 PHP-bearing pages are the docs team's cross-SDK pass. The mapping table above is what they need.
• Laravel wrappers (step 27): the README and the guide both state the wrappers need their new majors on this package; those PRs must be open before GA.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}