PHPackages                             magebitcom/ucp-php-spec - 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. [Utility & Helpers](/categories/utility)
4. /
5. magebitcom/ucp-php-spec

ActiveLibrary[Utility & Helpers](/categories/utility)

magebitcom/ucp-php-spec
=======================

Universal Commerce Protocol specification for PHP

v1.0.2(6mo ago)127MITPHPPHP >=8.1CI passing

Since Jan 19Pushed 6d agoCompare

[ Source](https://github.com/magebitcom/ucp-php-spec)[ Packagist](https://packagist.org/packages/magebitcom/ucp-php-spec)[ RSS](/packages/magebitcom-ucp-php-spec/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (1)Versions (14)Used By (0)

UCP PHP Specification
=====================

[](#ucp-php-specification)

PHP interfaces for the Universal Commerce Protocol (UCP) specification. This package provides type-safe PHP interfaces automatically generated from the official UCP JSON Schema definitions.

About UCP
---------

[](#about-ucp)

The Universal Commerce Protocol (UCP) is a standardized protocol for commerce operations, providing a unified interface for shopping, checkout, payment, and fulfillment operations across different platforms and systems.

What's Included
---------------

[](#whats-included)

This package contains PHP interfaces for:

- **Shopping** - Cart, checkout, and order management
- **Payment** - Payment handlers, instruments, and credentials
- **Fulfillment** - Shipping, pickup, and delivery operations
- **Discovery** - Service discovery and capability negotiation

All interfaces are generated from the official UCP JSON Schema specifications located in the `spec/` directory.

Installation
------------

[](#installation)

```
composer require magebitcom/ucp-php-spec
```

Versioning
----------

[](#versioning)

SemVer, with one extra rule: **a new UCP spec target always means a new MAJOR.**

PartBumped when**MAJOR**New spec target, or a breaking change to emitted interfaces**MINOR**New interfaces or members, nothing existing changed**PATCH**Generator fix — same spec target, no new APISo `^1.0` means "built against UCP `2026-04-08`", and a generator bug is fixed as a patch that consumers can take without thinking.

LibraryUCP spec target`1.x``2026-04-08`The target lives in `composer.json` → `extra.ucp.spec-target`, and is copied into `spec.manifest.json` by the generator. The release workflow fails if they disagree, or if the target moved without a major bump.

Releasing
---------

[](#releasing)

Releases are cut by the **Release** GitHub Action, manual dispatch only — there is no tag-push or merge trigger, so releasing is always a deliberate act.

Run it from the Actions tab with:

- **version** — e.g. `1.2.0`, no leading `v`
- **spec\_target** — optional; must match what is already committed. It is a confirmation, not a way to change the target. To move the target, commit the change to `composer.json` first.
- **prerelease** / **dry\_run** — `dry_run` runs every gate and publishes nothing.

The job refuses to release unless: the version is valid semver and unused, `composer validate`passes, unit tests pass, `composer check` confirms `generated/` matches what `spec/` produces, and the two spec-target declarations agree with each other and with the major-bump rule.

Usage
-----

[](#usage)

### Two Interface Variants

[](#two-interface-variants)

This package generates two sets of interfaces:

1. **`Api`** - Immutable interfaces with getters only (read-only)
2. **`MutableApi`** - Mutable interfaces with getters and setters (read-write)

### Using Immutable Interfaces (Api)

[](#using-immutable-interfaces-api)

The `Api` namespace contains immutable interfaces with only getter methods:

```