README

XSD-to-PHP code generator for UBL 2.x documents. Reads OASIS UBL schemas and emits typed PHP 8.2+ classes with XML mapping attributes, optional codelist enums from Genericode files, and configurable property bindings.

Features

• UBL 2.x Schemas — Supports versions 2.1, 2.2, 2.3, 2.4
• All UBL Namespaces — CBC, CAC, EXT, SBC, SIG, SAC with universal resolution
• Typed Classes — final class with private properties, typed getters, fluent setters
• PHP 8 Attributes — #[XmlRoot], #[XmlType], #[XmlElement], #[XmlAttribute], #[XmlValue]
• Codelist Enums — Parse OASIS Genericode (.gc) files into string-backed PHP enums with #[CodelistMeta]
• Union Type Bindings — Bind multiple codelist enums to a single property as PHP union types
• Setter Validation — Inline type checks, patterns, and enumeration validation
• Validator Attributes — Optional symfony/validator #[Assert\*] attribute generation
• Configurable — YAML config with namespace overrides, include/exclude filters, naming customization
• Bring Your Own Schemas — Download UBL schemas from OASIS and point the generator at them

Installation

composer require --dev xterr/php-ubl-generator

Generated classes depend on the runtime package:

composer require xterr/php-ubl

Requirements:

• PHP 8.2 or higher
• ext-dom
• ext-libxml
• ext-mbstring

Quick Start

Generate classes from UBL schemas

# Dry-run (show what would be generated)
php vendor/bin/php-ubl-generator ubl:generate --schema-dir=path/to/UBL-2.4/xsd

# Generate files
php vendor/bin/php-ubl-generator ubl:generate --schema-dir=path/to/UBL-2.4/xsd --force

# With codelist enums
php vendor/bin/php-ubl-generator ubl:generate \
  --schema-dir=path/to/UBL-2.4/xsd \
  --codelist-dir=path/to/codelists/gc \
  --force

# From YAML config
php vendor/bin/php-ubl-generator ubl:generate --config=ubl-generator.yaml --force

# Override namespace and output
php vendor/bin/php-ubl-generator ubl:generate \
  --schema-dir=path/to/UBL-2.4/xsd \
  --namespace='App\Ubl' \
  --output-dir=src/Ubl \
  --force

Generated output structure

src/
├── Cbc/            # Leaf types (Amount, Code, Text, Identifier, ...)
├── Cac/            # Aggregate types (Party, Address, TaxTotal, ...)
├── Doc/            # Document roots (Invoice, CreditNote, ...)
├── Enum/           # XSD restriction enumerations
└── Codelist/       # Codelist enums from .gc files (when configured)

Configuration

Copy the default config and customize:

cp vendor/xterr/php-ubl-generator/resources/config/ubl-generator.yaml.dist ubl-generator.yaml

schema_version: '2.4'
schema_dir: '/path/to/UBL-2.4/xsd'
output_dir: 'src'
namespace: 'App\UBL'

namespaces:
  cbc: 'Cbc'
  cac: 'Cac'
  doc: 'Doc'
  enum: 'Enum'

include: []                    # Glob patterns to include (empty = all)
exclude: []                    # Glob patterns to exclude

type_overrides: {}             # XSD type → PHP type
class_name_overrides: {}       # XSD type name → PHP class name
property_name_overrides: {}    # XSD element name → PHP property name

include_documentation: true
generate_validation: true
generate_validator_attributes: false
include_generated_tag: true

codelists:
  dir: ~                       # Path to .gc files (null = disabled)
  namespace: 'Codelist'
  name_overrides: {}           # listID → custom enum class name
  bindings: {}                 # XsdType.Element → listID or [listID1, listID2]

Codelist Support

Point the generator at a directory of OASIS Genericode (.gc) files to generate string-backed PHP enums:

codelists:
  dir: 'resources/codelists/gc'
  namespace: 'Codelist'
  name_overrides:
    'http://publications.europa.eu/resource/authority/country': 'CountryCode'

Generated enum:

use Xterr\UBL\Xml\Mapping\CodelistMeta;

#[CodelistMeta(listID: 'criterion-element-type', listAgencyID: 'OP', listVersionID: '4.1.0')]
enum CriterionElementType: string
{
    case QUESTION = 'QUESTION';
    case REQUIREMENT = 'REQUIREMENT';
    case CAPTION = 'CAPTION';
    // ...
}

Property Bindings

Bind codelist enums to specific XSD properties, replacing the default CBC Code type:

codelists:
  dir: 'resources/codelists/gc'
  bindings:
    # Single binding — property typed as one enum
    'TenderingCriterionPropertyType.TypeCode': 'criterion-element-type'
    'CountryType.IdentificationCode': 'http://publications.europa.eu/resource/authority/country'

    # Union binding — property accepts multiple enums
    'TenderingCriterionPropertyType.ExpectedCode':
      - 'boolean-gui-control-type'
      - 'financial-ratio-type'
      - 'http://publications.europa.eu/resource/authority/occupation'

Single bindings produce:

private ?CriterionElementType $typeCode = null;

Union bindings produce PHP union types:

private BooleanGUIControl|FinancialRatio|OccupationCode|null $expectedCode = null;

public function getExpectedCode(): BooleanGUIControl|FinancialRatio|OccupationCode|null
{
    return $this->expectedCode;
}

public function setExpectedCode(BooleanGUIControl|FinancialRatio|OccupationCode|null $expectedCode = null): self
{
    $this->expectedCode = $expectedCode;
    return $this;
}

Namespace Handling

All standard UBL 2.x namespaces are supported with universal resolution:

Types are classified structurally: complex types with simpleContent extensions become leaf classes in Cbc/, complex types with child element sequences become aggregate classes in Cac/.

CLI Options

Architecture

Two packages work together:

The generator reads XSD schemas and Genericode files, then emits PHP classes that use attributes from xterr/php-ubl. At runtime, only the lightweight xterr/php-ubl package is needed for XML serialization and deserialization.

Development

# Install dependencies
composer install

# Run tests
composer test

# Run static analysis
composer analyze

CI

Tests run on PHP 8.2, 8.3, and 8.4 via GitHub Actions. Tagged releases are automatically notified to Packagist.

License

MIT — Copyright (c) 2026 Ceana Razvan