Download the PHP package xterr/php-espd without Composer

PHP ESPD

Typed PHP classes for ESPD (European Single Procurement Document) based on ESPD-EDM v2.1.1–v4.1.0 / UBL 2.3.

Serialize and deserialize QualificationApplicationRequest and QualificationApplicationResponse documents without DOM code, with multi-version support (v2.1.1 through v4.1.0). Validate documents against the official OP-TED Schematron business rules with 1:1 compliance. Codelist values are PHP enums with full type safety, including union-typed properties for elements that span multiple codelists.

Features

• 325 Generated Classes — 2 document roots, 290 aggregate types, 8 leaf value types, 16 codelist enums, 5 XSD enums, 2 registries
• Business Rule Validation — Official OP-TED ESPD-EDM Schematron rules for v2.1.1, v3.3.0, v4.0.0, and v4.1.0 via SaxonC-HE XSLT processor, 1:1 compliant with the EU reference validator
• Codelist Enums — CriterionCode, CriterionElement, ResponseData, PropertyGroup, CountryCode, LanguageCode, and 10 more
• Union Enum Types — ExpectedCode resolves to BooleanGUIControl|FinancialRatio|OccupationCode based on listID at runtime
• Multi-Version Support — Deserialize and validate ESPD documents from v2.1.1, v3.3.0, v4.0.0, and v4.1.0. V2 long-form criterion codes automatically merge into the CriterionCode enum with V2_ prefix and bidirectional v2↔v4 mapping
• ESPD Part & Section Classification — CriterionCode::getPart() returns the EspdPart enum (I–VI per EU Regulation 2016/7), getSection() returns the sub-section letter (A–D, α) per Directive 2014/24/EU Articles 57–62
• Criterion Taxonomy — ESPD-criterion.xml ships as a resource, deserializable into the generated classes
• Full Round-Trip — serialize → deserialize produces identical object graphs

Installation

Requirements:

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

Optional (for validation):

• ext-saxonc — SaxonC-HE 12.x (free, MPL-2.0 license)

Quick Start

Deserialize an ESPD Request

Serialize to XML

Validate against EU business rules

Requires the ext-saxonc PHP extension (installation guide).

You can also validate raw XML strings directly:

Work with typed enums

Multi-version deserialization

The library supports ESPD documents from all major versions. V2 long-form criterion codes are automatically resolved:

Criterion Part & Section classification

Every criterion code knows its position in the ESPD form hierarchy defined by Commission Implementing Regulation (EU) 2016/7:

ESPD Form Parts (per EU Regulation 2016/7, Annex 2):

Union enum — ExpectedCode

ExpectedCode can hold values from three different codelists depending on the criterion context. The listID XML attribute acts as the runtime discriminator:

Load the criterion taxonomy

The full ESPD criterion tree ships as a resource:

Validation

The validation subsystem runs the official OP-TED/ESPD-EDM Schematron business rules via SaxonC-HE. This guarantees 1:1 compliance with the EU reference validator — identical rule IDs, severity levels, and error messages.

Multi-version validation

The validator supports 4 ESPD-EDM version families and automatically detects which rule set to apply based on the document's ProfileExecutionID:

Auto-detection (recommended) — the validator reads ProfileExecutionID from the XML and selects the matching rule set:

Explicit version — useful when the document lacks a ProfileExecutionID or you want to force a specific rule set:

If auto-detection fails (missing or unrecognized ProfileExecutionID), a ValidationException is thrown prompting you to specify the version explicitly.

What gets validated

Validation result API

Each Violation exposes:

Generated Structure

Codelist Enums

Codelist Bindings

These properties are typed with codelist enums instead of generic Code:

Installing SaxonC-HE

The ext-saxonc PHP extension is required only for validation. Serialization and deserialization work without it.

Docker (easiest)

macOS

For Intel Macs, replace arm64 with x86_64 in the download URL.

Linux (Ubuntu/Debian)

Verify

Schema Source

Generated from OP-TED/ESPD-EDM v4.1.0, which uses OASIS UBL 2.3 OS schemas. The XSD schemas and Genericode codelist files are in resources/ (not committed — dev-only). The pre-compiled Schematron XSL validation rules are bundled in resources/validation/ for all 4 version families (v2.1.1, v3.3.0, v4.0.0, v4.1.0). V2.1.1 codelist GC files are in resources/cl/gc/.

Regenerating

The php-espd CLI tool orchestrates the full code generation pipeline:

What it does

1. Parses criterion taxonomies — reads ESPD-EDM v2.1.1 and v4.1.0 taxonomy XML files
2. Cross-references UUIDs — matches v2 long-form codes to v4 short-form codes by criterion UUID (+ 6 manual EO_DATA equivalences for codes where v4 uses structured IDs instead of UUIDs)
3. Generates v2→v4 mapping file — writes resources/criterion/v2-to-v4-mapping.php (v2 → v4 lookup) 3b. Generates code-to-part mapping — parses criterionList.xml for exclusion/selection classification, resolves sub-sections from v2 code prefixes and EU Regulation 2016/7 Annex 2, writes resources/criterion/code-to-part.php
4. Generates Genericode file — writes resources/codelists/gc/CriteriaTypeCode.gc with all v2 codes
5. Runs UBL generator — regenerates all PHP classes, codelist enums, and registries from XSD schemas and Genericode files

The generator automatically merges v2 criterion codes into CriterionCode with a V2_ prefix and injects the CriterionCodeMethods trait for v2↔v4 conversion.

Options

Example output

Multi-version support

The generated CriterionCode enum contains both v4 short codes (crime-org, corruption, ...) and v2 long-form codes prefixed with V2_ (CRITERION.EXCLUSION.CONVICTIONS.PARTICIPATION_IN_CRIMINAL_ORGANISATION, ...). This allows deserializing ESPD documents from both v2.x and v4.x without data loss:

Development

EU Legislation References

The ESPD form structure and criterion classification are defined by EU legislation:

License

MIT - Copyright (c) 2026 Ceana Razvan