Download the PHP package ghayma/sdk without Composer

ghayma/sdk

PHP client for the Ghayma platform. Two entry classes over the two published contracts:

• Ghayma — the admin client, authenticated with a project API key (gsk_…). Sub-clients ->auth, ->storage, ->databases. Server-side only.
• GhaymaAuth — the stateless end-user auth client for one app, keyed by an app slug and an optional server key (ghs_…). Registers, signs in and manages an app's end users.

Requires PHP 8.2+.

Install

The SDK talks HTTP through the PSR-18 / PSR-17 interfaces and never hard-depends on a client. It discovers any installed implementation via php-http/discovery. If your app doesn't already ship one, add Guzzle and nyholm:

You can also pass your own client and factories explicitly (see Bring your own HTTP client).

Admin client (Ghayma)

Authenticate with a project API key from Project → Settings → API keys.

->auth, ->storage and ->databases return typed, immutable DTOs (Ghayma\Sdk\Model\*). See examples/admin.php.

Credentials: your site's own

->databases->credentials() and ->storage->credentials() answer a site's key (the GHAYMA_API_KEY in the site's variables) with that site's own connection credential, the one its runtime already carries in DATABASE_URL / MONGODB_URI or STORAGE_*, at the connection's level (read-only/connect for a database, read/read-write for a bucket); credential is always connection. A database's own login and a bucket's owner key are never handed out.

From your laptop, reach a database with ghayma connect --local, and a bucket with ghayma env pull (your site's STORAGE_* variables; the S3 endpoint is public). A system outside Ghayma gets a credential of its own: ghayma access add database <name> --name <principal> (or bucket).

End-user auth client (GhaymaAuth)

GhaymaAuth holds no session state — a PHP request is stateless, so the caller passes the accessToken (or refreshToken) it stored. There is no token storage, no auto-refresh timer.

login() returns a LoginResult (LoginSuccess | TwoFaRequired | TwoFaEnrollmentRequired); register() returns a RegisterResult (RegisterSuccess | VerificationRequired). Match with instanceof. See examples/auth.php.

Server key and client IP

When you construct GhaymaAuth with a server key, pass the real end-user IP so the auth service applies its rate limits to that user rather than to your server. The key and the IP travel together or not at all (a forwarded IP is only honoured from a caller that proves itself with the key), and the IP is validated as a literal before it is sent:

On Ghayma, the visitor's IP is in X-Real-IP, which the platform's edge overwrites; if your server is also reachable another way (another host, your own proxy), make sure that path overwrites it too, or don't forward it.

clientIp is accepted on the rate-limited entry points: register, login, verify2fa, refresh, forgotPassword, resetPassword, verifyResetToken, resendVerification, exchangeCode, signInWithIdToken. Never expose the server key to a browser — build GhaymaAuth in server code only.

OAuth

Build a provider sign-in URL for a login page, then redirect the browser to it:

Complete a native or PKCE sign-in server-side:

The redirect_uri must match one of the app's Allowed Origins, and native client IDs must be registered under Native client IDs, both in the console. See the mobile OAuth guide: https://docs.ghayma.cloud/guides/oauth-mobile.

signInWithIdToken() refuses a Google account whose email address Google has not verified: a 403 ForbiddenException with errorCode email_not_verified, through the usual error mapping.

Second factor on OAuth sign-in

When the app's 2FA policy applies to the user, exchangeCode() and signInWithIdToken() create no session and throw a TwoFactorRequiredException. Its result is the same pending step login() returns, finished the same way:

$e->errorCode is two_fa_required or two_fa_enrollment_required, and $e->status is 200. The exception extends GhaymaException, so a broad catch (GhaymaException $e) still stops the sign-in; catch TwoFactorRequiredException first to offer the second factor.

Errors

Every failure is a Ghayma\Sdk\Exception\GhaymaException carrying status, errorCode and (on a 429) retryAfter. Catch the base type broadly, or a subclass to branch:

Bring your own HTTP client

The constructors accept an optional PSR-18 client and PSR-17 request/stream factories; when omitted, they are discovered:

Laravel

No facade or companion package is required — bind the clients in a service provider:

Then type-hint Ghayma or GhaymaAuth anywhere the container resolves. Laravel's Guzzle satisfies the PSR-18/17 discovery. Forward the visitor's IP with $request->header('X-Real-IP').

Contracts and conformance

Every wire shape comes from the two vendored OpenAPI contracts in Prism mock of each and runs the SDK against them; tool/sync-spec.sh refreshes the vendored copies from the served documents.

License

MIT © Throct