Download the PHP package elqora/dgp-sdk without Composer

DGP SDK

DGP SDK is a framework-neutral protocol and core toolkit for digital-service handlers. A handler exposes services that a host can initialize, charge, start, fulfill, update, act on in bulk, and manage through stable contracts.

The package is intentionally framework-neutral. It defines protocol shapes, DTOs, contracts, enums, validators, hydrators, and deterministic helper APIs. It does not prescribe a database, ORM, queue, transaction model, routing layer, or rendering layer.

Installation

Optional shadcn/ui Registry

This repository also contains a custom shadcn/ui registry with optional React and Tailwind components for presenting DGP runtime state. It includes client-facing plan and delivery views, admin/operator views, status badges, action controls, segmented progress, and shared TypeScript DTO types.

The registry is a host-rendering convenience layer, not part of the Composer package or the framework-neutral PHP runtime. Hosts remain responsible for choosing, installing, adapting, and rendering these components.

• registry.json declares the dgp-sdk registry item and its dependencies.
• registry/dgp-sdk contains the registry source files.
• playground provides the local interactive preview.

The dgp-sdk registry item currently installs:

• Shared components: StatusBadge, ActionButtonGroup, and SegmentBar.
• Client components: ClientDeliveryCard, ClientPlanCard, and ClientPlanViewer.
• Admin components: AdminDeliveryCard, AdminPlanViewer, and AdminManagementViewer.
• Types: shared TypeScript DTOs for manifests, services, runtime plans, deliveries, progress, actions, charges, management, insights, audits, assets, balance, and health.

The source tree also contains ChargeIndicator, OrderChargeStateViewer, ClientChargeCard, and AdminChargeCard. These charge components are exported by the source barrel but are not currently declared as files in registry.json, so they are not yet part of the installable registry item.

To run the registry playground locally:

Validate or build the frontend assets with:

The repository does not currently publish a stable hosted registry endpoint. Consumers should use the registry source directly until an installation URL is documented.

Responsibility Split

The SDK defines:

• Contracts
• DTOs
• Enums
• Endpoint path helpers
• Validators
• Hydrators
• Protocol shapes

The host implements:

• Persistence
• Routing
• Storage
• Payment records
• Broadcasting
• Rendering

The handler implements:

• Service catalog
• Balance reporting
• Initialization
• Start
• Synchronization
• Cancellation
• Actions
• Charges
• Management

Ecosystem

• DGP Spec owns canonical wire contracts.
• DGP Core interprets product definitions.
• DGP Validation validates definitions for ingestion and publication.
• DGP Ordering constructs customer order snapshots.
• DGP Ordering Form Palette provides an optional frontend Form Palette integration.
• DGP Workspace supplies headless editorial session infrastructure.
• DGP Studio provides visual authoring, testing, and publication UX.

Driver Contract

Handlers implement DgpDriverContract, which aggregates the mandatory protocol contracts:

Optional capabilities such as service schema catalogs, webhooks, UI contributions, private assets, and insights are modeled as separate contracts or capability declarations.

Host-Provided Ports

The SDK may define repositories and stores as host-provided ports. The SDK defines the interface; the host provides the implementation.

Examples:

• RuntimeRepositoryContract resolves a handler-scoped runtime port.
• HandlerRuntimeRepositoryContract reads plans, start results, deliveries, and runtime views.
• ServicesRepositoryContract resolves handler-scoped service catalog/state access.
• DeliveriesRepositoryContract exposes persisted delivery lookups.
• DeliveryProgressRepositoryContract records and reads historical delivery progress observations.
• AuditRepositoryContract records and reads meaningful operational and domain evidence.
• InsightsRepositoryContract exposes insight snapshot updates.

Handlers return normalized runtime state. The host persists plans, start results, and deliveries automatically, then exposes persisted state through host-provided ports. The SDK still owns no storage backend. A host can implement ports with SQL, files, queues, remote APIs, memory, or any other storage model.

