instapro/schema-converter

Convert PHP types into schemas and cast values based on types.

1.0.0 2025-11-17 18:17 UTC

Requires

• php: >=8.4

Requires (Dev)

• doctrine/orm: ^3.5
• instapro/coding-standard: ^1.6
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4

MIT

README

Overview

This library provides functionality to convert PHP types into schemas and cast values based on types.

Installation

You can install the library via Composer:

composer require instapro/schema-converter

Usage

There are several schema converters that can be used to convert PHP types into schemas. Bellow an example using the most basic converter which can be used to convert primitive types:

$converter = new \Instapro\SchemaConverter\PrimitiveConverter();

echo json_encode($converter->toSchema('string')->toArray()); // {"type": "string"}

You can also cast values based on the schema:

$converter = new \Instapro\SchemaConverter\PrimitiveConverter();

var_dump($converter->castValue('string', 12.3)); // string(4) "12.3"

Supported converters

PrimitiveConverter

The primitive converter can be used to convert primitive types into schemas. Primitives can be array, string, int, float, bool, mixed, or null.

You can see examples of how to use the primitive converter in the previous section.

ObjectConverter

The object converter can be used to convert objects into schemas. The converter will recursively convert the properties of the object into schemas, but it will require you to define a converter to deal with that recursively.

For the following example, we'll let the converter handle the following class:

final readonly class Person
{
    public function __construct(
        public string $name,
        public int $age,
    ) {}
}

You can use the converter to get a schema of any class:

$converter = new \Instapro\SchemaConverter\ObjectConverter();
$converter->bindConverter(new \Instapro\SchemaConverter\PrimitiveConverter());

echo json_encode($converter->toSchema(Person::class)->toArray(), JSON_PRETTY_PRINT);

The code above will output the following schema:

{
  "type": "object",
  "parameters": {
    "name": {
      "required": true,
      "type": "string"
    },
    "age": {
      "required": true,
      "type": "int"
    }
  }
}

You can also cast values based on a type, as long you use the same format as the schema:

$converter = new \Instapro\SchemaConverter\ObjectConverter();
$converter->bindConverter(new \Instapro\SchemaConverter\PrimitiveConverter());

$person = $converter->castValue(Person::class, [
    'name' => 'John Doe',
    'age' => 30,
]);

echo $person->name; // John Doe

Disclosure: Note that this converter has a bindConverter instead of a constructor argument. This was designed to help with recursive conversions.

EntityConverter

The entity converter can be used to convert Doctrine entities into schemas.

$converter = new \Instapro\SchemaConverter\EntityConverter($entityManager);

echo json_encode($converter->toSchema(MyEntity::class)->toArray()); // {"type": "identifier"}   
echo $converter->castValue(MyEntity::class, 123)->id; // 123   

DateTimeConverter

The DateTimeConverter can handle objects that implement DateTimeIterface.

$converter = new \Instapro\SchemaConverter\DateTimeConverter();

echo json_encode($converter->toSchema(\DateTime::class)->toArray()); // {"type": "datetime"}
echo PHP_EOL;

$dateTime = $converter->castValue(\DateTime::class, '2021-01-01T00:00:00Z');
echo $dateTime->format('Y-m-d'); // 2021-01-01

EnumConverter

The EnumConverter can handle PHP enumerations.

$converter = new \Instapro\SchemaConverter\EnumConverter();

echo json_encode($converter->toSchema(MyEnum::class)->toArray()); // {"type": "enum", "values": ["VALUE1", "VALUE2"]}
echo PHP_EOL;

$enum = $converter->castValue(MyEnum::class, 'VALUE1');
echo $enum->getValue(); // VALUE1

EntityByKeyConverter

This converter handles Doctrine entities by their key properties.

$entityManager = // get your EntityManager instance
$converter = new \Instapro\SchemaConverter\EntityByKeyConverter(
    $entityManager,
    'postal_code',
    MyPostalCodeEntity::class,
    'postalCode'
);

echo json_encode($converter->toSchema(MyPostalCodeEntity::class)->toArray()); // {"type": "postal_code"}
echo PHP_EOL;

$entity = $converter->castValue(MyPostalCodeEntity::class, '1017BS');
echo $entity->postalCode; // 1017BS

JsonArrayConverter

This converter handles JSON arrays.

$converter = new \Instapro\SchemaConverter\JsonArrayConverter();

echo json_encode($converter->toSchema('array')->toArray()); // {"type": "json"}
echo PHP_EOL;

$array = $converter->castValue('array', '[1, 2, 3]');
print_r($array); // Array ( [0] => 1 [1] => 2 [2] => 3 )

CompositeConverter

There are several types of schemas that can be generated. For convenience, the library provides a CompositeConverter that can be used to convert multiple types of schemas.

$converter = new \Instapro\SchemaConverter\CompositeConverter(
    new \Instapro\SchemaConverter\PrimitiveConverter(),
    new \Instapro\SchemaConverter\DateTimeConverter(),
    new \Instapro\SchemaConverter\ObjectConverter(),
    new \Instapro\SchemaConverter\EntityConverter($entityManager);
);

echo json_encode($converter->toSchema(SomethingComplex::class)->toArray()); // {"type": "object", "parameters": {...}}

$somethingComplex = $converter->castValue(SomethingComplex::class, $complextData);
$somethingComplex->doSomething();

Note: The CompositeConverter will automatically call setConverter() for the ObjectConverter with itself.