Download the PHP package querri/embed without Composer

querri/embed — PHP SDK

Embed Querri analytics in your PHP application. One method call, zero config.

Laravel | Symfony | Plain PHP | WordPress

PHP SDK for creating embed sessions, managing users, and controlling access policies via the Querri API. Use it with any PHP framework alongside the @querri-inc/embed frontend component. One getSession() call, one server endpoint, and you're done.

Get Started in 60 Seconds

1. Install

2. Create a session

3. Add the embed (React)

4. Wire the endpoint

Set QUERRI_API_KEY and QUERRI_ORG_ID environment variables. In production, always derive user identity from your auth system — never from the request body.

5. Done.

The embed handles auth, token caching, and cleanup automatically.

Security: Always derive user identity and access from your server-side auth system. Never read user or access from the request body — a malicious client can impersonate any user or escalate access.

Configuration

The SDK reads configuration from constructor arguments or environment variables:

getSession() — Embed Sessions

The flagship method that creates an embed session in three steps:

1. User resolution — creates or retrieves a Querri user by your external ID
2. Access policy — auto-creates or reuses a deterministic policy with row-level filters
3. Session creation — generates an opaque es_… session token for the embed iframe

With inline access rules

With pre-created policy IDs

Running the session as a custom role

Pass role (a role id or key, at most 100 characters) to run the embed session as one of your organization's custom roles:

roleId is null when no role was applied — and also when an older server ignored role, in which case the session runs as the user's own role. Check it whenever the role matters.

• A role the user already holds is simply selected.
• A role they don't hold is granted only when the API key has the embed:role:assign scope and the role is on the organization's embed allow-list (Settings → Embed), and the people behind the key hold every permission in it (servers released after 2026-10-21: both the key's creator and its bound user, if any; earlier servers: its bound user, else its creator). Otherwise the call throws PermissionException with errorCode insufficient_scope or role_not_allowed.
• A grant is permanent. It adds the role to the user's assignment, so later sessions and the Querri app see it too; revoking the session doesn't remove it. An admin removes it in Settings → People.
• An unknown role throws NotFoundException (role_not_found); a draft role role_disabled; a role that needs a creator seat seat_change_required.
• role is not user.role. user.role is the org role (admin/member) used only when the user is first created; role is the Custom Role the session runs as.
• Decide role on your server from your own auth. Never read it from the page's request — anyone can edit that.
• getSession() creates or updates the user and applies access policies before it requests the session, so if the role is refused those steps have still happened.
• Creating a new user can itself be refused: PermissionException with escalation_denied when the user's org role would carry permissions the people behind the key don't hold (the refused keys are only in the raw body, $e->body['detail']['error']['missing']).
• An empty string is treated like no role.

GetSessionResult

Direct Resource Usage

For advanced use cases, access the API resources directly:

Users

Policies

Embed Sessions

Servers released after 2026-10-21 also return role_id from refresh and list; earlier servers return it only from create.

All Resources

Beyond the core embed resources above, the SDK provides full access to the Querri API:

See docs/server-sdk.md for complete method signatures and examples.

Error Handling

All errors extend QuerriException. API errors are mapped to specific exception types:

Every ApiException exposes status, errorCode (compare with the ErrorCode constants), type, docUrl, requestId (from the X-Request-Id header), the raw body and headers, and — on a role-system denial (permission_denied) — permission (the permission key, also sent as the X-Permission-Denied header) and reason (role_denied, not_in_plan, flag_off, embed_disabled, dependency_unmet, scope_exceeds_role or forbidden; the server may add more). See the error code table for the codes for authentication, access, Custom Roles and embed sessions; the API sends other codes too, so keep a default branch.

The SDK automatically retries 429 (always) and 5xx (idempotent methods only) with exponential backoff + jitter, up to max_retries attempts.

Example App

See examples/react-embed/ for a complete working example with a PHP backend and React frontend.

Full Reference

See docs/server-sdk.md for the complete API reference, including every method signature, framework integration guides (Laravel, Symfony), error handling details, and the getSession() deep dive.

Troubleshooting

"API key is required" / "Organization ID is required" errors

Set the QUERRI_API_KEY and QUERRI_ORG_ID environment variables (both are required since 1.0.0). An org admin creates API keys at app.querri.com/settings/api.

The SDK checks getenv(), $_ENV, and $_SERVER — covering CLI, Apache, nginx+FPM, and Docker.

Embed is blank / session endpoint returns 500

Verify your PHP endpoint returns JSON with the correct Content-Type:

CORS errors in development

Use Vite's dev proxy to forward /api requests to your PHP server — no CORS headers needed:

Class not found errors

Ensure Composer's autoloader is loaded before using SDK classes:

Important Notes

• This SDK uses the Server Token auth mode. Your PHP backend creates session tokens and the frontend embed consumes them. For other auth modes (Share Key, Popup Login), see the JS SDK docs.
• Pair this release with @querri-inc/embed ^1.0.0 on the frontend.
• The session token is an opaque es_… string, not a JWT — don't try to decode or verify it client-side; pass it through as-is.
• React/Vue/Angular: Memoize the auth prop if it's an object. A new object reference on every render cycle causes the iframe to be destroyed and recreated.
• The PHP SDK covers the full Querri API (all 13 resources). For frontend-only use cases, see the JS SDK.

Requirements

• PHP 8.3+
• ext-json
• ext-hash
• symfony/http-client ^7.2

License

MIT

Support policy

Versions below 1.0.0 receive security fixes only, for 6 months from the 1.0.0 release (2026-08-31). Their data-surface methods call routes the server has removed; migrate with docs/MIGRATION.md.