Configuration

DGP uses elqora/config-kit for structured configuration. Handlers can declare config fields, validate inputs, expose safe public config, and redact sensitive values.

Order Snapshots

OrderSnapshot is the semantic description of what the customer ordered. Host identity such as orderId and execution context such as RuntimeContext are useful runtime metadata, but the snapshot remains the resolved order description. Hydration validates the complete nested DGP v1 wire shape, JSON compatibility, finite numeric values, quantity-source discriminators, and utility evidence before constructing the DTO. String and integer service identities are preserved losslessly, including numeric-looking string IDs.

Runtime Lifecycle

Initialization receives the host order identity, the resolved snapshot, and optional runtime context. The returned Plan describes the execution structure, deliveries, next actions, and is initialized with a PlanStatus (e.g. draft, active, completed, failed, cancelled, abandoned).

After initialization, the host persists the plan and its initialization deliveries. Preparation receives that persisted, hydrated Plan object, including persisted delivery IDs, and can update those same initialization deliveries before fulfillment starts. The passed plan is an input snapshot; handlers may still use host repositories for freshness checks, locks, claims, or retry protection where the host implementation supports them.

Starting fulfillment carries the host order identity plus a reference to the persisted plan. The returned StartResult specifies the initial progress and carrying a StartResultStatus (e.g. pending, running, completed, failed, cancelled, abandoned).

Runtime State Through Host Ports

Hosts can register handler-scoped ports through Dgp. The repository allows looking up plans, start results, and delivery histories, and updating plan/start result statuses.

The SDK defines these interfaces only. Host implementations decide how returned state is stored, indexed, locked, versioned, authorized, and rendered.

Host Endpoints

Dgp::endpointPrefix() sets the host base prefix. Dgp::endpoint() resolves typed built-in endpoint paths, while Dgp::path() remains available for custom extension paths.

Interactions

Handlers guide user or host next steps through elqora/interactions DTOs. Runtime DTOs keep the nextAction property and serialize it as next_action, but the payload is now an interaction.

Supported interaction types come from elqora/interactions:

• Redirect
• Instructions
• QrCode
• Script
• Mount
• Component

Buttons are independent controls exposed on runtime DTOs separately from nextAction.

Use the reserved value action when a button should execute its attached interaction instead of submitting a handler-defined button value.

Inline client behavior is represented as an interaction script.

Runtime DTOs that expose nextAction also expose top-level buttons.

Generic And Bulk Actions

Generic actions represent arbitrary host-defined or handler-defined action values over arbitrary targets. They can be used for delivery actions, charge actions, plan actions, order actions, management actions, custom host actions, and bulk-like custom actions.

Explicit bulk methods model standard bulk operations separately.

Deliveries

Deliveries expose rendering fields directly instead of hiding them in meta: kind, name, isPublic, and note. Progress is represented by DeliveryProgress; scalar progress values are accepted for convenience and hydrated into a progress DTO.

Segmented progress can expose a one-level breakdown while keeping the parent DeliveryProgress authoritative as the aggregate.

Segment buttons are user-selectable commands for addressable progress segments. They do not replace delivery-level interactions; submit them as generic actions with the parent delivery target and the segment target.

Delivery.progress is the current progress state. DeliveryProgressRepository stores and exposes historical progress observations. Progress records may be written asynchronously through record() by handlers, workers, synchronizers, webhooks, actions, host processes, or manual operations. The host implements the repository and owns storage.

Audits

The audit repository is a host-provided, handler-scoped persistence port. Handlers may record meaningful operational or domain occurrences that the host may need to inspect later, such as provider rejection, exhausted fallback services, invalid webhook signatures, rejected refill requests, unsupported provider statuses, insufficient provider balance, synchronization inconsistencies, or manual administrator intervention.

Audits preserve evidence for later review. They are separate from debug logs, events, progress timelines, and insights:

