PHPackages                             xapps-platform/xapps-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. xapps-platform/xapps-php

ActiveLibrary[API Development](/categories/api)

xapps-platform/xapps-php
========================

PHP SDK for Xapps publisher/tenant backend integrations

0.2.11(2mo ago)01701MITPHPPHP ^8.2

Since Mar 24Pushed 2mo agoCompare

[ Source](https://github.com/0x730/xapps-php)[ Packagist](https://packagist.org/packages/xapps-platform/xapps-php)[ Docs](https://gateway.0x730.com)[ RSS](/packages/xapps-platform-xapps-php/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (10)DependenciesVersions (18)Used By (1)

xapps-platform/xapps-php
========================

[](#xapps-platformxapps-php)

PHP backend SDK for tenant, publisher, and host-proxy integrations.

Install
-------

[](#install)

```
composer require xapps-platform/xapps-php
```

Fast Start For Hosted Integrators
---------------------------------

[](#fast-start-for-hosted-integrators)

If your browser already uses `@xapps-platform/browser-host`, the minimum PHP or Laravel backend job is one local route:

- `POST /api/browser/host-bootstrap`

That local browser-safe route forwards identity input to the remote tenant backend and returns resolved `subjectId` + short-lived `bootstrapToken`.

Start here:

- [packages/xapps-php/examples/host-proxy/hosted-integrator-bootstrap.php](/home/dacrise/x/xapps/packages/xapps-php/examples/host-proxy/hosted-integrator-bootstrap.php)
- [apps/tenants/docs/tooling/first-hosted-tenant-integrator-handoff.md](/home/dacrise/x/xapps/apps/tenants/docs/tooling/first-hosted-tenant-integrator-handoff.md)

Use `xapps-platform/xapps-php` for lower-level PHP primitives for gateway, callback, payment-return, publisher-admin, or host-proxy flows.

If you want a higher-level packaged backend contract with default routes and mode assembly, use `xapps-platform/xapps-backend-kit` instead.

For the current XMS system behavior and API reader path, read:

- [docs/specifications/xms/README.md](/home/dacrise/x/xapps/docs/specifications/xms/README.md)

Browser + Backend SDK Split
---------------------------

[](#browser--backend-sdk-split)

For the full embed contract:

- browser SDK: `@xapps-platform/browser-host`
- low-level browser engine: `@xapps-platform/embed-sdk`
- PHP backend SDK: `xapps-platform/xapps-php`

Use this package when the browser already runs `@xapps-platform/browser-host`or `@xapps-platform/embed-sdk` and the backend needs to proxy the host/session contract to the gateway or tenant backend.

Scope
-----

[](#scope)

- Dispatch payload parsing (`Xapps\\Dispatch::parseRequest`)
- Request signature verification (`Xapps\\Signature::verifyXappsSignature`)
- Callback client for `/v1/requests/:id/events|complete` (`Xapps\\CallbackClient`)
- Payment-return parse/sign/verify helpers (`Xapps\\PaymentReturn`)
- Provider credential bundle helpers (`Xapps\\PaymentProviderCredentials`)
- Managed gateway session shaping helpers (`Xapps\\ManagedGatewayPaymentSession`)
- Hosted gateway payment bootstrap helper (`Xapps\\HostedGatewayPaymentSession`)
- Payment policy support helpers (`Xapps\\PaymentPolicySupport`)
- Gateway client for host backends (API key and/or bearer token), including payment-session helpers, low-level XMS monetization lifecycle helpers (catalog, access, subscription, wallet, purchase-intent, and subscription-contract routes), and request-widget bootstrap verification (`Xapps\\GatewayClient`)
- Publisher admin API client for publisher backends (`Xapps\\PublisherApiClient`), including `listClients()`, publisher linking helpers, and bridge-token exchange parity with `@xapps-platform/server-sdk`
- Typed SDK exceptions (`Xapps\\XappsSdkError`) for callback/gateway networking + argument validation
- Unified subject-proof verifier surface (`Xapps\\SubjectProof`) via injected verifier adapters

Current `GatewayClient` XMS helpers include:

- `getXappMonetizationCatalog(...)`
- `getXappMonetizationAccess(...)`
- `getXappCurrentSubscription(...)`
- `listXappEntitlements(...)`
- `listXappWalletAccounts(...)`
- `listXappWalletLedger(...)`
- `consumeXappWalletCredits(...)`
- purchase-intent / transaction / payment-session lifecycle helpers
- subscription-contract reconcile / cancel / refresh helpers
- current-user embed monetization lane:
    - `getEmbedMyXappMonetization(...)`
    - `getEmbedMyXappMonetizationHistory(...)`
    - `prepareEmbedMyXappPurchaseIntent(...)`
    - `createEmbedMyXappPurchasePaymentSession(...)`
    - `finalizeEmbedMyXappPurchasePaymentSession(...)`

Current XMS targeting-aware catalog helpers support:

- `getXappMonetizationCatalog($xappIdOrInput)` where the input may include:
    - `xappId`
    - `subjectId`
    - `installationId`
    - `realmRef`
    - `locale`
    - `country`
- `prepareXappPurchaseIntent(...)` with optional `locale` and `country`

Current enforced gateway policy on that lane:

- offering/paywall `targeting_rules`
- price `country_rules`
- price `trial_policy`
- price `intro_policy`

Current enforced subset:

- locale include/exclude
- country include/exclude
- scope requirements:
    - `require_subject`
    - `require_installation`
    - `require_realm`
- first-time-only free trials for `subscription_plan` / `hybrid_plan`
- first-time-only intro discounts for `subscription_plan` / `hybrid_plan`
- `trial_policy` wins over `intro_policy` when both qualify
- zero-cost qualified lanes can finalize without an external payment session

Current canonical `XMS` lifecycle event family exposed through the existing hook system:

- `xapps.xms.purchase_intent.prepared`
- `xapps.xms.transaction.reconciled`
- `xapps.xms.access.issued`
- `xapps.xms.access_snapshot.refreshed`

Xapps can subscribe through manifest `event_subscriptions`, and publisher-wide integrations can subscribe through Publisher `Events & Webhooks` on the same delivery rail.

Local path install during monorepo development
----------------------------------------------

[](#local-path-install-during-monorepo-development)

```
{
  "repositories": [
    {
      "type": "path",
      "url": "../../../../packages/xapps-php",
      "options": { "symlink": true }
    }
  ],
  "require": {
    "xapps-platform/xapps-php": "*@dev"
  }
}
```

Then:

```
composer update xapps-platform/xapps-php
```

Supported distribution modes
----------------------------

[](#supported-distribution-modes)

Current supported ways to consume `xapps-platform/xapps-php`:

1. Local/path package during monorepo development
2. Packagist-facing split package mirror and/or VCS package from the public package mirror, pinned to an approved tag for integrator environments

Current release model:

- `0x730/xapps-sdk-php` is the public PHP source/control-plane repo
- package distribution is intended to happen through split package mirrors:
    - `0x730/xapps-php`
    - `0x730/xapps-backend-kit-php`
- Packagist should point to those split package mirrors, not the raw multi-package source repo

Example VCS package install:

```
{
  "repositories": [
    {
      "type": "vcs",
      "url": ""
    }
  ],
  "require": {
    "xapps-platform/xapps-php": "dev-xpo#"
  }
}
```

Practical rule for integrators:

- pin to an approved tag or commit, not a floating branch
- treat monorepo tags/commits as the source of truth for release provenance
- run `composer test` or `php packages/xapps-php/test/run.php` against the pinned version during integration sign-off

Verify locally
--------------

[](#verify-locally)

Smoke check:

```
php packages/xapps-php/examples/smoke/smoke.php
```

Direct local package verification:

```
php packages/xapps-php/test/run.php
```

Or via Composer inside `packages/xapps-php`:

```
composer test
composer smoke
```

Payment-return parity regression (golden vector vs Node SDK contract):

```
php packages/xapps-php/examples/payment-return/parity.php
```

Managed gateway session examples:

```
php packages/xapps-php/examples/managed-gateway-session/tenant.php
php packages/xapps-php/examples/managed-gateway-session/publisher.php
```

Minimal host proxy example:

```
php packages/xapps-php/examples/host-proxy/minimal.php
```

Host plans / current-user monetization example:

```
php packages/xapps-php/examples/host-proxy/plans.php
```

Current `EmbedHostProxyService` host-plan helpers include:

- `getMyXappMonetization(...)`
- `getMyXappMonetizationHistory(...)`
- `prepareMyXappPurchaseIntent(...)`
- `createMyXappPurchasePaymentSession(...)`
- `finalizeMyXappPurchasePaymentSession(...)`
- `runWidgetToolRequest(...)`

Request-widget bootstrap verification helper:

```
$verified = $gateway->verifyBrowserWidgetContext([
    'hostOrigin' => 'https://tenant.example.test',
    'installationId' => 'inst_123',
    'bindToolName' => 'submit_form',
    'subjectId' => 'sub_123',
    'bootstrapTicket' => 'bst_123',
]);
```

Recommended request-widget posture:

- keep the publisher widget asset URL as a public/bootstrap shell
- block request-capable runtime until the short-lived widget token and context are verified server-side
- do not put secrets or durable tokens in the manifest URL
- direct raw browser hits should stay blocked instead of unlocking private request/runtime behavior

Optional stronger bootstrap transport already supported:

- `widgets[].config.xapps.bootstrap_transport = "signed_ticket"`
- current first slice reuses the short-lived signed widget token as a bootstrap ticket and carries it in the iframe URL hash
- browser widget code can forward it to the backend as `bootstrapTicket`
- `GatewayClient::verifyBrowserWidgetContext(...)` accepts both:
    - `bootstrapTicket`
    - `bootstrap_ticket`

Publisher linking + bridge helpers:

```
$publisher = new PublisherApiClient('http://localhost:3000', 'publisher-api-key');
$publisher->completeLink([
    'subjectId' => 'sub_123',
    'xappId' => 'xapp_123',
    'publisherUserId' => 'publisher-user-123',
    'metadata' => ['email' => 'user@example.test'],
]);

$status = $publisher->getLinkStatus();
$bridge = $publisher->exchangeBridgeToken([
    'publisher_id' => 'pub_123',
    'scopes' => ['publisher.api:read'],
]);
```

Higher-level tenant/publisher backend kits are intentionally not part of the current supported PHP SDK surface. The next redesign for that layer will start from backend `lib/` and `modes/`, not from route-wrapper aliases.

XPO-Core fixture conformance check (`P1`-`P5`, `N1`-`N7` payment-return vectors):

```
php packages/xapps-php/examples/payment-return/xpo-core-fixtures.php
```

Note: replay fixture handling (`N3`) is evaluated at the runner layer to model gateway/runtime replay protection semantics above pure signature verification.

Live local smoke (gateway + optional callback roundtrip):

```
XAPPS_SMOKE_BASE_URL=http://localhost:3000 \
XAPPS_SMOKE_API_KEY=xapps_test_tenant_b_key_123456789 \
php packages/xapps-php/examples/smoke/live.php
```

Optional callback leg:

```
XAPPS_SMOKE_BASE_URL=http://localhost:3000 \
XAPPS_SMOKE_API_KEY=xapps_test_tenant_b_key_123456789 \
XAPPS_SMOKE_CALLBACK_TOKEN='' \
XAPPS_SMOKE_REQUEST_ID='' \
php packages/xapps-php/examples/smoke/live.php
```

Minimal event-delivery verification example:

```
$result = Signature::verifyXappsSignature([
    'method' => $_SERVER['REQUEST_METHOD'] ?? 'POST',
    'pathWithQuery' => $_SERVER['REQUEST_URI'] ?? '/webhooks/events',
    'body' => $rawBody,
    'timestamp' => $_SERVER['HTTP_X_XAPPS_TS'] ?? '',
    'signature' => $_SERVER['HTTP_X_XAPPS_SIGNATURE'] ?? '',
    'nonce' => $_SERVER['HTTP_X_XAPPS_NONCE'] ?? '',
    'source' => 'event_delivery',
    'requireSourceInSignature' => true,
    'allowLegacyWithoutSource' => true,
    'secret' => getenv('XAPPS_ENDPOINT_SECRET') ?: '',
]);

if (!($result['ok'] ?? false)) {
    throw new RuntimeException('Invalid event delivery signature');
}
```

Usage
-----

[](#usage)

```