Download the PHP package hampel/xenforo-api-laravel without Composer

XenForo API for Laravel

By Simon Hampel

Laravel integration for hampel/xenforo-api — a service provider, a manager for named forums, and a facade.

Two things it adds that an application would otherwise write for itself:

• Http::fake() sees the API client's traffic. The core package carries its own PSR-18 client, so by default Laravel's HTTP fakes know nothing about it and an application has to fake at the transport library instead. Here every request goes through Laravel's own handler stack, so Http::fake(), Http::assertSent() and Http::preventStrayRequests() all work.
• Named forums. A URL and a credential per forum, a default, and XenForo::forum('name') to reach one — the shape Laravel's own database and mail managers take.

It supplies the transport and nothing else. The core package's request building, status mapping and exception hierarchy are untouched, which is the point: a 401 and a 404 stay different exceptions rather than both becoming an unsuccessful response.

Requirements

PHP 8.3 or later, and Laravel 12 or 13.

Laravel Zero is supported too, with two extra steps covered under Installation. It needs the HTTP component, which an application opts into with php <app> app:install http (that command runs composer require illuminate/http and nothing else).

Installation

In a Laravel application the provider and the XenForo alias are discovered automatically. Publish the config file if you want to edit it:

Laravel Zero

Laravel Zero switches package discovery off, so register the provider yourself in config/app.php:

The XenForo alias comes from the same discovery, so it is not registered either — import Hampel\XenForo\Api\Laravel\Facades\XenForo by its class name. To edit the config, copy vendor/hampel/xenforo-api-laravel/config/xenforo.php into the application's config/.

Registering the provider also closes a gap in Http::fake(). Laravel binds Illuminate\Http\Client\Factory as a singleton in FoundationServiceProvider, which a Laravel Zero application does not register, and the HTTP component installs the classes without binding anything. Unbound, the container builds a fresh factory on every resolution, so the one this package holds is not the one Http::fake() configures, and the fake would miss: the request would go to the real forum. The provider binds a singleton when nothing else has. Without the provider nothing is bound at all, and resolving a client fails with a BindingResolutionException rather than reaching the network.

Configuration

A forum needs a URL. Everything else is optional.

The shipped config/xenforo.php defines one forum called main. Add more by naming them:

Either the board URL or the /api URL is accepted; both are normalised.

Credentials

XenForo accepts three quite different credentials on the same endpoints, and which one you hold changes what you may ask for:

Two combinations are refused when the client is built, because both otherwise fail somewhere far less obvious:

• a forum with no url — which would reach the core package as an empty base URI;
• user with no key — which would be sent as a guest and answered, so the call succeeds and quietly returns less than it should.

Both raise Hampel\XenForo\Api\Laravel\Exception\InvalidConfiguration, which extends the core package's XenForoException, so an application already catching that catches misconfiguration too.

bypassPermissions is deliberately not configurable. It belongs to a super-user key and to no other credential, and it is per-call by nature:

Transport

Applied to every request, alongside any Http::globalRequestMiddleware() the application has configured. Http::globalOptions() applies too, but only its transport options: timeouts, TLS verification and client certificates, proxy, protocol version and curl settings. Global headers, query and body options are ignored, because the request is built by the core package and they would overwrite its API key, its query string or its body.

Redirects are not followed — Guzzle's PSR-18 entry point does not follow them, so a 3xx is handed back whole. That is what the two attachment thumbnail endpoints need, since the 301 they answer with is their documented output.

Usage

The facade reaches the default forum directly:

Name a forum to reach another:

Everything past that point is the core package — see its documentation for the endpoints, the entities, pagination, uploads, OAuth2 and how to call an endpoint an add-on added that neither package has heard of.

Inject the manager where a facade is not wanted:

Forums that are not in configuration

When the forum list lives somewhere other than config/xenforo.php — a database table, per-tenant settings, a file read on demand to keep API keys out of the config repository — build a client from an array instead:

The array takes the same keys as an entry under xenforo.forums, and gets the same validation and choice of credential. The client sends through the same transport, so Http::fake() and Http::preventStrayRequests() reach it. Each call builds a new client and nothing is memoised, so keep the one you get.

The transport is bound under the container key xenforo.http_client, with PSR-17 factories beside it, for constructing a Hampel\XenForo\Api\Client directly:

Returning an entity

Entities implement \JsonSerializable and serialise to the forum's own payload, so handing one to a JSON response gives you what the API answered rather than the entity's internals:

Fields the credential is not allowed to see are absent from that payload rather than null, which is the distinction XenForo itself draws — a permission failure and a genuinely empty field are not the same thing, and ApiResponse::has() is how to tell them apart. Add-on fields the specification does not describe survive too.

Errors

The core package's exceptions arrive untouched. Telling them apart is the reason to use it rather than Http:: directly — a client that reports every unsuccessful status the same way cannot tell a rejected credential from a user who is not a member:

Testing

Fake the forum with the vocabulary the rest of your suite already uses:

The package's real code path runs; only the socket is replaced. So a faked 404 still arrives as NotFoundException, and a faked 200 whose body is not JSON still arrives as MalformedResponseException.

Three things worth knowing:

• Http::fake() with no arguments gives every request an empty 200, which the core package treats as a malformed response rather than an empty result — a 2xx that does not decode is a maintenance page, a WAF challenge or a truncated body, and reading it as "no such record" is the failure the package exists to prevent. Always give a body.
• Order does not matter. Faking after the client has been resolved works, and so does Http::swap() with a new factory, because the transport resolves Laravel's HTTP factory at the moment of sending rather than when it was built.
• Request bodies are assertable — $request['username'] works, because the core package writes form-encoded bodies with an exact Content-Type.

Replace the transport entirely by rebinding xenforo.http_client to any PSR-18 client. That is how an application with its own outbound HTTP policy, such as a proxy-aware or SSRF-guarded client that everything must go through, makes this package use it:

The binding can go in any service provider. This package only binds the key if nothing has yet, so the override holds whether its provider registers before or after this one, including in Laravel Zero, where the order is the providers list.

Proxy and CA settings don't need a replacement: set them with Http::globalOptions(), which reaches this package's requests and keeps them visible to Http::fake().

Binding Psr\Http\Client\ClientInterface does not affect this package. That key is shared by every package that binds it, so with two of them installed the last one registered would serve both. The package neither binds that key nor falls back to it. An application that wants all of its API traffic through its own client rebinds each package's own key.

What is not visible

Laravel raises ResponseReceived and ConnectionFailed from a layer above the handler stack, and this package sends through the stack directly, so neither fires — anything listening for them, including Telescope's HTTP client watcher, will not show this traffic. The core package logs every request through PSR-3 instead, which reaches the application log.

RequestSending does fire, because Laravel raises it from inside the stack. A listener that pairs it with either of the other two will see requests announced and never concluded.

Http::assertSent() cannot inspect uploaded files either: Illuminate\Http\Client\Request::hasFile() reads data the framework records when it builds a multipart body itself. Assert on the request's Content-Type and body instead.

What this package will not do

Grow retries or backoff. TooManyRequestsException is typed so an application can retry; which requests are safe to retry is the application's knowledge, not this package's.

License

MIT. See LICENSE.md.