• Result informs the immediate caller.
• Events notify listeners that something happened.
• Progress records delivery progress changes.
• Insights aggregate stored data into analysis.
• Audits preserve meaningful evidence for later inspection.

The host controls audit storage, retention, redaction, authorization, indexing, and presentation. The SDK does not automatically audit every Result::failure() or every event; the handler decides which occurrences are important enough to preserve. Avoid audit records for routine execution noise such as entering a method, request started, or loop iteration completed.

Events

Events support built-in EventType values and custom string values for extensions.

Charges And Payments

Charge carries the money item, current payment projections, and immutable payment history. Aggregate values such as paidAmount and balanceDue are useful for presentation and filtering, but hosts should keep ChargePayment records for audit trails, partial payment inspection, refunds, and accounting reconciliation.

Charges are owned by workflow targets, not by deliveries alone. Built-in target types cover plans, segments, and deliveries, and custom string types can represent future workflow objects without changing the Charge contract.

The charge lifecycle is bidirectional:

1. The handler creates or updates a Charge through ChargeUpdateHookContract.
2. The host persists and presents the charge to the client.
3. The client pays through host-owned checkout or wallet flows.
4. The host records the immutable ChargePayment.
5. The host notifies the handler with ChargePaymentNotificationContract.
6. The handler progresses its workflow and may emit updated charges, deliveries, plans, next actions, or management state.

The handler owns pricing logic, charge requirements, and workflow progression. The host owns payment gateways, client interaction, payment collection, and payment persistence. ChargeStateResolverContract remains available for reconciliation and recovery, but normal workflow progression should use payment notifications instead of polling.

ChargeTarget identifies what the charge belongs to. ChargePaymentNotification still identifies the order, charge, and payment, and may include chargeTarget when the host wants to echo the ownership context back to the handler.

Product Definitions

Product-definition catalogs are optional. Every definition has one canonical shape regardless of whether it comes from a handler, Studio, a host, or an import. A handler declaring the product_definition_catalog capability implements ProductDefinitionCatalogContract and returns root ProductDefinition objects directly.

The PHP DTO uses idiomatic constructor names and emits the canonical snake-case v1 wire keys. meta remains one opaque object on the wire even when ServiceMeta internally combines provider and host-derived values. Product fields do not have a component property; rendering descriptors belong to host integrations rather than ProductDefinition.

Insights

Insights, charts, UI manifest support, and private assets are product additions isolated from the mandatory DgpDriverContract except where a handler explicitly declares or implements the related capability.

The current package depends on elqora/chart because Analysis stores an Elqora\Chart\Charts\Chart directly. If a smaller core package becomes important, insights/chart support is the main candidate for extraction into an optional package or adapter layer.

Hooks & Event Ports

The DGP SDK specifies interfaces for asynchronous update hooks, payment notifications, and event dispatching. Charge updates flow from handler to host; payment notifications flow from host to handler after the host records payment state changes.

1. Charge Update Hook

Used by handlers/drivers to push charge requirements and charge state changes to the host platform. This remains the handler-to-host synchronization path for charge creation, amount changes, status changes, next actions, and metadata:

2. Charge Payment Notification

Used by hosts to notify handlers that a payment state change has been recorded. This is an opt-in handler contract and does not replace ChargeUpdateHookContract:

3. Charge State Resolver

Used for reconciliation and recovery when the host or handler needs to resolve current charge and payment state. It should not be the normal mechanism for discovering that payment happened:

4. Event Hook

A general, neutral channel for dispatching event telemetry (such as status updates or logs) from the driver to the host:

5. Webhook Receiver Contract

Unlike the outbound hooks above, WebhookContract is an inbound port implemented by the handler to parse and verify incoming HTTP notifications sent by the external provider:

Testing

composer check is the completion command. It runs the PHPUnit suite, PHPStan, Spec-fixture and dependency-boundary checks, and strict Composer validation. The committed contract fixtures are copied from dgp-spec v1 and are compared with a sibling Spec checkout when available.

To run a specific file: