Extensible PHP library for defining and serializing Data Contracts using PHP Attributes or programmatically at runtime. Ships with Open Data Contract Standard (ODCS) support, extensible for custom standards.
Work in progress The API is stabilizing but may still change.
- PHP 8.2+
composer require thesameson/php-data-contractsAnnotate your classes with the package's attributes to export them as data contracts:
use DataContracts\Attribute\Contract;
use DataContracts\Attribute\Schema;
use DataContracts\Attribute\Field;
use DataContracts\ContractBuilder;
#[Contract('user-contract', version: '1.0.0', owner: 'data-team')]
#[Schema(name: 'Users', physicalName: 'users', physicalType: 'table')]
class User
{
#[Field(description: 'Primary key', primaryKey: true)]
public int $id;
#[Field(description: 'User email', required: true, format: 'email', maxLength: 255)]
public string $email;
#[Field(logicalType: 'timestamp', required: true)]
public string $createdAt;
}
$result = ContractBuilder::create('user-contract')
->addSource(User::class)
->toYaml('user-contract.yaml');The builder supports runtime enrichment and custom resolvers, all chainable:
use DataContracts\Config\ConfigurationBuilder;
use DataContracts\ContractBuilder;
use DataContracts\Extractor\Metadata\RawFieldMetadata;
use DataContracts\Model\Definition\ContractDefinition;
use DataContracts\Model\Definition\FieldDefinition;
use DataContracts\Resolver\Field\FieldResolverInterface;
use DataContracts\Resolver\Field\FieldResolutionResult;
use DataContracts\Resolver\ResolutionContext;
// Configuration: strict validation, alphabetical field ordering
$config = (new ConfigurationBuilder())
->strict()
->sortFieldsAlphabetically()
->build();
$result = ContractBuilder::create('user-contract', config: $config)
->addSource(User::class)
// Add fields at runtime without modifying the source class
->addField('Users', 'updatedAt', function (FieldDefinition $field) {
$field->setLogicalType('timestamp')
->setRequired(true);
})
// Enrichment: modify the contract/schema/field definition after extraction
->enrichContract(function (ContractDefinition $contract) {
$contract->setDescription('User accounts and profile data');
return $contract;
})
// Custom resolver: hook into the extraction pipeline (priority 100+)
// This example marks all "id" fields as "required"
->addFieldResolver(new class implements FieldResolverInterface {
public function getPriority(): int { return 100; }
public function supports(RawFieldMetadata $raw, ResolutionContext $ctx): bool
{
return $raw->name === 'id' || str_ends_with($raw->name, '_id');
}
public function resolve(
RawFieldMetadata $raw,
FieldDefinition $current,
ResolutionContext $ctx,
): FieldResolutionResult {
$current->setRequired(true);
return FieldResolutionResult::continue($current);
}
})
->toYaml();The built-in ODCS implementation covers fundamental contract, schema, and field properties. For ODCS properties that aren't modeled internally (e.g., classification, criticalDataElement), use customProperties - they are spread as top-level keys in the output:
#[Field(
logicalType: 'string',
required: true,
customProperties: [
'classification' => 'sensitive',
'criticalDataElement' => true,
],
)]
public string $email;The same works programmatically via setCustomProperties() on any definition object, or at the schema/contract level through #[Schema(customProperties: [...])] and #[Contract(customProperties: [...])].
| Concept | Description |
|---|---|
| Attributes | #[Contract], #[Schema], #[Field] declare metadata directly on PHP classes and properties |
| Resolvers | Transform raw extracted metadata into normalized definitions (e.g., physical -> logical type mapping) |
| Enrichment | Runtime callbacks to add, modify, or remove fields/schemas after extraction |
| Standards | Pluggable output standards. ODCS ships built-in, implement StandardInterface for custom ones |
| Serializers | Output to YAML, JSON, or array or bring your own SerializerInterface |
MIT