PHPackages xterr/php-ubl-generator - 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. [Parsing & Serialization](/categories/parsing) 4. / 5. xterr/php-ubl-generator ActiveLibrary[Parsing & Serialization](/categories/parsing) xterr/php-ubl-generator ======================= UBL 2.x XSD-to-PHP 8.2+ code generator — produces typed classes with XML mapping attributes from OASIS XSD schemas 1.4.0(3mo ago)0431MITPHPPHP ^8.2CI passing Since Apr 10Pushed 3mo agoCompare [ Source](https://github.com/xterr/php-ubl-generator)[ Packagist](https://packagist.org/packages/xterr/php-ubl-generator)[ RSS](/packages/xterr-php-ubl-generator/feed)WikiDiscussions main Synced 3w ago READMEChangelog (7)Dependencies (11)Versions (8)Used By (1) PHP UBL Generator ================= [](#php-ubl-generator) [![PHP](https://camo.githubusercontent.com/ccaa43fc634d348cffccb1d8db7b55d9f17c5d46944bc99a15c3c982724b387d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![CI](https://github.com/xterr/php-ubl-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/xterr/php-ubl-generator/actions/workflows/ci.yml)[![Packagist Version](https://camo.githubusercontent.com/951724dd581b50f38440da224c33d22e178fb8c59a71850e6be91ad4ed3d5350/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f78746572722f7068702d75626c2d67656e657261746f72)](https://packagist.org/packages/xterr/php-ubl-generator)[![PHPStan Level 8](https://camo.githubusercontent.com/ff3c7f8c8667ce643f47e74532748f673482a5f95d7d4269f925f2eebbe5117e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e)](https://phpstan.org/) 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 -------- [](#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](http://docs.oasis-open.org/ubl/os-UBL-2.4/) and point the generator at them Installation ------------ [](#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 ----------- [](#quick-start) ### Generate classes from UBL schemas [](#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 [](#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 ------------- [](#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 ---------------- [](#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 [](#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 ------------------ [](#namespace-handling) All standard UBL 2.x namespaces are supported with universal resolution: NamespacePrefixOutputDescriptionCommonBasicComponents`cbc``Cbc/`Leaf types (value + attributes)SignatureBasicComponents`sbc``Cbc/`Signature leaf types (same pattern)CommonExtensionComponents`ext``Cbc/` or `Cac/`Leaf types → `Cbc/`, aggregates → `Cac/`CommonAggregateComponents`cac``Cac/`Aggregate types (child elements)SignatureAggregateComponents`sac``Cac/`Signature aggregate typesCommonSignatureComponents`sig``Cac/`Signature componentsTypes 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 ----------- [](#cli-options) OptionDescription`--config`, `-c`Path to YAML configuration file`--schema-dir`, `-s`Path to XSD schema directory`--schema-version`UBL schema version (2.1, 2.2, 2.3, 2.4)`--output-dir`, `-o`Output directory for generated classes`--namespace`Root PHP namespace`--codelist-dir`Path to directory containing `.gc` codelist files`--force`, `-f`Actually generate files (without this, dry-run only)Architecture ------------ [](#architecture) Two packages work together: PackageRoleInstall**[xterr/php-ubl-generator](https://github.com/xterr/php-ubl-generator)** (this)Dev-time code generator`composer require --dev`**[xterr/php-ubl](https://github.com/xterr/php-ubl)**Runtime XML mapping & serialization`composer require`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 ----------- [](#development) ``` # Install dependencies composer install # Run tests composer test # Run static analysis composer analyze ``` ### CI [](#ci) Tests run on PHP 8.2, 8.3, and 8.4 via GitHub Actions. Tagged releases are automatically notified to Packagist. License ------- [](#license) [MIT](LICENSE) — Copyright (c) 2026 Ceana Razvan ### Health Score 39 — LowBetter than 84% of packages Maintenance81 Actively maintained with recent releases Popularity8 Limited adoption so far Community8 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 7 Last Release 102d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/d9526b453abaa7d569fdacdf58cb0f55aa8d889f68f5b622344a28b37eb6c17d?d=identicon)[razvanceana](/maintainers/razvanceana) --- Top Contributors [![xterr](https://avatars.githubusercontent.com/u/619509?v=4)](https://github.com/xterr "xterr (23 commits)") --- Tags xmlcode generatorxsdublpeppole-invoicingoasisprocurementespd ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/xterr-php-ubl-generator/health.svg) ``` [![Health](https://phpackages.com/badges/xterr-php-ubl-generator/health.svg)](https://phpackages.com/packages/xterr-php-ubl-generator) ``` ### Alternatives [shopware/core Shopware platform is the core for all Shopware ecommerce products. 585.6M600](/packages/shopware-core)[jolicode/castor A lightweight and modern task runner. Automate everything. In PHP. 54643.3k4](/packages/jolicode-castor)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M754](/packages/sylius-sylius)[oro/platform Business Application Platform (BAP) 645143.5k116](/packages/oro-platform)[pimcore/pimcore Content & Product Management Framework (CMS/PIM/E-Commerce) 3.8k3.8M511](/packages/pimcore-pimcore)[open-dxp/opendxp Content & Product Management Framework (CMS/PIM) 9421.6k64](/packages/open-dxp-opendxp) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)