Download the PHP package webrek/supabase-php without Composer

supabase-php

Framework-agnostic PHP client for Supabase. PHP 8.3+.

Status

Status: Stable (1.1). Available: Auth (user flows, admin, PKCE / ID-token sign-in, local JWT verification via JWKS), per-request user context for Row Level Security, Edge Functions, Database (PostgREST), Storage, Realtime (postgres changes, broadcast & presence, private channels, HTTP broadcast, opt-in auto-reconnect). Tested on PHP 8.3–8.5 and end-to-end against a real Supabase stack in CI.

Installation

You also need any PSR-18 HTTP client and PSR-17 factories. If you do not already have one, install Guzzle and Nyholm PSR-7:

The client auto-discovers them via php-http/discovery. You can also inject your own via ClientOptions.

For production deployments, install without dev dependencies and with an optimized, authoritative classmap:

Quick start

Edge Functions

Database (PostgREST)

The Database module supports the full set of PostgREST filtering operators — eq, neq, gt, gte, lt, lte, like, ilike, is, in, contains, containedBy, rangeGt, rangeGte, rangeLt, rangeLte, rangeAdjacent, overlaps, textSearch, not, or, match, and filter (escape hatch) — plus modifiers (order, limit, range, single, maybeSingle), count(), and error handling via PostgrestException.

Storage

upload() accepts a string or a PSR-7 StreamInterface. Storage uses the key the client was built with (anon respects Storage RLS policies; service_role bypasses them). download() caps at 50 MiB by default — raise the maxBytes argument or use a signed URL for larger files.

Realtime

Subscribe to Postgres changes and exchange broadcast messages over a persistent WebSocket connection. Realtime is connection-oriented and meant for long-lived CLI / worker processes, not a typical web request.

Because there is no PSR standard for WebSockets, this library does not bundle a WebSocket client. You provide a connection by implementing Supabase\Realtime\WebSocketConnection (the SDK implements the Phoenix channels protocol on top of it) and wiring a factory through ClientOptions:

Prefer your own loop? Call poll(float $timeout) repeatedly instead of run(), and stop() to break out of run() from inside a callback.

Broadcast from a web request (no WebSocket)

broadcast() posts a message through the Realtime REST endpoint, so an ordinary HTTP request can notify connected clients without holding a socket open — no WebSocketConnectionFactory needed:

Subscribers receive it as a regular broadcast event. The request carries the client's bearer, so withAccessToken($jwt)->realtime()->broadcast(...) is authorised as that user.

Private channels and user tokens

Private channels are authorised by Realtime RLS policies on realtime.messages. Pass private: true and act as a user: the client's access token (see withAccessToken()) is sent with the join automatically.

Presence

Track which clients are online and get notified when they join or leave. Register callbacks with onPresenceSync, onPresenceJoin, and onPresenceLeave before calling subscribe(), then call track() to broadcast your own state:

Auto-reconnect

By default the client does not reconnect after a dropped connection. Pass realtimeAutoReconnect: true to make run() reconnect with exponential backoff and automatically re-subscribe all active channels:

When driving the loop yourself with poll(), reconnection is not automatic. After a receive error, call connect() again and re-subscribe your channels.

Implementing WebSocketConnection

WebSocketConnection is a small contract you back with any WebSocket client. The URL passed to connect() already contains the apikey query parameter, so never log it verbatim.

Calling realtime() without configuring a webSocketFactory throws a Supabase\Exception\RealtimeException.

Ready-made adapter: phrity/websocket

A concrete WebSocketConnection implementation backed by phrity/websocket is included in this package. Install the backing library and use it directly:

PhrityWebSocketConnectionFactory is a drop-in: it creates one PhrityWebSocketConnection per RealtimeClient, handles the WebSocket handshake, adds headers, applies a read timeout on every receive() call, and auto-responds to WebSocket-level ping frames via phrity's PingResponder middleware.

Auth (GoTrue)

Sessions are stateless: the SDK never stores them — persist accessToken/refreshToken yourself. withSession() (below) refreshes one on demand. Tokens are redacted in var_dump/print_r/json_encode and in AuthException bodies, and Session cannot be serialized. (PHP's var_export() cannot be intercepted — never var_export() a Session.)

OAuth on the server (PKCE)

Run the OAuth redirect flow entirely from PHP. Generate a PKCE pair, keep the verifier in your session, send the user to the provider, and trade the code from the callback for a Session:

Sign in with an ID token (Google, Apple, ...)

For native or server-side flows where you already hold an OpenID Connect ID token from the provider:

Acting as a user (Row Level Security)

On the server every request arrives with a different user's JWT. Bind it to a sibling client instead of constructing a new one: the apikey, HTTP client and all options are shared, only the bearer changes, and the original client is untouched.

withSession() refreshes proactively, before the first request, and only when needed; it does not retry a request whose token expired mid-flight. A refresh token that is no longer valid throws AuthException. withAccessToken(null) returns a client that uses the apikey as bearer again.

Verifying a JWT locally (JWKS)

getClaims() checks a token's signature against the project's public keys (/auth/v1/.well-known/jwks.json) plus its exp/nbf, without calling /auth/v1/user. Give it a PSR-16 cache so the key set is fetched once and shared across requests:

ES256 and RS256 keys are verified locally. Projects still on the legacy HS256 shared secret publish no public key: pass jwtSecret in ClientOptions to verify locally, otherwise getClaims() falls back to one /auth/v1/user request. Without a cache the key set is fetched once per process (memoised for jwksCacheTtl); an unknown kid triggers a single refetch so rotated keys are picked up. Requires ext-openssl.

Admin API (service_role)

Construct the client with your service_role key (never expose it to browsers):

Injecting your own HTTP client

Error handling

Operations return data directly and throw typed exceptions on failure:

Security

• HTTPS enforced. The SDK rejects any $url that does not use https, except for http://localhost and http://127.0.0.1 (local Supabase dev). This prevents your API key and tokens from being sent in cleartext.
• Disable HTTP redirects on your PSR-18 client. The SDK sends your apikey in a custom header that is not stripped on cross-origin redirects. The SDK rejects 3xx responses, but a client that follows redirects internally can leak the key before the SDK sees the response. Set allow_redirects: false (Guzzle) or the equivalent for your client.
• Set a request timeout. The SDK does not impose one; without it a stalled endpoint can hang the process indefinitely.
• Do not dump or serialize credential-holding objects. Client, Transport, and ClientOptions hold your API key. var_export() and some crash reporters can expose raw values even though serialize() is blocked and var_dump() is redacted.
• Exception bodies may contain sensitive data. SupabaseException::getResponseBody() returns the raw response body, which may include tokens or PII. Do not log or expose it verbatim.
• Inject a hardened client in production. Auto-discovery picks up whatever PSR-18 client is installed. For production, pass an explicit client with redirects off, timeout set, and TLS verification on via ClientOptions:

For full guidance and vulnerability reporting, see SECURITY.md.

License

MIT