PHPackages                             xapps-platform/xapps-backend-kit - 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. [Framework](/categories/framework)
4. /
5. xapps-platform/xapps-backend-kit

ActiveLibrary[Framework](/categories/framework)

xapps-platform/xapps-backend-kit
================================

Modular PHP backend kit for the current Xapps backend contract (tenant surface today, shared actor-adapter direction later)

0.2.13(2mo ago)0149MITPHPPHP ^8.2

Since Mar 24Pushed 2mo agoCompare

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

READMEChangelog (10)Dependencies (2)Versions (20)Used By (0)

xapps-platform/xapps-backend-kit
================================

[](#xapps-platformxapps-backend-kit)

Modular PHP backend kit for the current Xapps backend contract.

Install
-------

[](#install)

```
composer require xapps-platform/xapps-backend-kit
```

This package depends on `xapps-platform/xapps-php` and sits above it.

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

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

Use it when you want a higher-level packaged backend contract with default routes, mode assembly, payment runtime composition, and override seams.

Use `xapps-platform/xapps-php` directly only when you need lower-level PHP primitives that the backend kit intentionally does not own.

Current public surface:

- backend composition for the shipped backend contract

Direction:

- PHP and Node variants should converge on the same backend contract
- actor differences should live in adapters, rights/scope, config, and data access
- not in duplicated platform backend logic

This package sits above:

- `xapps-platform/xapps-php`

Use it when you want a working backend with default routes, default modes, and override seams, while keeping the later shared tenant/publisher direction open.

For request-capable publisher-rendered widgets, use the package layer to verify browser widget context server-side before exposing private runtime behavior:

```
$originPolicy = BackendKit::evaluateWidgetBootstrapOriginPolicy([
    'hostOrigin' => $request['body']['hostOrigin'] ?? null,
    'allowedOrigins' => $config['widgetBootstrap']['allowedOrigins'] ?? [],
]);

if (!($originPolicy['ok'] ?? false)) {
    http_response_code(($originPolicy['code'] ?? '') === 'HOST_ORIGIN_REQUIRED' ? 400 : 403);
    echo json_encode([
        'ok' => false,
        'error' => [
            'code' => $originPolicy['code'] ?? 'HOST_ORIGIN_NOT_ALLOWED',
            'message' => $originPolicy['message'] ?? 'Widget bootstrap origin rejected',
        ],
    ]);
    return;
}

$verified = BackendKit::verifyBrowserWidgetContext($gatewayClient, [
    'hostOrigin' => $originPolicy['hostOrigin'],
    'installationId' => 'inst_123',
    'bindToolName' => 'submit_form',
    'subjectId' => 'sub_123',
    'bootstrapTicket' => $request['body']['bootstrapTicket'] ?? null,
]);
```

Recommended shared local config contract for publisher-rendered bootstrap routes:

- `widgetBootstrap.allowedOrigins`
- optional app env:
    - `XAPPS_WIDGET_ALLOWED_ORIGINS=https://host.example.test,https://host-b.example.test`

This stays local/app-owned on purpose. The package helper standardizes the policy behavior without forcing a framework-specific env contract.

Recommended request-widget posture:

- keep the widget asset URL as a public/bootstrap shell
- keep request-capable UI blocked until backend verification succeeds
- do not place secrets or durable bearer tokens in manifest widget URLs
- direct raw browser hits should stay blocked instead of exposing private runtime

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 your backend as `bootstrapTicket`
- the PHP backend-kit passthrough accepts that field without changing the current default/public bootstrap contract

This is now a real package, not a placeholder or extraction stub. Keep the public entry surface stable and split internal package code behind it.

Start Here
----------

[](#start-here)

Consumer rule:

- prefer Composer autoload plus the package file autoload
- use the package entry surface
- do not wire individual `src/...` files directly in consuming apps

Example:

```
require_once __DIR__ . "/vendor/autoload.php";

use Xapps\BackendKit\BackendKit;
```

Packaged consumers should prefer Composer autoload plus the package file autoload. Repo-local consumers can keep loading `src/functions.php` directly.

What It Gives You
-----------------

[](#what-it-gives-you)

The current package surface provides:

- backend-kit option normalization
- backend-kit composition
- default route surface
- default mode tree
- payment runtime assembly
- higher-level XMS purchase workflow helpers
- host-proxy service assembly
- request-widget bootstrap verification passthrough
- subject-profile sourcing hooks

Internal package structure is intentionally modular:

- `src/BackendKit.php`thin public facade
- `src/Backend/Support.php`small shared value helpers
- `src/Backend/Options.php`option normalization and config shaping
- `src/Backend/Runtime.php`plain-PHP request/bootstrap helpers
- `src/Backend/PaymentRuntime.php`payment runtime assembly and payment-page API helpers
- `src/Backend/Xms.php`higher-level XMS purchase workflow helpers on top of the PHP gateway client
- `src/Backend/HostProxy.php`host-proxy service and plain-app creation
- `src/Backend/Modules.php`backend module composition
- `src/Backend/Modes/*`explicit default mode tree
- `src/Backend/Routes/*`explicit default route tree

Current route surface includes:

- health
- reference
- host core
- lifecycle
- current-user host monetization lifecycle under `/api/my-xapps/:xappId/...`
    - includes `/api/my-xapps/:xappId/monetization/history` for recent current-user XMS audit buckets
- bridge
- payment
- guard
- subject profiles

Current workflow helpers also include:

- `BackendKit::normalizeXappMonetizationScopeKind(...)`normalizes subject / installation / realm scope selection
- `BackendKit::resolveXappMonetizationScope(...)`resolves scope fields from runtime context plus optional realm reference
- `BackendKit::resolveXappHostedPaymentDefinition(...)`resolves a manifest payment definition into hosted session config, including delegated signing metadata
- `BackendKit::listXappHostedPaymentPresets(...)`shapes manifest payment definitions into generic hosted-lane preset options for UI selectors
- `BackendKit::findXappHostedPaymentPreset(...)`looks up one hosted-lane preset by `paymentGuardRef`
- `BackendKit::readXappMonetizationSnapshot(...)`reads the common app-facing XMS state bundle: access, current subscription, entitlements, and wallet accounts
- `BackendKit::buildXappMonetizationReferenceSummary(...)`interprets the current-user XMS snapshot plus projected paywall packages into:
    - primary recurring membership
    - owned additive unlocks
    - available additive unlocks
    - recurring options
    - credit top-ups
    - blocked packages
- host-mounted plans surfaces can now also consume the recent current-user history bundle exposed through:
    - `/api/my-xapps/:xappId/monetization/history`
    - portal `/v1/me/xapps/:xappId/monetization/history`
    - embed `/embed/my-xapps/:xappId/monetization/history`
- `BackendKit::consumeXappWalletCredits(...)`consumes credits from one wallet account through the XMS API and returns the updated wallet, ledger entry, and refreshed access projection
- `BackendKit::startXappHostedPurchase(...)`prepares a purchase intent and creates the lane-bootstrapped gateway payment session
- `BackendKit::finalizeXappHostedPurchase(...)`finalizes a hosted purchase through the platform finalize endpoint, returning reconciliation and issued access state
- `BackendKit::activateXappPurchaseReference(...)`prepares a purchase intent, creates a verified reference transaction, and issues access

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

[](#verify-locally)

```
php packages/xapps-backend-kit-php/test/run.php
php packages/xapps-backend-kit-php/examples/smoke/smoke.php
```

Minimal usage
-------------

[](#minimal-usage)

```