Download the PHP package survos/wordpress-bundle without Composer

survos/wordpress-bundle

Symfony bundle client for the WordPress REST API (/wp-json/wp/v2) — posts, pages, media, taxonomies, users, and custom post types — built on Symfony's own HttpClient.

Multi-site by design: one app routinely talks to more than one WordPress install, so sites are named in configuration and each gets its own client.

Why this exists

Two Survos apps integrated with WordPress in two unrelated ways (survos-sites/ff#5):

• ff used vnn/wordpress-rest-api-client, an unmaintained Guzzle/PSR-7 library whose composer.json still caps psr/http-message at ^1.0. Nothing else in the tree does — aws-sdk-php, guzzle/psr7, nyholm/psr7, google/auth and symfony/psr-http-message-bridge all accept ^1.1 || ^2.0 — so that single package was the reason survos/elastic-bundle could not be installed there at all (elasticsearch/elasticsearch requires psr/http-message ^2.0).
• kpa hand-rolled the same integration with HttpClient::create(), raw curl strings and exec().

This bundle replaces both. It has no PSR-7 dependency of any kind, so nothing it brings in can pin psr/http-message.

Installation

Configuration

Every key is optional. With no sites at all, one site named default is registered from WORDPRESS_BASE_URL / WORDPRESS_USERNAME / WORDPRESS_APPLICATION_PASSWORD.

Credentials are Application Passwords

application_password is a WordPress Application Password (Users → Profile → Application Passwords, core since WP 5.6), not the account password. The generated value contains spaces; paste it as-is. It is sent as HTTP Basic auth, so the site must be HTTPS.

Credentials are only needed for writes. Reading public posts, pages and media works with no credentials at all, and in that case no Authorization header is sent.

Usage

Choosing a site at runtime (a --site option, a per-tenant lookup) goes through the registry:

Endpoints

posts(), pages(), media(), categories(), tags(), comments(), users(), types(), statuses(), taxonomies() — plus resource() for anything else:

Every endpoint offers:

Raw arrays are the contract; DTOs (WpPost, WpTerm, WpMedia, WpUser) are a convenience and each keeps its source array on ->raw. WordPress records carry arbitrary plugin/ACF keys that no DTO can enumerate, so unknown fields are never dropped and never cause a hydration failure. Text fields arrive as {"rendered": "…"} in the default context and as plain strings in others; the DTOs flatten both.

Uploading media

WordPress creates an attachment from the raw file bytes plus a Content-Disposition filename — not multipart, not JSON — and metadata cannot ride along in that request. upload() handles both halves:

Fetch strategy (retry / cache / rate limits)

Retry is on by default: transport errors and HTTP 500/502/503/504 are retried with exponential backoff (Symfony's RetryableHttpClient).

429 is deliberately excluded from that list. It surfaces as RateLimitException carrying the server's own Retry-After, so a caller — a Messenger consumer, a batch import — can reschedule itself with the real delay. Retrying it inside the HTTP client would swallow that signal. This is a live concern rather than a theoretical one: managed WordPress hosts (WP Engine among them) rate-limit /wp-json/ aggressively.

Caching (cache_enabled) wraps the client in Symfony's RFC 9111 CachingHttpClient via survos/fetch-bundle's shared factory. It is off by default, and that default is deliberate: WordPress core sends Cache-Control: no-cache on REST responses, so an RFC-9111 cache is a no-op against a stock install. Turn it on only for a site fronted by a CDN or a caching plugin that emits real freshness headers.

Errors

Everything thrown implements WordpressExceptionInterface. WordPress error bodies are structured — {"code":"rest_post_invalid_id","message":"…","data":{"status":404}} — and both the machine code and the human message are parsed onto the exception rather than collapsed into "Unexpected response":

Console commands

wordpress:ping fetches the REST index and, when credentials are configured, verifies them against wp/v2/users/me — the fastest way to tell a wrong Application Password from a host that strips the Authorization header before it reaches PHP (the two are indistinguishable from the response alone).

Migrating from vnn/wordpress-rest-api-client

The surface was kept close on purpose, including save()'s create-or-update-on-id behaviour:

The one behavioural difference worth knowing: vnn's get() with no id returned a single page and silently stopped at WordPress' default of 10 records. list() does the same thing explicitly; iterate() is what you want when you meant "all of them".

Not included

• No OAuth / JWT / nonce-cookie auth. Application Passwords cover server-to-server access, which is the only case these apps have. Cookie auth requires a nonce from a logged-in browser session and does not apply.
• No WordPress entity/Doctrine mapping. This is a client, not a sync layer. Apps own their own entities (kpa's Song::$wordpressPageId, ff's Article).
• No block/Gutenberg parsing. content comes back as rendered HTML or as raw block markup depending on context; interpreting it belongs to the app.