README

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

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

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

composer require magebitcom/ucp-php-spec

Usage

Two Interface Variants

This package generates two sets of interfaces:

Api - Immutable interfaces with getters only (read-only)
MutableApi - Mutable interfaces with getters and setters (read-write)

Using Immutable Interfaces (Api)

The Api namespace contains immutable interfaces with only getter methods:

<?php

use Magebit\UcpSpec\Api\Schemas\Shopping\OrderInterface;
use Magebit\UcpSpec\Api\Schemas\Shopping\Types\OrderLineItemInterface;

// Implement the immutable interface
class MyOrder implements OrderInterface
{
    public function getId(): string
    {
        return $this->orderId;
    }

    public function getLineItems(): array
    {
        return $this->lineItems; // OrderLineItemInterface[]
    }

    // ... implement other getter methods
}

Using Mutable Interfaces (MutableApi)

The MutableApi namespace contains mutable interfaces with both getters and setters:

<?php

use Magebit\UcpSpec\MutableApi\Schemas\Shopping\OrderInterface;
use Magebit\UcpSpec\MutableApi\Schemas\Shopping\Types\OrderLineItemInterface;

// Implement the mutable interface
class MyMutableOrder implements OrderInterface
{
    private string $orderId;
    private array $lineItems;

    public function getId(): string
    {
        return $this->orderId;
    }

    public function setId(string $id): self
    {
        $this->orderId = $id;
        return $this;
    }

    public function getLineItems(): array
    {
        return $this->lineItems;
    }

    public function setLineItems(array $lineItems): self
    {
        $this->lineItems = $lineItems;
        return $this; // Fluent interface for method chaining
    }

    // ... implement other getter and setter methods
}

Available Namespaces

Immutable (Api):

Magebit\UcpSpec\Api\Schemas\Shopping - Shopping and order interfaces
Magebit\UcpSpec\Api\Schemas\Shopping\Types - Common types
Magebit\UcpSpec\Api\Discovery - Discovery profile interfaces
Magebit\UcpSpec\Api\Services - Service definition interfaces

Mutable (MutableApi):

Magebit\UcpSpec\MutableApi\Schemas\Shopping - Shopping and order interfaces
Magebit\UcpSpec\MutableApi\Schemas\Shopping\Types - Common types
Magebit\UcpSpec\MutableApi\Discovery - Discovery profile interfaces
Magebit\UcpSpec\MutableApi\Services - Service definition interfaces

Type Safety

All interfaces include:

✅ Full PHP 8.1+ type hints
✅ Nullable types for optional properties
✅ Union types where applicable
✅ PHPDoc with array item types
✅ Fluent interface for setters (return self)

Immutable Interface Example (Api):

interface OrderInterface
{
    /**
     * Unique order identifier.
     *
     * @return string
     */
    function getId(): string;

    /**
     * Immutable line items — source of truth for what was ordered.
     *
     * @return OrderLineItemInterface[]
     */
    function getLineItems(): array;

    /**
     * Append-only event log of money movements.
     *
     * @return AdjustmentInterface[]|null
     */
    function getAdjustments(): array|null;
}

Mutable Interface Example (MutableApi):

interface OrderInterface
{
    function getId(): string;
    function setId(string $id): self;

    /**
     * @return OrderLineItemInterface[]
     */
    function getLineItems(): array;
    
    /**
     * @param OrderLineItemInterface[] $lineItems
     * @return self
     */
    function setLineItems(array $lineItems): self;

    /**
     * @return AdjustmentInterface[]|null
     */
    function getAdjustments(): array|null;
    
    /**
     * @param AdjustmentInterface[]|null $adjustments
     * @return self
     */
    function setAdjustments(?array $adjustments): self;
}

Regenerating Interfaces

If you need to regenerate the interfaces from the JSON Schema files (e.g., after updating the spec):

Prerequisites

PHP 8.1 or higher
Composer dependencies installed

Generate Command

# Generate interfaces from spec files
php generate.php

# Clean and regenerate all interfaces
php generate.php --clean

The generator automatically creates both Api (immutable) and MutableApi (mutable) namespaces in a single run.

Namespace Mapping

The generator preserves directory structure in namespaces and creates both immutable and mutable variants:

Spec File	Immutable Interface (Api)	Mutable Interface (MutableApi)
`spec/schemas/shopping/order.json`	`Magebit\UcpSpec\Api\Schemas\Shopping\OrderInterface`	`Magebit\UcpSpec\MutableApi\Schemas\Shopping\OrderInterface`
`spec/schemas/shopping/types/postal_address.json`	`Magebit\UcpSpec\Api\Schemas\Shopping\Types\PostalAddressInterface`	`Magebit\UcpSpec\MutableApi\Schemas\Shopping\Types\PostalAddressInterface`
`spec/discovery/profile_schema.json`	`Magebit\UcpSpec\Api\Discovery\UCPDiscoveryProfileInterface`	`Magebit\UcpSpec\MutableApi\Discovery\UCPDiscoveryProfileInterface`

Type Mapping

JSON Schema types are mapped to PHP as follows:

JSON Schema Type	PHP Type	PHPDoc Example
`string`	`string`	`@return string`
`integer`	`int`	`@return int`
`number`	`float`	`@return float`
`boolean`	`bool`	`@return bool`
`array`	`array`	`@return TypeInterface[]`
`object`	Interface	`@return InterfaceName`
`null`	`null`	`@return TypeInterface\|null`
`oneOf`/`anyOf`	Union	`@return string\|int`

Contributing

When updating the UCP specification:

Update JSON Schema files in spec/
Run php generate.php --clean to regenerate interfaces
Run composer dump-autoload to update autoloader
Test the generated interfaces
Commit both spec files and generated interfaces

License

MIT License - see LICENSE.md for details.

magebitcom / ucp-php-spec

Maintainers

Details