Download the PHP package revenexx/app-sdk without Composer

revenexx App SDK for PHP

Build revenexx Apps in PHP. The SDK gives an App function everything it needs to answer requests on the revenexx platform:

• A typed data client for the App's own records, with the same code running against in-memory fixtures in a test and against the platform's data plane in production.
• A router with one-line CRUD routes, safe error answers and stable error codes.
• The App's settings as the merchant configured them, per market.
• Who is acting behind a request.
• The App's own events, fired by name.

It is the PHP counterpart of the JavaScript SDK @revenexx/app-sdk. The two behave the same way, call for call.

Requirements

• PHP 8.2 or newer, with ext-curl and ext-json
• The revenexx CLI to generate the typed client (Node.js 18+)

Install

How an App is put together

An App declares its data in two files, and the CLI turns them into a typed client:

This writes src/Db.php. It holds one typed repository and one row class per entity, plus Db::entities(), which lists the entities for the SDK. Regenerate it whenever schema.json or manifest.json changes; never edit it by hand.

Quick start: a function

The runtime loads your entrypoint once per process and calls the function it returns for every request.

Answer through $c->json(), not $context->res->json(). The runtime's own json() encodes every list as an object ({"0": …}). The router writes JSON itself for that reason.

The data client

Client reaches the App's records. The generated Db wraps the same calls with typed repositories ($db->markets->list(...)); Client takes an Entity and works with plain arrays.

A guard on a number gives an atomic decrement. Read, compute, write only if nobody wrote in between, and retry when the answer is null:

Two concurrent reservations cannot both spend the same amount. The second one's condition no longer holds, so it gets null, reads again and decides again.

Only the operations the manifest grants are available. Any other call fails with a 403 and the code not_permitted, naming the method.

Queries

Every read takes the same shape: where, select, order, limit, offset.

All entries must hold. An order without a direction sorts ascending ('code' is 'code.asc').

Adapters

The mock fills in column defaults and generated keys. It also refuses a filter on a column the entity does not have, as the platform does. It does not imitate tenant isolation, unique constraints or foreign keys, so try your App against a development tenant once before you ship it.

The router

RouteContext gives a handler the following:

Routing rules:

• Literal path segments match before parameters, so /markets/defaults wins over /markets/{id}.
• An unknown path answers 404; a known path with the wrong method answers 405.
• GET / answers the App's name and its routes, as a health check.

One-line CRUD

Crud::mount mounts the five standard routes for an entity:

Options:

• only mounts a subset, for example ['list', 'get'].
• parent nests the routes under a parent: ['param' => 'marketId', 'column' => 'market_id', 'entity' => $client->entity('markets')] for /markets/{marketId}/locales. Rows are then scoped to the parent in the path; nothing in a body or query string reaches another parent's rows. With entity given, an unknown parent answers 404.
• queryParams names extra query keys your App reads itself.

List filters. A caller filters the list by exact value: ?currency=EUR. limit, offset and order page and sort it. Anything the list cannot apply is refused with a 400, never silently ignored:

The trash in one call

An entity with trash: true in schema.json gets the routes a trash needs from Trash::mount, the same as mountTrash in the JavaScript SDK:

• DELETE /organizations/{id} on a live row puts it into the trash with its live children, as one group (trash_batch), recording deleted_by / deleted_by_id from the acting person. guard reasons refuse it (409 trash_blocked).
• The same DELETE on a trashed row deletes it for good: the group's children first, then the row. blockers reasons refuse it (409 delete_blocked); canDeleteForGood can require its own permission (403 not_permitted).
• POST /organizations/{id}/restore brings back the row and the children of its group (409 parent_in_trash when its parent is in the trash).
• $trash->purge($caller) is the scheduled job. It reads trash_retention_days through the gateway (GET /v1/audit/settings, 90 when unset; REVENEXX_AUDIT_SETTINGS_URL overrides the URL) and deletes for good what is older, through the same blockers. A blocked row stays, with its reason in the result and in purge_blocked_reason ('purgeReasonColumn' => false for none). If the retention cannot be read, the run is skipped.

A check that throws, and a cross-app count the gateway does not answer, block.

Errors

Throw an HttpError to refuse a request. The router answers it with its status, and the caller sees only what is safe to show:

Branch on code, never on the message. A code is stable across versions; a message may be reworded. message and type repeat error and code under the names the revenexx platform client reads.

Anything else a handler throws answers 500 {"error": "internal error", "code": "internal_error"}. Its message goes to the function log and never reaches the caller.

The data client raises HttpErrors itself:

No table, column or constraint name ever appears in an answer. The full diagnosis is on $e->serverDetail and in the function log.

Reading another App's refusal

When your App calls another App and is refused, Refusal::of() reads what it said:

Settings

$c->settings() returns the App's settings for the tenant and market of the request, resolved by the platform: a market value, else the tenant's value, else the default from your settings declaration.

• Reads are cached per tenant, App and market for 60 seconds.
• A settings outage never fails a request: the reader answers with the last values it resolved, or with your defaults.
• Settings declared sensitive are withheld; $c->settingsSnapshot() lists their keys under masked.

Who is acting

$c->actor reads the identity the platform forwarded with the request:

Check trust before enforcing a per-person rule. A contact named by a storefront server is asserted, not proven: authenticated() answers true only for a person the platform verified itself. Today the platform verifies no person itself, so treat every contact as asserted.

The App's own events

An App declares the events it fires itself in its manifest, for facts with no row behind them:

With the generated client, the same call is $db->events()->emit(…). A Client built by hand needs Db::EMIT_FN and Db::declaredEvents() passed to its constructor (see the quick start). An event the manifest does not declare is refused before anything is sent. On the mock adapter nothing is published; $client->events()->emitted() lists what the App fired, so a test can assert it.

Testing an App

Build the same routes on the mock adapter and run requests through $app->handle(), with a small stand-in for the runtime's context:

Keep the route setup in one function that both main.php and your tests call, so the tests run the routes production runs. For Settings, pass a transport callable to answer without a network:

Not included

• Tracing. The JavaScript SDK traces requests with OpenTelemetry; the PHP SDK does not.

Versioning

The SDK follows semantic versioning. The public classes and methods, the answers of the routes it mounts, and the status and code of every refusal are bound: changing any of them needs a new major version. A message may be reworded in a minor version. See CHANGELOG.md.

Working on the SDK itself

A few tests check the SDK against cases it shares with the JavaScript SDK. Those cases are not part of this package, so these tests are skipped here.

This repository is published from the SDK's main repository and is replaced on every release, so pull requests opened here cannot be merged. Report problems to revenexx.

License

MIT — see LICENSE.