https://github.com/apioo/psx-schema
TypeSchema parser, object mapper and DTO generator
https://github.com/apioo/psx-schema
code-generator dto json-schema object-mapper php popo typeschema
Last synced: 3 days ago
JSON representation
TypeSchema parser, object mapper and DTO generator
- Host: GitHub
- URL: https://github.com/apioo/psx-schema
- Owner: apioo
- License: apache-2.0
- Created: 2016-03-31T13:05:11.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2025-03-23T20:11:46.000Z (about 2 months ago)
- Last Synced: 2025-05-03T11:03:08.982Z (15 days ago)
- Topics: code-generator, dto, json-schema, object-mapper, php, popo, typeschema
- Language: PHP
- Homepage: https://typeschema.org/
- Size: 1.95 MB
- Stars: 56
- Watchers: 5
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Schema
This library helps you to work with fully typed objects, it provides the following features:
* Transform raw JSON data into fully typed objects
* Parse PHP classes into a [TypeSchema](https://typeschema.org/) specification
* Generate DTOs in different languages like TypeScript, Java, C# etc.
We provide also a hosted version of this [code generator](https://typeschema.org/generator).
For more integration options you can also take a look at the [SDKgen](https://sdkgen.app/) project
which provides a CLI binary or GitHub action to integrate the code generator.
## Object mapper
This example reads raw JSON data and transform it into the provided `Person` class.
```php
$json = <<<'JSON'
{
"firstName": "Ludwig",
"lastName": "Beethoven",
"age": 254
}
JSON;
$objectMapper = new ObjectMapper(new SchemaManager());
$person = $objectMapper->readJson($json, SchemaSource::fromClass(Person::class));
assert('Ludwig' === $person->getFirstName());
assert('Beethoven' === $person->getLastName());
assert(254 === $person->getAge());
$json = $objectMapper->writeJson($person);
```
Besides a simple class there are multiple ways to specify a source, for example to parse
an array of persons s.
```php
$json = <<<'JSON'
[
{
"firstName": "Ludwig",
"lastName": "Beethoven",
"age": 254
}
]
JSON;
$objectMapper = new ObjectMapper(new SchemaManager());
$personList = $objectMapper->readJson($json, SchemaSource::fromType('array'));
assert(1 === count($personList));
assert('Ludwig' === $personList[0]->getFirstName());
$json = $objectMapper->writeJson($person);
```
## Code generation
It is possible to transform any DTO class into a [TypeSchema](https://typeschema.org/) specification.
This schema can then be used to generate DTOs in different languages which helps to work with
type-safe objects across different environments.
```php
$schemaManager = new SchemaManager();
$factory = new GeneratorFactory();
$schema = $schemaManager->getSchema(Person::class);
$generator = $factory->getGenerator(GeneratorFactory::TYPE_JAVA, Config::of('org.typeschema.model'));
$result = $generator->generate();
$result->writeTo('/my_model.zip');
```
## TypeSchema specification
It is possible to transform an existing [TypeSchema](https://typeschema.org/) specification into a PHP DTO class.
For example lets take a look at the following specification, which describes a person:
```json
{
"definitions": {
"Person": {
"type": "struct",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"age": {
"description": "Age in years",
"type": "integer"
}
}
}
},
"root": "Person"
}
```
It is then possible to turn this specification into a ready-to-use PHP class s.
```php
$schemaManager = new SchemaManager();
$factory = new GeneratorFactory();
$schema = $schemaManager->getSchema(__DIR__ . '/my_schema.json');
$generator = $factory->getGenerator(GeneratorFactory::TYPE_PHP, Config::of('App\\Model'));
$result = $generator->generate();
foreach ($result as $file => $code) {
file_put_contents(__DIR__ . '/' . $file, 'firstName = $firstName;
}
public function getFirstName() : ?string
{
return $this->firstName;
}
public function setLastName(?string $lastName) : void
{
$this->lastName = $lastName;
}
public function getLastName() : ?string
{
return $this->lastName;
}
public function setAge(?int $age) : void
{
$this->age = $age;
}
public function getAge() : ?int
{
return $this->age;
}
public function toRecord() : \PSX\Record\RecordInterface
{
/** @var \PSX\Record\Record $record */
$record = new \PSX\Record\Record();
$record->put('firstName', $this->firstName);
$record->put('lastName', $this->lastName);
$record->put('age', $this->age);
return $record;
}
public function jsonSerialize() : object
{
return (object) $this->toRecord()->getAll();
}
}
```
Every generated PHP class implements also the `JsonSerializable` interface so you can simply encode an object to json.
```php
$person = new Person();
$person->setFirstName('foo');
$person->setLastName('bar');
$person->setAge(32);
echo json_encode($person);
// would result in
// {"firstName": "foo", "lastName": "bar", "age": 32}
```
## Attributes
The following attributes are available:
| Attribute | Target | Example |
|---------------|----------------|-----------------------------------------|
| Deprecated | Property | #[Deprecated(true)] |
| DerivedType | Class | #[DerivedType(Person::class, 'person')] |
| Description | Class/Property | #[Description("content")] |
| Discriminator | Class | #[Discriminator('type')] |
| Exclude | Property | #[Exclude] |
| Format | Property | #[Format('date-time')] |
| Key | Property | #[Key('my-complex-name')] |
| Nullable | Property | #[Nullable(true)] |